Breaking changes for version 5.x

[oshai]

In version 5 I would like to change the api of KLogger that will contain fluent api (KLoggingEventBuilder) see: #228 (comment)

In addition, this is a good time to make KLogger api lighter and remove methods such as fun trace(msg: String?, arg: Any?).

Basically the idea is to reduce the signature, and make it more "kotlin friendly".

These are the features planned to be supported:

• marker (partially, in supported platforms).
• mdc (partially, in supported platforms).
• line logging (partially, in supported platforms).

Features not planned to be supported:

• line info in compilation (was never supported).
• inline functions.

As a side effect this will also make the lib implementation a bit simpler, as right now inheritance is a bit complex and has a lot of duplication.

More changes:

• remove NamedKLogging,KLogging,KLoggable due to low usage.

[oshai]

Here is a suggested KLoggingEventBuilder:

public class KLoggingEventBuilder {
  public var message: String? = null
  public var marker: Marker? = null
  public var cause: Throwable? = null
  public var payload: Map<String, Any>? = null
}

Here is a suggested KLogger:

public interface KLogger {

  /**
   * Return the name of this `Logger` instance.
   * @return name of this logger instance
   */
  public val name: String

  /** Lazy add a log message if isTraceEnabled is true */
  public fun trace(message: () -> Any?): Unit = log(Level.TRACE, message)

  /** Lazy add a log message if isDebugEnabled is true */
  public fun debug(message: () -> Any?): Unit = log(Level.DEBUG, message)

  /** Lazy add a log message if isInfoEnabled is true */
  public fun info(message: () -> Any?): Unit = log(Level.INFO, message)

  /** Lazy add a log message if isWarnEnabled is true */
  public fun warn(message: () -> Any?): Unit = log(Level.WARN, message)

  /** Lazy add a log message if isErrorEnabled is true */
  public fun error(message: () -> Any?): Unit = log(Level.ERROR, message)

  /** Lazy add a log message if isErrorEnabled is true */
  public fun log(level: Level, message: () -> Any?)

  /** Lazy add a log message with throwable payload if isTraceEnabled is true */
  public fun atTrace(block: KLoggingEventBuilder.() -> Unit): Unit = logAt(Level.TRACE, block)

  /** Lazy add a log message with throwable payload if isDebugEnabled is true */
  public fun atDebug(block: KLoggingEventBuilder.() -> Unit): Unit = logAt(Level.DEBUG, block)

  /** Lazy add a log message with throwable payload if isInfoEnabled is true */
  public fun atInfo(block: KLoggingEventBuilder.() -> Unit): Unit = logAt(Level.INFO, block)

  /** Lazy add a log message with throwable payload if isWarnEnabled is true */
  public fun atWarn(block: KLoggingEventBuilder.() -> Unit): Unit = logAt(Level.WARN, block)

  /** Lazy add a log message with throwable payload if isErrorEnabled is true */
  public fun atError(block: KLoggingEventBuilder.() -> Unit): Unit = logAt(Level.ERROR, block)

  /** Lazy add a log message if isErrorEnabled is true */
  public fun at(level: Level, block: KLoggingEventBuilder.() -> Unit)

  /** Add a log message with all the supplied parameters along with method name */
  public fun entry(vararg arguments: Any?): Unit = trace { "entry(${arguments.joinToString() })" }

  /** Add log message indicating exit of a method */
  public fun exit(): Unit = trace { "exit" }

  /** Add a log message with the return value of a method */
  public fun <T> exit(result: T): T where T : Any? {
    trace { "exit($result)" }
    return result
  }

  /** Add a log message indicating an exception will be thrown along with the stack trace. */
  public fun <T> throwing(throwable: T): T where T : Throwable {
    atError {
      cause = throwable
      message = "throwing($throwable)"
    }
    return throwable
  }

  /** Add a log message indicating an exception is caught along with the stack trace. */
  public fun <T> catching(throwable: T) where T : Throwable {
    atError {
      cause = throwable
      message = "catching($throwable)"
    }
  }

  /**
   * Similar to [.isTraceEnabled] method except that the marker data is also taken into account.
   *
   * @param marker The marker data to take into consideration
   * @return True if this Logger is enabled for the TRACE level, false otherwise.
   */
  public fun isTraceEnabled(marker: Marker? = null): Boolean =
    isEnabledForLevel(Level.TRACE, marker)

  /**
   * Similar to [.isDebugEnabled] method except that the marker data is also taken into account.
   *
   * @param marker The marker data to take into consideration
   * @return True if this Logger is enabled for the DEBUG level, false otherwise.
   */
  public fun isDebugEnabled(marker: Marker? = null): Boolean =
    isEnabledForLevel(Level.DEBUG, marker)

  /**
   * Similar to [.isInfoEnabled] method except that the marker data is also taken into
   * consideration.
   *
   * @param marker The marker data to take into consideration
   * @return true if this Logger is enabled for the INFO level, false otherwise.
   */
  public fun isInfoEnabled(marker: Marker? = null): Boolean = isEnabledForLevel(Level.INFO, marker)

  /**
   * Similar to [.isWarnEnabled] method except that the marker data is also taken into
   * consideration.
   *
   * @param marker The marker data to take into consideration
   * @return True if this Logger is enabled for the WARN level, false otherwise.
   */
  public fun isWarnEnabled(marker: Marker? = null): Boolean = isEnabledForLevel(Level.WARN, marker)

  /**
   * Similar to [.isErrorEnabled] method except that the marker data is also taken into
   * consideration.
   *
   * @param marker The marker data to take into consideration
   * @return True if this Logger is enabled for the ERROR level, false otherwise.
   */
  public fun isErrorEnabled(marker: Marker? = null): Boolean =
    isEnabledForLevel(Level.ERROR, marker)

  /**
   * Similar to [.isLoggingOff] method except that the marker data is also taken into consideration.
   *
   * @param marker The marker data to take into consideration
   * @return True if this Logger is set to the OFF level, false otherwise.
   */
  public fun isLoggingOff(marker: Marker? = null): Boolean = !isEnabledForLevel(Level.ERROR, marker)

  public fun isEnabledForLevel(level: Level, marker: Marker? = null): Boolean
}

[oshai]

I created #330.

Since it turns out to simplify things I am considering to somehow skip version 4 (which was already released), and recommend users to jump directly to v5.

[oshai]

Release version 5.0.0-beta-01.
As mentioned in previous comment the plan is to recommend users to jump from 3 directly to 5.
Will do some more testing before releasing the GA version.

[Fornitx]

What is the replacement for KLogging/KLoggable ?

[oshai]

The plan is to have only KLogger interface and a KotlinLogging.logger to create one.

[oshai]

What is the replacement for KLogging/KLoggable ?

For v5 it will be marked as deprecated, later will be removed.