apache/logging-log4j-kotlin

A Kotlin-friendly interface to log against the Log4j API

logging-log4j-kotlin's Issues

Thread/coroutine context is more verbose than necessary

Add convenience functions to make it simpler to use context with coroutines.

Also add some related docs.

Coroutine context is not cleared properly

The coroutine context is not cleared properly. This test fails:

  @Test
  fun `Context is restored after a context block is complete`() = runBlocking {
    assertTrue(ContextMap.empty)
    assertTrue(ContextStack.empty)
    withContext(CoroutineThreadContext(ThreadContextData(mapOf("myKey" to "myValue"), listOf("test")))) {
      assertEquals("myValue", ContextMap["myKey"])
      assertEquals("test", ContextStack.peek())
    }
    assertTrue(ContextMap.empty)
    assertTrue(ContextStack.empty)
  }

Improve logging context integration

Using log4j2 context seems a bit limited for non-thread use cases. The assumption that context will always be set at the Thread or coroutine level is IMO false, and sometimes we just want to set context for a particular block of code, or for a particular logger.

We should have a way to do something like this outside of a coroutine / suspending context:

withContextMap(...) {
  // log something
}

Possible implementations (only map shown here, but similar for stack)?

fun <T> withContextMap(
  map: Map<String, String>,
  block: () -> T,
): T {
  val oldMap = ContextMap.view
  return try {
    ContextMap += map
    block()
  } finally {
    ContextMap.clear()
    ContextMap += oldMap
  }
}

Could also be related to #36. We may want to do something like:

val log = parentLog.withContext(...)

...

log.debug { ... }

Update baseline Kotlin requirement to Kotlin 1.6

Add an extension property for storing a cached logger

Analogous to the extension function T.logger() which constructs a logger using the class of T, an extension property T.logger should be added for an alternative to using the Logging mixin. The general change is fairly simple:

inline val <reified T> T.logger: KotlinLogger
  get() = cachedLoggerOf(T::class.java)

Add facade APIs for manipulating the context map and stack

Context map operations could benefit from map-related operators, and the general ThreadContext API could benefit from some Kotlin-specific facades.

catching() is missing in KotlinLogger

It looks like Logger.catching(..) methods are missing in KotlinLogger.

If there is an equivalent for that then please mention it in KDoc of KotlinLogger and / or at Log4j Kotlin project site.
Fix version 1.2.1 and 1.3 are acceptable.

Previously created at https://issues.apache.org/jira/browse/LOG4J2-3649

Add a type-safe Kotlin configuration builder API

Using the functionality in https://kotlinlang.org/docs/type-safe-builders.html it should be fairly straightforward to make a Kotlin-specific DSL similar to the ConfigurationBuilder Java API.

Update baseline Kotlin requirement to Kotlin 1.4

The latest release of Kotlin is 1.8.x, and we only require 1.3.x. Starting in log4j-api-kotlin version 1.4.0, this should require Kotlin 1.4.x. Some potentially useful info about the process: https://kotlinlang.org/docs/whatsnew14.html#migrating-to-kotlin-1-4-0

Support LogBuilder API in a kotlin-y way

The Kotlin API does not have an equivalent to the https://logging.apache.org/log4j/2.x/manual/logbuilder.html.

A Kotlin-y approach may use a DSL rather than a builder. For example, a LoggingScope passed as a lambda receiver could result in an API that could look something like:

logger.atError {
  // `this` here is an instance of `LoggingScope`
  // everything optional except log
  throwable = ...
  marker = ...
  location = ...
  log = ...
}

The standard builder API could also be supported as an alternative for users who prefer it.

See also relevant background discussion about designing a fluent logging API from https://github.com/google/flogger and https://google.github.io/flogger/benefits.

Navigation menu icons are missing

The icons in the menu on https://logging.apache.org/log4j/kotlin/ don’t load.

Support Kotlin multi-platform

It would be nice if the API supported Kotlin multi-platform, and so could be used on other platforms that Kotlin targets, such as native, JavaScript, and WASM.

Log4j2 is obviously a JVM-only solution but this library is mostly just an API. We could make it easier for users to plugin in different backends for different platforms, and provide some reasonable choices out of the box for each platform.

Open KotlinLogger

Open KotlinLogger because I want to inherit it, rewrite the error method, and count the number of error calls. Of course, if there are other ways to meet my needs, I would be more than happy to ask for your advice