devlog-kotlin/dev.hermannm.devlog

Package-level declarations

The main package of devlog-kotlin, providing the Logger API.

Types

open class ExceptionWithLoggingContext : RuntimeException

Exception that carries log fields, to provide structured logging context when the exception is logged. When passing a cause exception to one of the methods on Logger, it will check if the given exception is an instance of this class, and if it is, these fields will be added to the log.

HasLoggingContext

interface HasLoggingContext

Interface for exceptions that carry log fields, to provide structured logging context when an exception is logged. When passing a cause exception to one of the methods on Logger, it will check if the given exception implements this interface, and if it does, these fields will be added to the log.

LogBuilder

@JvmInline

value class LogBuilder

Class used in the logging methods on Logger, allowing you to add structured key-value data to the log by calling the field and rawJsonField methods.

LogField

class LogField

A log field is a key-value pair for adding structured data to logs.

Logger

@JvmInline

value class Logger

A logger provides methods for logging at various log levels (info, warn, error, debug and trace). It has a logger name, typically the same as the class that the logger is attached to (e.g. com.example.Example). The name is included in the log output, and can be used to enable/disable log levels for loggers based on their package names, or query for logs from a specific class.

LoggingContext

expect class LoggingContext

Wraps a platform-specific representation of the thread-local logging context fields. On the JVM, this uses SLF4J's MDC context map.

actual class LoggingContext

LogLevel

class LogLevel

The severity of a log. From most to least severe:

RawJson

@Serializable(with = RawJsonSerializer::class)

expect sealed interface RawJson

rawJson returns this wrapper around a given raw JSON string, controlling how the JSON string is serialized:

@Serializable(with = RawJsonSerializer::class)

actual interface RawJson

Functions

field

inline fun <ValueT> field(key: String, value: ValueT): LogField

fun <ValueT : Any> field(key: String, value: ValueT?, serializer: SerializationStrategy<ValueT>): LogField

Constructs a LogField, a key-value pair for adding structured data to logs.

getCopyOfLoggingContext

expect fun getCopyOfLoggingContext(): LoggingContext

Returns a copy of the log fields in the current thread's logging context (from withLoggingContext). This can be used to pass logging context between threads (see example below).

actual fun getCopyOfLoggingContext(): LoggingContext

getLogger

expect inline fun getLogger(): Logger

Returns a Logger, with its name inferred from the class in which it's called (or file, if defined at the top level).

expect fun getLogger(name: String): Logger

Returns a Logger with the given name.

expect fun getLogger(forClass: KClass<*>): Logger

Returns a Logger with the name of the given class.

actual inline fun getLogger(): Logger

actual fun getLogger(name: String): Logger

actual fun getLogger(forClass: KClass<*>): Logger

inheritLoggingContext

fun ExecutorService.inheritLoggingContext(): ExecutorService

Wraps an ExecutorService in a new implementation that copies logging context fields (from withLoggingContext) from the parent thread to child threads when spawning new tasks. This is useful when you use an ExecutorService in the scope of a logging context, and you want the fields from the logging context to also be included on the logs in the child tasks.

rawJson

fun rawJson(json: String, validJson: Boolean = false): RawJson

Wraps the given pre-serialized JSON string in a serializable object, that will serialize the JSON string inline (without escaping). Uses the same validation logic as rawJsonField.

rawJsonField

fun rawJsonField(key: String, json: String, validJson: Boolean = false): LogField

Constructs a LogField, a key-value pair for adding structured data to logs, with the given pre-serialized JSON value.

withLoggingContext

inline fun <ReturnT> withLoggingContext(context: LoggingContext, block: () -> ReturnT): ReturnT

Adds the fields from an existing logging context to all logs made by a Logger in the context of the given block. This overload is designed to be used with getCopyOfLoggingContext, to pass logging context between threads. If you want to add fields to the current thread's logging context, you should instead construct log fields with the field/rawJsonField functions, and pass them to one of the withLoggingContext overloads that take LogFields.

inline fun <ReturnT> withLoggingContext(vararg logFields: LogField, block: () -> ReturnT): ReturnT

inline fun <ReturnT> withLoggingContext(logFields: Collection<LogField>, block: () -> ReturnT): ReturnT

Adds the given log fields to every log made by a Logger in the context of the given block.