Log4j Kotlin API

Log4j Kotlin API provides a Kotlin-friendly interface to log against the Log4j API. The minimum requirements are Java 8 and Kotlin 1.6.21.

This is just a logging API. Your application still needs to have a logging backend (e.g., Log4j) configured.

Dependencies

You need to have the org.apache.logging.log4j:log4j-api-kotlin dependency in your classpath:

<dependency>
  <groupId>org.apache.logging.log4j</groupId>
  <artifactId>log4j-api-kotlin</artifactId>
  <version>1.5.0</version>
</dependency>

Java module name and OSGi Bundle-SymbolicName are set to org.apache.logging.log4j.api.kotlin.

Creating loggers

A Logger is the primary interface that users interact with Log4j Kotlin. You can create Loggers particularly in two ways:

Associate them with the class (Recommended!)
Associate them with the instance

Creating class loggers

For most applications, we recommend you to create a single logger instance per class definition – not per class instance! This not only avoids creating an extra logger field for each instance, its access pattern transparently communicates the implementation: the Logger is statically bound to the class definition. You can create class loggers in one of following ways:

Creating a logger in the companion object

This is the traditional approach to create class loggers. It also happens to be the most efficient one, since the logger lookup is performed once and its result is stored in the companion object shared by all instances of the class.

import org.apache.logging.log4j.kotlin.logger

class DbTableService {

  companion object {

    private val LOGGER = logger() (1)

  }

  fun truncateTable(tableName: String) {
    LOGGER.warn { "truncating table `${tableName}`" }
    db.truncate(tableName)
  }

}

1	Create a `Logger` associated with the static class definition that all instances of the class share

Extending companion object from `Logging`

Logging interface contains a logger getter that you can use by extending the companion object from the Logging class:

import org.apache.logging.log4j.kotlin.Logging

class DbTableService {

  companion object: Logging (1)

  fun truncateTable(tableName: String) {
    logger.warn { "truncating table `${tableName}`" }
    db.truncate(tableName)
  }

}

1	Extending the companion object from `Logging` effectively creates a single `Logger` instance Assigned to the `logger` field Associated with the static class definition that all instances of the class share

This getter-based approach incurs an extra overhead (compared to Creating a logger in the companion object) due to the logger lookup involved at runtime.

Creating instance loggers

Even though we recommend you to create class loggers, there might be occasions (most notably while sharing classes in Jakarta EE environments) necessitating loggers associated with each instance. You can achieve this as follows:

Creating a logger in the class

This is the traditional approach to create instance loggers. It also happens to be the most efficient one, since the logger lookup is performed once and its result is stored in the instance field.

import org.apache.logging.log4j.kotlin.logger

class DbTableService {

  private val logger = logger() (1)

  fun truncateTable(tableName: String) {
    logger.warn { "truncating table `${tableName}`" }
    db.truncate(tableName)
  }

}

1	Create a `Logger` associated with the class instance

Extending the class from `Logging`

Logging interface contains a logger getter that you can use by extending the class from Logging:

import org.apache.logging.log4j.kotlin.Logging

class DbTableService: Logging { (1)

  fun truncateTable(tableName: String) {
    logger.warn { "truncating table `${tableName}`" }
    db.truncate(tableName)
  }

}

1	Extending the class from `Logging` effectively creates a single `Logger` instance Assigned to the `logger` field Exclusively associated with the class instance (i.e., not shared among instances!)

This getter-based approach incurs an extra overhead (compared to Creating a logger in the class) due to the logger lookup involved at runtime.

Using `logger` extension property

You can use the logger extension property to dynamically inject a logger at the spot:

import org.apache.logging.log4j.kotlin.logger

class DbTableService {

  fun truncateTable(tableName: String) {
    logger.warn { "truncating table `${tableName}`" } (1)
    db.truncate(tableName)
  }

}

1	`logger` will look up the associated `Logger` instance for the encapsulating class

This getter-based approach incurs an extra overhead (compared to Creating a logger in the class) due to the logger lookup involved at runtime.

Thread context

The ThreadContext API has two facade objects provided: ContextMap and ContextStack.

import org.apache.logging.log4j.kotlin.ContextMap
import org.apache.logging.log4j.kotlin.ContextStack

ContextMap["key"] = "value"
assert(ContextMap["key"] == "value")
assert("key" in ContextMap)

ContextMap += "anotherKey" to "anotherValue"
ContextMap -= "key"

ContextStack.push("message")
assert(!ContextStack.empty)
assert(ContextStack.depth == 1)
val message = ContextStack.peek()
assert(message == ContextStack.pop())
assert(ContextStack.empty)

A CoroutineThreadContext context element is provided to integrate logging context with coroutines.

We provide convenience functions loggingContext and additionalLoggingContext to create instances of CoroutineThreadContext with the appropriate context data. The result of these functions can be passed directly to coroutine builders to set the context for the coroutine.

To set the context, ignoring any context currently in scope:

launch(loggingContext(mapOf("myKey" to "myValue"), listOf("test"))) {
  assertEquals("myValue", ContextMap["myKey"])
  assertEquals("test", ContextStack.peek())
}

Or to preserve the existing context and add additional logging context:

launch(additionalLoggingContext(mapOf("myKey" to "myValue"), listOf("test"))) {
  assertEquals("myValue", ContextMap["myKey"])
  assertEquals("test", ContextStack.peek())
}

Alternatively, to change the context without launching a new coroutine, the withLoggingContext and withAdditionalLoggingContext functions are provided:

withAdditionalLoggingContext(mapOf("myKey" to "myValue"), listOf("test")) {
  assertEquals("myValue", ContextMap["myKey"])
  assertEquals("test", ContextStack.peek())
}

These functions are shorthand for withContext(loggingContext(…)) or withContext(additionalLoggingContext(…)).

Parameter substitution

Unlike Java, Kotlin provides native functionality for string templates. However, using a string template still incurs the message construction cost if the logger level is not enabled. To avoid this, prefer passing a lambda which won’t be evaluated until necessary:

logger.debug { "Logging in user ${user.name} with birthday ${user.calcBirthday()}" }

Logger names

Most logging implementations use a hierarchical scheme for matching logger names with logging configuration.

In this scheme the logger name hierarchy is represented by . (dot) characters in the logger name, in a fashion very similar to the hierarchy used for Java/Kotlin package names. The Logger property added by the Logging interface follows this convention: the interface ensures the Logger is automatically named according to the class it is being used in.

The value returned when calling the logger() extension method depends on the receiver of the extension. When called within an object, the receiver is this and therefore the logger will again be named according to the class it is being used in. However, a logger named via another class can be obtained as well:

import org.apache.logging.log4j.kotlin

class MyClass: BaseClass {

  val logger = SomeOtherClass.logger()

  // ...

}

Explicitly Named Loggers

An explicitly-named logger may be obtained via the logger function that takes a name parameter:

import org.apache.logging.log4j.kotlin

class MyClass: BaseClass {

  val logger = logger("MyCustomLoggerName")

  // ...

}

This is also needed in scopes that do not have a this object, such as top-level functions.