Skip to content

Latest commit

 

History

History
166 lines (121 loc) · 8.87 KB

README.md

File metadata and controls

166 lines (121 loc) · 8.87 KB
Raw

kotlin-logging kotlin-logging Build Status Slack channel Maven Central Apache License V.2

Lightweight logging framework for Kotlin, written in Pure Kotlin.
A convenient and performant logging library wrapping slf4j with Kotlin extensions.

Call log methods, without checking whether the respective log level is enabled

logger.debug { "Some $expensive message!" }

Behind the scenes the expensive message do not get evaluated if debug is not enabled:

// This is what happens when you write the above ^^^
if (logger.isDebugEnabled) logger.debug("Some $expensive message!")

Define the logger, without explicitly specifiying the class name

// Place definition above class declaration to make field static
private val logger = KotlinLogging.logger {}

Behind the scenes val logger will be created in the class, with the class/file name:

// This is what happens when you write the above ^^^
val logger = LoggerFactory.getLogger("package.ClassName")

Log exceptions in a Kotlin-style

// exception as first parameter with message as lambda
logger.error(exception) { "a $fancy message about the $exception" }

Getting started

private val logger = KotlinLogging.logger {} 
class FooWithLogging {
    val message = "world"
    fun bar() {
        logger.debug { "hello $message" }
    }
}

An Android example project with kotlin-logging can be found in kotlin-logging-example-android.

Download

Important note: kotlin-logging depends on slf4j-api (in the JVM artifact). In runtime, it is also required to depend on a logging implementation. More details in how-to-configure-slf4j. And an excellent detailed explanation in a-guide-to-logging-in-java.

In short, if you just want to log statements to stdout, it's possible to add the following dependency: org.slf4j:slf4j-simple:1.7.29.

Maven

<dependency>
  <groupId>io.github.microutils</groupId>
  <artifactId>kotlin-logging</artifactId>
  <version>1.12.0</version>
</dependency>

See the full example in kotlin-logging-example-maven.

Gradle

compile 'io.github.microutils:kotlin-logging:1.12.0'

Alternatively, download the JAR from github or bintray or maven-central.

Version 2.x

There are currently two supported branches: 1.x and 2.x.

The main incompatible change is in the artifact names. In version 1.x the jvm artifact is called kotlin-logging while in version 2.x it's called kotlin-logging-jvm to comply with multiplatform schema. In addition, version 2.x supports only Kotlin >= 1.4.

Therefore for jvm library owners it is still recommended to use 1.x, as for the rest of the use cases 2.x is recommended.

For example, to use kotlin-logging for jvm in version 2.0.2 add the following gradle dependency:

compile 'io.github.microutils:kotlin-logging-jvm:2.0.2'

Multiplatform

An experimental common & JS & linux-x64 support is available.
More information is available on the wiki and issues #21 #45.

Snapshot builds

To get the latest non-stable version of kotlin logging use the following gradle configuration:

repositories {
	maven { url 'https://oss.jfrog.org/artifactory/oss-snapshot-local' }
}

dependencies {
	compile('io.github.microutils:kotlin-logging-jvm:2.0.0-SNAPSHOT')
}

Overview

After seeing many questions like Idiomatic way of logging in Kotlin and Best practices for loggers, it seems like there should be a standard for logging and obtaining a logger in Kotlin. kotlin-logging provides a wrapper for slf4j-api to be used by Kotlin classes with the following advantages:

  • No need to write the logger and class name or logger name boilerplate code.
  • A straight forward way to log messages with lazy-evaluated string using lambda expression {}.
  • All previous slf4j implementation can still be used.

Who is using it

And many more... (add your name above)

FAQ

  • Why not use plain slf4j? kotlin-logging has better native Kotlin support. It adds more functionality and enables less boilerplate code.
  • Is all slf4j implementation supported (Markers, params, etc')? Yes, kotlin-logging inherits Logger and all methods are supported.
  • Is location logging possible? Yes, location awareness was added in kotlin-logging 1.4.
  • When I do logger.debug, my IntelliJ IDEA run console doesn't show any output. Do you know how I could set the console logger to debug or trace levels? Is this an IDE setting, or can it be set in the call to KLogging()? Setting log level is done per implementation. kotlin-logging and slf4j are just facades for the underlying logging lib (log4j, logback etc') more details here.
  • Can I access the actual logger? Yes, via KLogger.underlyingLogger property.

Usage

  • See wiki for more examples.

It is possible to configure IntelliJ live templates. For file level logger configure the following:

  • Text template: private val logger = mu.KotlinLogging.logger {}.
  • Applicable in Kotlin: top-level.

Support

More links

Contributors

Any contribution is appreciated. See the contributors list in: https://github.com/MicroUtils/kotlin-logging/graphs/contributors

Contributing

Pull requests are welcome!
Show your ❤ with a ★