repository·master·Indexed 25 days ago
https://github.com/oshai/kotlin-loggingA lightweight, multiplatform logging facade for Kotlin that provides an idiomatic wrapper around SLF4J. It features lazy-evaluated log messages via lambdas, fluent logging with payloads, and coroutine-safe MDC context via withLoggingContextAsync. The library supports SLF4J 1 and 2, requiring a separate logging implementation such as Logback or Log4j2 at runtime.
When upgrading from version 1.x to 2.x, note the following breaking changes:
kotlin-logging to kotlin-logging-jvm to comply with the multiplatform schema.2.x requires Kotlin >= 1.4.Recommendation: For JVM-only library owners, using 1.x is still acceptable, but 2.x is recommended for all other use cases.
Version 5 introduced breaking changes. If you are upgrading:
io.github.microutils to io.github.oshai.mu to io.github.oshai.kotlinlogging.slf4j-api is no longer provided automatically; you must include it in your dependencies.To use kotlin-logging in a JVM project, add the kotlin-logging-jvm dependency.
Important: kotlin-logging is a facade. You must also provide a logging implementation (like Logback, Log4j2, or slf4j-simple) at runtime to see any output. If you only want to log to stdout for testing, you can add org.slf4j:slf4j-simple:2.0.3.
### Gradle
```Groovy
implementation 'io.github.oshai:kotlin-logging-jvm:7.0.3'<dependency>
<groupId>io.github.oshai</groupId>
<artifactId>kotlin-logging-jvm</artifactId>
<version>7.0.3</version>
</dependency>In version 1.4.1 and later, you can obtain a logger using the KotlinLogging object with the following syntax:
private val logger = KotlinLogging.logger {}Use lambda expressions {} for log methods to ensure that expensive string construction or message evaluation only occurs if the specific log level is enabled.
logger.debug { "Some $expensive message!" }Use withLoggingContextAsync to wrap a block of suspending code with a specific SLF4J MDC context. This ensures that the provided key-value pairs are available in the MDC during the execution of the block.
By default, the function restores the previous MDC context once the block completes. You can disable this restoration by setting restorePrevious = false.
withLoggingContextAsync("userId" to "A_USER_ID") {
// The MDC context will contain the mapping of "userId"=>"A_USER_ID"
// during this log statement.
logger.info { "..." }
}
// The block will restore The MDC context so that it no longer contains
// the mapping of "userId"=>"A_USER_ID"
withLoggingContextAsync("userId" to "ANOTHER_USER_ID", restorePrevious = false) {
logger.info { "..." }
}
// The MDC context will retain the mapping of "userId"=>"ANOTHER_USER_ID",
// as the previous context restoration was disabled.You can define a logger without explicitly specifying the class name by using the empty lambda syntax. Placing the definition above the class declaration makes the field static.
import io.github.oshai.kotlinlogging.KotlinLogging
private val logger = KotlinLogging.logger {}
class FooWithLogging {
val message = "world"
fun bar() {
logger.debug { "hello $message" }
}
}Use the atLevel API (e.g., atWarn) to build logs fluently, allowing you to attach a cause and a structured payload.
logger.atWarn {
message = "foo $bar"
cause = exception
payload = buildMap(capacity = 3) {
put("foo", 1)
put("bar", "x")
put("obj", Pair(2, 3))
}
}The library provides support for Mapped Diagnostic Context (MDC):
1.4.9.2.0.7 added support for optional or nullable values within the MDC.1.4.6 and later, KLogger provides an underlyingLogger property. This allows you to access the actual logger implementation, which is useful for operations such as setting log levels programmatically.Pass the exception as the first parameter and provide the log message as a lambda.
logger.error(exception) { "a $fancy message about the $exception" }underlyingLogger property on the DelegatingKLogger (on supported platforms).