This note is based on the ZIO Logging doc. It supports context across fibers. It comes with a console implementation and a SLf4j intergration. The code is not elegant and the sample code is a mess.
1 LogAnnotation
A value of LogAnnotation describes a piece of meta-info of a log entry. It has a name, an initial value, a value combination function and a render function. The combine function merges two values. The render function generates a string from the value.
A value of LogAnnotation is used as the map key of a LogContext.
Its companion object defines the following LogAnnotation values:
CorrelationId: a value ofOption[java.util.UUID]Level: a value ofLogLevelName: a value ofList[String]Throwable: a value ofOption[Throwable]Cause: a value of[Option[Cause[Any]]]
An important method is the apply method that returns a function of LogContext => LogContext. The function calls the combine field of the current LogAnnotation to combine two values.
2 LogContext
A LogContext stores conext for a logging operation. It wraps a map of a key of type LogAnnotation and a value of a type specified by the LogAnnotation type.
It defines the following methods:
++andmerge: merge two values of typeLogContext.annotate: add an annotation and return a newLogContext.apply: render the value of a given annotation.get: retrieve the specified annotation.renderContext: rend all annotation name and rendered value as a map.
3 Logger
The Logger[A] trait defines the log methods. A is the type of the logged value. It has three abstract methods that are to be implemented by any Logger object.
def log(line: => A): UIO[Unit]: the core function of a logger is to log a value of typeA.def logContext: UIO[LogContext]: the log context.def locally[R1, E, A1](f: LogContext => LogContext)(zio: ZIO[R1, E, A1]): ZIO[R1, E, A1]: modify the log context in the scope of the specified effectzio– the second parameter is a result of thelogmethod defined above. Thefis usually defined by theapplymethod ofLogAnnotation– the function is to combine annotation vlues.
Based on the three abastract methods, the Logger trait implements the following help methods:
contramap: log a different value with a contramap function parameterf: A1 => A.def log(level: LogLevel)(line: => A): UIO[Unit] = locally(_.annotate(LogAnnotation.Level, level))(log(line)): log with log level. Some shortcuts are:trace,debug,info,warn,error,error(line, cause), andthrowable(line, throwable).def derive(f: LogContext => LogContext): Logger[A]: create a new logger by newLogContext.def named(name: String): Logger[A]: produce a named logger
4 Logging
The Logging object defines a make[R] method to create a ZLayer from a logger and a rootLoggerName. The logger parameter has a type of (LogContext, => String) => URIO[R, Unit]. It is used to write a line with the log context. The make methods creates a FiberRef that wraps a LogContext value. Therefore the created logging object has a context in its FiberRef.
The make method is used to create a console method that create a value of ZLayer[Console with Clock, Nothing, Logging]. The Logging type is defined as Has[Logger[String]], i.e, a Logger type that logs string values.
The rest of the Logging object defines all methods of Logger that returns a type of URIO[Logging, LogContext].
5 log
The log object repeats all methods defined in Logging using the corresponding Logging methods . The sample code use the Loggin.console to create an environment and use the log methods to write log.
6 Slf4j Integration
The Slf4jLogger defines a make method that takes a logFormat: (LogContext, => String) => String and a root logger name. It maps each log level into the Slf4jLogger level. The log context can have a LogAnnotation.Throwable value.
Another method makeWithAnnotationAsMdc takes an additional parameter mdcAnnotations: List[LogAnnotation[_]] that allows the logging of mapped diagnostic context (MDC).
7 Sample Code
The ZIO logging document comes with several examples. The build file is as the following:
|
|
7.1 Simple Console Log
The console logging example:
|
|
7.2 Slf4j Log
The build.sc:
|
|
|
|
7.3 SLF4j with MDC
|
|
When run with mill -i hi, the messages are incorrect: 1) no mdc 2) logging call during initialization phase.