kotlinx-logger

Installation · Quick start · Contents · Integrations

kotlinx-logger is a Kotlin Multiplatform logging library. It supports global, thread-local, and coroutine contexts, lazy message evaluation, customizable pipelines, and hierarchical per-logger configuration driven by dotted logger names. The JVM integration module also provides interoperability with JUL and SLF4J.

• One API, every target — a consistent logging API across Kotlin Multiplatform targets
• Structured contexts — global (GlobalLogContext), thread-local (ThreadLogContext), and coroutine (CoroutineLogContext) contexts
• Lazy by default — a logging DSL that avoids constructing messages before level filtering
• Composable pipelines — a LogPipeline for filtering, transforming, formatting, emitting records, async processing, and everything
• Hierarchical configuration — levels and pipelines inherited along dotted logger names, so a whole package can be configured at startup
• Formatters — included text formatting plus Gson and Jackson JSON formatters for the JVM. Also, you can create your own.
• Safe with untrusted input — control characters are escaped so a request value cannot forge a log line, credential-looking keys are redacted by default, captured bodies are bounded, and a failing pipe never reaches the code that logged the record
• Integrations — Koin, Ktor, OkHttp, OpenTelemetry, and Sentry
• Drops into existing stacks — a JUL handler and an SLF4J 2 provider

• Modules and supported platforms
• Installation
• Quick start
• Creating a logger — immediate · lazy & delegates · hierarchical configuration
• Logging — string overloads · lazy DSL · generic log
• Log contexts — immutable & mutable · global & thread-local · coroutine
• LogRecord and metadata
• Handling untrusted input
• Pipelines — management · built-in pipes · custom pipes
• JVM JSON formatters — Gson · Jackson 3
• JVM logging interoperability — SLF4J 2 · JUL
• Integration modules — Koin · Ktor · OkHttp · Sentry · OpenTelemetry
• License

The Multiplatform modules target JVM 11, Android, JS (browser and Node.js, ES2015), macOS Arm64, iOS Arm64/x64/Simulator Arm64, watchOS Arm64/Simulator Arm64, tvOS Arm64/Simulator Arm64, Linux x64/Arm64, and Windows MinGW x64.

Add Maven Central, set the version shown in the badge above or on Maven Central, and include only the modules you need.

// build.gradle.kts
repositories {
    mavenCentral()
}

dependencies {
    implementation("kim.jade:kotlinx-logger:<version>")
}

val kotlinxLoggerVersion = "<version>"

dependencies {
    implementation("kim.jade:kotlinx-logger:$kotlinxLoggerVersion")

    implementation("kim.jade:kotlinx-logger-integration-gson:$kotlinxLoggerVersion")
    implementation("kim.jade:kotlinx-logger-integration-jackson:$kotlinxLoggerVersion")
    implementation("kim.jade:kotlinx-logger-integration-jvm:$kotlinxLoggerVersion")
    implementation("kim.jade:kotlinx-logger-integration-koin:$kotlinxLoggerVersion")
    implementation("kim.jade:kotlinx-logger-integration-ktor:$kotlinxLoggerVersion")
    implementation("kim.jade:kotlinx-logger-integration-okhttp:$kotlinxLoggerVersion")
    implementation("kim.jade:kotlinx-logger-integration-opentelemetry:$kotlinxLoggerVersion")
    implementation("kim.jade:kotlinx-logger-integration-sentry:$kotlinxLoggerVersion")
}

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("kim.jade:kotlinx-logger:$kotlinxLoggerVersion")
        }
    }
}

import kim.jade.kotlinx.logger.Logger

class OrderService {
    private val logger by Logger

    fun create(orderId: String) {
        logger.info {
            meta = mapOf("orderId" to orderId)
            "order created"
        }
    }
}

The default output has the following form. The timestamp and logger name vary at runtime.

2026-08-05T08:00:00Z [main] INFO  com.example.OrderService            - order created (orderId=A-100)

When private val logger by Logger is declared as a class member, the logger name is the class's qualified name. The default global level is INFO, and the default pipeline runs in this order:

LoggerNameShortener -> TextFormatter -> StdOutSink

val byName = Logger.named("payment")
val byClass = Logger.typed(PaymentService::class)
val byType = Logger.typed<PaymentService>()

// JVM only
val byJavaClass = Logger.typed(PaymentService::class.java)

named(name) caches instances by name, so calls with the same name return the same logger. The Kotlin typed variants use the qualified name and then the simple name, while the JVM Class overload uses the canonical name. They fall back to Logger.defaultLoggerName when no name is available.

Registered loggers inherit their level and pipeline along the dotted segments of their name — see Hierarchical configuration.

Call the constructor directly when you need an uncached logger. It still inherits from registered ancestors, but is not itself registered, so it never becomes anyone's ancestor.

val auditLogger = Logger(
    name = "audit",
    level = LogLevel.INFO,
    pipeline = auditPipeline,
)

val namedLogger by Logger.lazy("payment")
val classLogger by Logger.lazy(PaymentService::class)
val typedLogger by Logger.lazy<PaymentService>()

class PaymentService {
    private val logger by Logger // PaymentService's qualified name
}

private val topLevelLogger by Logger // Logger.defaultLoggerName

Logger names form a hierarchy split on ., the way java.util.logging treats packages. A logger that declares neither a level nor a pipeline inherits them from the nearest registered ancestor, ending at Logger.root, which falls back to Logger.defaultLevel and Logger.defaultPipeline.

Logger.defaultLevel = LogLevel.INFO
Logger.configure("com.example.payment") { level = LogLevel.DEBUG }

Logger.named("com.example.payment.CardService").level   // DEBUG, inherited
Logger.named("com.example.order.OrderService").level    // INFO, from the default

Logger.configure(name) { } creates and registers the logger if it does not exist yet, so a whole package can be configured at startup before any of its loggers has been touched.

Logger.configure("com.example.payment") {
    configurePipelineFromParent { installBefore(FilterPipe { it.meta["pii"] != true }, TextFormatter) }
}

Every level function accepts a message and optional properties directly.

logger.trace("trace message")
logger.debug("cache miss", meta = mapOf("key" to cacheKey))
logger.info("order created")
logger.warning("retrying request", exception = cause)
logger.error(
    message = "payment failed",
    exception = cause,
    eventName = "payment.failed",
    meta = mapOf("paymentId" to paymentId),
    context = requestContext,
)
logger.fatal("service cannot continue", exception = cause)

trace, debug, info, warning, error, and fatal all accept the same parameters.

[!NOTE] An explicit context replaces the automatically captured context; it is not added to it.

logger.debug {
    exception = cause
    eventName = "query.failed"
    meta = mapOf("query" to expensiveQueryDescription())
    context = requestContext

    "query failed"
}

The DSL body is not evaluated when its level is disabled. Prefer this form when constructing the message or metadata is expensive. Inside the body, you can set exception, eventName, meta, and context; the final expression must be the message String.

logger.log(
    level = LogLevel.INFO,
    message = "manual log",
    meta = mapOf("source" to "batch"),
)

logger.log(LogLevel.DEBUG) {
    meta = mapOf("jobId" to jobId)

    "job started"
}

val record = LogRecordData(
    loggerName = "importer",
    level = LogLevel.WARNING,
    body = "invalid row",
    eventName = "import.invalid-row",
    meta = mapOf("row" to 42),
)
logger.log(record)

Context data is stored in LogRecord.context as a Map<String, Any?>. The default TextFormatter displays meta but not context. Context remains available to JSON formatters, Sentry, and custom pipes.

val immutable = LogContext(
    "tenantId" to "tenant-a",
    "region" to "kr",
)

val mutable = MutableLogContext(
    "requestId" to "req-100",
)
mutable.putAll(mapOf("userId" to 7, "role" to "admin"))

Both factories accept either a Map<String, Any?> or key/value Pair arguments. Input data is copied, so subsequent changes to the source map do not affect the context. When keys overlap, the value on the right-hand side of + wins.

val base = LogContext("tenant" to "a", "region" to "kr")
val override = LogContext("region" to "us")
val merged = base + override // region == "us"

val mutableMerged = MutableLogContext("a" to 1) + mapOf("b" to 2)
mutableMerged += mapOf("c" to 3)

GlobalLogContext["service"] = "checkout"
ThreadLogContext["requestId"] = requestId //persistently on the thread

withThreadLogContext("requestId" to requestId) { //will be cleared after out this block
    logger.info("request received")
}

withThreadLogContext restores whatever was bound to the thread before the block, including writes made inside it, so nothing survives into the next task that borrows the same thread.

snapCurrentLogContext() returns an immutable snapshot of GlobalLogContext + ThreadLogContext. Thread-local values win when keys overlap.

val snapshot = snapCurrentLogContext()

// Intentionally exclude the automatic global and thread-local contexts.
logger.info("health check", context = EmptyLogContext)

[!WARNING] ThreadLogContext has no natural end of its own. On a pooled thread — a servlet container, an executor, a Dispatchers.Default worker — whatever the previous task left behind is still attached when the next one starts, so one caller's user id ends up on another caller's log lines. Scope every write with withThreadLogContext, or use the coroutine propagation utility below. Writing through the SLF4J MDC goes to the same thread-local storage and needs the same treatment.

Install CoroutineLogContext with withContext and call withCoroutine() in the logging DSL to merge the current coroutine values into the record.

import kotlinx.coroutines.withContext

suspend fun runJob(jobId: String) {
    val coroutineLogContext = CoroutineLogContext(
        mapOf("jobId" to jobId)
    )

    withContext(coroutineLogContext) {
        logger.info {
            withCoroutine()

            "job started"
        }
    }
}

On the JVM, combine both context elements when ThreadLogContext must also follow coroutine thread switches.

withContext(
    CoroutineThreadLogContext() +
            CoroutineLogContext(mapOf("jobId" to jobId))
) {
    logger.info {
        withCoroutine()
        "running on a coroutine"
    }
}

LogRecord is the data contract processed by the pipeline.

logger.error {
    exception = cause
    meta = mapOf(
        "exception" to cause.asLogObject(),
        "operation" to "charge",
    )

    "charge failed"
}

LogPipeline starts each record at the first LogPipe in installation order. A pipe controls the rest of the pipeline through apply(record, next): call next(record) to continue, call next(transformedRecord) to continue with a replacement, or do not call next to stop. Calling next more than once runs the downstream pipes once per call, which can be useful for deliberate fan-out; otherwise, call it at most once.

Logger.defaultPipeline = LogPipeline()
    .install(FilterPipe { record -> record.context["healthCheck"] != true })
    .install(LoggerNameShortener(preferLength = 30))
    .install(TextFormatter(printMeta = true, enableColor = true))
    .install(StdOutSink(printStackTrace = true, useStdErr = false))

[!IMPORTANT] Install serializers and formatters before StdOutSink. StdOutSink only prints SerializedLog.String records.

val pipeline = LogPipeline()
    .install(TextFormatter())
    .install(StdOutSink())
val customSink = SinkPipe { record -> println(record.body) }

pipeline.install(FilterPipe { it.level != LogLevel.TRACE }, index = 0)
pipeline.installBefore(MapPipe(::enrich), TextFormatter)
pipeline.installAfter(customSink, StdOutSink)

pipeline.isInstalled(TextFormatter)      // true
pipeline.installIndexOf(TextFormatter)   // -1 if absent
pipeline.uninstall(MapPipe)              // Remove every pipe with the same key
pipeline.uninstall(0)                    // Remove one pipe by index
pipeline.handle(record)                  // Run the pipeline directly
pipeline.clear()                         // Remove all pipes

LoggerNameShortener, RedactPipe, and SanitizePipe cannot be installed more than once with the same key and only transform LogRecordData records — install them before a formatter, which replaces the record with a serialized one. To format a record without running a pipeline, call TextFormatter(...).format(record). When installed as a pipe, the formatter passes that result to next.

The following example uses MapPipe to modify a record.

fun enrich(record: LogRecord): LogRecord =
    if (record is LogRecordData) {
        record.copy(meta = record.meta + ("environment" to "production"))
    } else {
        record
    }

class SinkPipe(
    private val sink: (LogRecord) -> Unit,
) : LogPipe {
    companion object Key : LogPipe.Key<SinkPipe>

    override val key: LogPipe.Key<out LogPipe> = Key

    override fun apply(record: LogRecord, next: (LogRecord) -> Unit) {
        sink(record)
        next(record) // Omit this call to stop the pipeline here.
    }
}

Logger.defaultPipeline.installBefore(
    SinkPipe { record -> println("custom sink: ${record.body}") },
    TextFormatter,
)

Override LogPipe.addTo(pipeline, index) to change a pipe's installation policy. The default implementation replaces pipes with the same key, then inserts the new pipe at the requested position. apply(record, next) is invoked by the pipeline and normally does not need to be called directly.

The Gson and Jackson formatters are provided by separate JVM integration modules. Add the corresponding artifact from Installation, then import the formatter from its package.

import kim.jade.kotlinx.logger.integration.gson.GsonFormatter

Logger.defaultPipeline = LogPipeline()
    .install(LoggerNameShortener())
    .install(GsonFormatter(traceLimit = 12))
    .install(StdOutSink(printStackTrace = false))

import kim.jade.kotlinx.logger.integration.jackson.JacksonFormatter

Logger.defaultPipeline = LogPipeline()
    .install(LoggerNameShortener())
    .install(JacksonFormatter(traceLimit = 12))
    .install(StdOutSink(printStackTrace = false))

Add the kotlinx-logger-integration-jvm artifact to use the JUL and SLF4J integrations in this section.

The JVM integration artifact includes an SLF4J service provider for standard LoggerFactory logging. Add a compatible 2.x release of org.slf4j:slf4j-api as a direct dependency if your application does not already provide it. The basic MDC key/value functions are backed by ThreadLogContext.

import org.slf4j.LoggerFactory
import org.slf4j.MDC

val slf4jLogger = LoggerFactory.getLogger("legacy-component")

try {
    MDC.put("requestId", requestId)
    slf4jLogger.info("received order {}", orderId)
} finally {
    MDC.clear()
}

You can also instantiate KotlinxLoggerAdapter with either a core Logger or a name, or create KotlinxLoggerFactory and KotlinxLoggerMdcAdapter directly. LoggerFactory and MDC normally load them automatically. Avoid placing another SLF4J provider on the same classpath.

When kotlinx-logger-integration-jvm is on the classpath, the core Logger discovers the JUL initializer during first initialization and adds a JulLogger handler to the root JUL logger. JUL records are then passed to the same LogPipeline.

Logger.named("bootstrap") // Initialize the core logger and load the JUL integration

val julLogger = java.util.logging.Logger.getLogger("legacy-component")
julLogger.info("message from JUL")

[!NOTE] Existing root handlers are retained and may print the same records, so adjust the root handler configuration if you want to avoid duplicate output. JUL logger and handler levels still determine which records reach the pipeline.

import kim.jade.kotlinx.logger.integration.koin.KoinLogger
import org.koin.core.context.startKoin

startKoin {
    logger(KoinLogger())
    modules(appModule)
}

The default core logger name used by KoinLogger() is KoinApplication. You can also supply a logger explicitly.

logger(KoinLogger(Logger.named("dependency-injection")))

import io.ktor.server.application.install
import io.ktor.server.request.header
import kim.jade.kotlinx.logger.integration.ktor.LogContext as KtorLogContext

install(KtorLogContext) {
    includedHeaders = setOf("X-Request-Id", "Accept-Language")
    setupContext = { context ->
        context["tenantId"] = request.header("X-Tenant-Id")
    }
}

The plugin adds the call ID, HTTP method, path, and route to CoroutineLogContext and runs request handling in that coroutine context. The default setupContext also adds remoteAddress and userAgent; the current remoteAddress value comes from request.host().

Headers are copied only when named in includedHeaders, matched case-insensitively. The context is attached to every record a call produces, and request headers routinely carry Authorization, Cookie, or X-API-Key, so copying all of them would write those credentials to each sink and to every service the pipeline forwards to. RedactPipe still redacts a credential-looking header if one is named here, but it cannot recognize headers that are merely sensitive.

[!NOTE] Assigning a new lambda to setupContext, as above, replaces the default lambda, so add any required default values yourself.

import io.ktor.server.application.install
import io.ktor.server.request.path
import kim.jade.kotlinx.logger.integration.ktor.RequestLogger

install(RequestLogger) {
    logger = Logger.named("http-server")
    logLevel = { call ->
        if (call.request.path() == "/health") null else LogLevel.INFO
    }
    canLogBody = { false }
    additionalMeta = { meta ->
        meta["host"] = request.host()
    }
}

When a response is sent, the plugin logs the status, method, path, and processing time, and adds path parameters and query parameters to meta as maps — keyed by parameter name, so RedactPipe redacts a token passed as a query parameter the same way it redacts a header. For 302 Found responses, it also appends the Location header to the message. Requests for which logLevel returns null are not logged.

Use the following functions for per-route control:

routing {
    get("/health") {
        disableRequestLog()
        call.respondText("ok")
    }

    post("/debug/users") {
        enableRequestLog()
        logBody(true)
        // ...
    }
}

[!CAUTION] Restrict body and header logging carefully to avoid recording passwords, tokens, or personal data. RedactPipe covers values it can recognize by key; it cannot recognize a secret inside a request body.

import kim.jade.kotlinx.logger.integration.okhttp.OkHttpLogInterceptorFactory
import okhttp3.OkHttpClient
import okhttp3.logging.HttpLoggingInterceptor

Logger.defaultLevel = LogLevel.DEBUG

val client = OkHttpClient.Builder()
    .addInterceptor(
        OkHttpLogInterceptorFactory.create(
            clientName = "backend",
            logLevel = LogLevel.DEBUG,
            interceptLevel = HttpLoggingInterceptor.Level.BASIC,
        )
    )
    .build()

This adapter forwards the text lines produced by OkHttp's official interceptor to kotlinx-logger at the selected LogLevel.

Use OkHttpLogger when you want request and response details recorded as structured metadata.

import kim.jade.kotlinx.logger.LogLevel
import kim.jade.kotlinx.logger.integration.okhttp.OkHttpLogger
import okhttp3.OkHttpClient

val structuredClient = OkHttpClient.Builder()
    .addInterceptor(
        OkHttpLogger(
            clientName = "backend",
            option = OkHttpLogger.HttpLogOption(
                successLogLevel = LogLevel.INFO,
                includeRequestHeaders = true,
                includeResponseHeaders = true,
            ),
        )
    )
    .build()

OkHttpLogger.HttpLogOption controls success and failure levels, header and body capture, and whether request and response data are combined in one record. Header and body capture are disabled by default; enable them only when sensitive values are excluded.

maxBodyBytes (32 KiB by default) bounds what a captured body costs. A response is buffered only up to that many bytes and a gzipped one is decompressed no further, so a large response — or a small one that expands into a large one — cannot be pulled into memory whole; the captured value is marked as truncated. A request body whose declared length is over the limit is skipped rather than buffered. The response itself is untouched and still readable by the caller.

val request = Request.Builder()
    .url(url)
    .tag(
        LogContext::class.java,
        LogContext("requestId" to requestId),
    )
    .build()

Initialize Sentry before installing SentrySink.

import io.sentry.Sentry
import kim.jade.kotlinx.logger.integration.sentry.SentrySink

Sentry.init { options ->
    options.dsn = System.getenv("SENTRY_DSN")
}

Logger.defaultPipeline.install(SentrySink())

By default, SentrySink forwards records at WARNING or a more severe level. Pass a custom isAcceptable predicate to change the threshold.

kotlinx-logger-integration-opentelemetry is a JVM module that provides bridges in both directions between kotlinx-logger and the OpenTelemetry Logs API.

Initialize the OpenTelemetry SDK, then install OpenTelemetrySink. Its constructor accepts either OpenTelemetry or an OpenTelemetry LoggerProvider.

import kim.jade.kotlinx.logger.integration.opentelemetry.OpenTelemetrySink

//val openTelemetry = ...

Logger.defaultPipeline.install(OpenTelemetrySink(openTelemetry))

OpenTelemetrySink forwards the logger name, severity, timestamps, body, exception, event name, and LogRecord.meta as attributes; LogRecord.context is not mapped. A metadata value that is neither a primitive nor a container is converted by reflecting over its public properties, bounded by depth and by a check for values that refer back to themselves.

Use OTelKotlinxLoggerProvider as an OpenTelemetry LoggerProvider to pass records created with the OpenTelemetry Logs API to the core Logger and LogPipeline.

import io.opentelemetry.api.common.AttributeKey
import io.opentelemetry.api.logs.Severity
import kim.jade.kotlinx.logger.integration.opentelemetry.OTelKotlinxLoggerProvider

val otelLogger = OTelKotlinxLoggerProvider()
    .loggerBuilder("checkout")
    .setInstrumentationVersion("1.0.0")
    .build()

otelLogger.logRecordBuilder()
    .setSeverity(Severity.INFO)
    .setEventName("order.created")
    .setBody("order created")
    .setAttribute(AttributeKey.stringKey("order.id"), orderId)
    .emit()

[!CAUTION] Do not connect the two bridges to each other. If an OpenTelemetrySink in the core pipeline targets an OTelKotlinxLoggerProvider, each record is sent back into the same pipeline, causing recursive calls.

Distributed under the Apache License 2.0. See LICENSE for details.