devlog-kotlin/dev.hermannm.devlog

Package-level declarations

Types

open class ExceptionWithLogFields(val message: String?, logFields: List<LogField> = emptyList(), val cause: Throwable? = null) : RuntimeException, HasLogFields

Base exception class to allow you to attach log fields to exceptions. 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.

HasLogFields

interface HasLogFields

Interface to allow you to attach log fields to exceptions. 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

sealed 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.

LoggingContextJsonFieldWriter

class LoggingContextJsonFieldWriter : MdcEntryWriter

Writes logging context fields as JSON when using logstash-logback-encoder. We need this in order to include object fields as raw JSON instead of escaped strings on the log output.

LogLevel

class LogLevel

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

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.

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

getLoggingContext

fun getLoggingContext(): List<LogField>

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).

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): JsonElement

Turns the given pre-serialized JSON string into a JsonElement (from kotlinx.serialization), using 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(vararg logFields: LogField, block: () -> ReturnT): ReturnT

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

Adds the given log fields to every log made by a Logger in the context of the given block. Use the field/rawJsonField functions to construct log fields.