Flavored logging offering story-driven primitives: single-event notes and contextual scrolls, best-effort non-suspending variants, customizable note/scroll/entry savers, and scroll lifecycle enrichment via margins.
A flavored Kotlin Multiplatform logging library
Scribe is a Kotlin Multiplatform logging library built around the ideas from loggingsucks.com, so structured logs can model both single events and longer contextual flows.
newScroll(...) and immediate-seal one-shot scrollsArchivist instances receiving Entry snapshotsAdd Scribe to your commonMain dependencies:
kotlin {
sourceSets {
commonMain.dependencies {
implementation("com.rafambn:scribe:0.6.0")
}
}
}
Create a Scribe object, start processing its private buffer, and emit a scroll:
object AppScribe : Scribe() {
override val archivists: List<Archivist> = listOf(
Archivist { entry ->
println(entry)
}
)
}
AppScribe.hire()
val scroll = AppScribe.newScroll()
scroll["tag"] = JsonPrimitive("payments")
scroll["message"] = JsonPrimitive("starting checkout")
scroll["level"] = JsonPrimitive("INFO")
scroll.seal(AppScribe)
Use a scroll when you need shared context for a longer flow:
object BillingScribe : Scribe() {
override val archivists: List<Archivist> = listOf(
Archivist { entry -> println(entry) }
)
override val imprint = mapOf(
"service" to JsonPrimitive("billing"),
"environment" to JsonPrimitive("production"),
)
}
BillingScribe.hire()
scroll = BillingScribe.newScroll(id = )
scroll[] = JsonPrimitive()
scroll[] = JsonPrimitive()
scroll[] = JsonPrimitive()
scroll.seal(BillingScribe)
Each Scribe object has independent configuration and delivery lifecycle. A Scroll is a mutable JSON-element map initialized by newScroll(...); pass the runtime that should enrich and deliver it to scroll.seal(scribe). Each seal(...) call emits a separate snapshot of the scroll data.
For JVM applications, add the SLF4J provider:
dependencies {
implementation("com.rafambn:scribe-slf4j:0.6.0")
}
Select exactly one application-wide backend with @ScribeBackend:
@ScribeBackend
object AppScribe : Slf4jScribe() {
override val bufferCapacity = 1_024
override bufferOverflow = BufferOverflow.DROP_OLDEST
onArchiveFailure: ((Archivist, Entry, Throwable) -> )? =
archivists = listOf(
Archivist { entry -> println(entry) },
)
: = level.toInt() >= Level.INFO.toInt()
}
The provider discovers the annotated backend once on the first SLF4J access and registers a JVM shutdown hook. Intake starts open, so early calls accumulate in the private buffer; the application calls AppScribe.hire() when processing should begin. The shutdown hook retires the Scribe and drains accepted entries automatically. Initialization fails with a descriptive error when no backend is present, multiple backends are annotated, or the annotation is not placed on a Kotlin object extending Slf4jScribe.
scribe-slf4j is a standalone SLF4J provider. Do not include another provider such as logback-classic in the same runtime classpath.
See the full documentation for lifecycle controls, overflow behavior, margins, and SLF4J field mapping.
Scribe is designed for high-throughput and thread-safe concurrent logging.
The repository includes JVM throughput tests for concurrent in-memory ingestion and serialized file writing. Results depend on the machine, runtime, buffer configuration, and archivist implementation; run the tests in your target environment before using them for capacity planning.
MarginScribe objects for applications and imported librariesSurfaced from shared tags and platforms — no rankings paid for.