cartus.core — io.logicblocks/cartus.core 0.1.19-RC20

A structured logging abstraction for logging data rich events with support for multiple backends.

The cartus.core namespace includes core protocols, macros and utilities for managing loggers.

cartus is heavily inspired by JUXT's blog on logging which is worth a read to understand the motivations behind this library.

compose-loggers clj

(compose-loggers logger-a logger-b & other-loggers)

Returns a new logger which logs to each of the provided loggers

debug clj macro

(debug logger type)

(debug logger type context)

(debug logger type context opts)

Log event at debug level, capturing call site metadata.

By default, forms include :line and :column metadata. Additionally, this macro captures the calling namespace, with the metadata on the form taking precedence.

logger, type, context and opts are as defined on Logger.

error clj macro

(error logger type)

(error logger type context)

(error logger type context opts)

Log event at error level, capturing call site metadata.

By default, forms include :line and :column metadata. Additionally, this macro captures the calling namespace, with the metadata on the form taking precedence.

logger, type, context and opts are as defined on Logger.

fatal clj macro

(fatal logger type)

(fatal logger type context)

(fatal logger type context opts)

Log event at fatal level, capturing call site metadata.

By default, forms include :line and :column metadata. Additionally, this macro captures the calling namespace, with the metadata on the form taking precedence.

logger, type, context and opts are as defined on Logger.

info clj macro

(info logger type)

(info logger type context)

(info logger type context opts)

Log event at info level, capturing call site metadata.

By default, forms include :line and :column metadata. Additionally, this macro captures the calling namespace, with the metadata on the form taking precedence.

logger, type, context and opts are as defined on Logger.

Logger clj protocol

A protocol for logging events.

Events:

• are logged at a specific level, typically one of :trace, :debug, :info, :warn, :error or :fatal;
• have a type, expressed as a keyword, such as :some.namespace/some.event.type;
• include a map of additional context, which can be deeply nested;
• optionally include a message where implementations are guided to use the type as the message if none is provided and logging implementations require a message;
• optionally include an exception including more details of an error;
• optionally include a meta map, including any metadata at the point of the call to the logger; the level specific macros trace, debug, info, warn, error and fatal include line, column and namespace metadata in log calls they delegate to the Logger.

See [[cartus.test]] and [[cartus.cambium]] for example implementations.

log clj

(log this
     level
     type
     context
     {:keys [message exception meta] :or {meta {}} :as opts})

Log the provided event.

trace clj macro

(trace logger type)

(trace logger type context)

(trace logger type context opts)

Log event at trace level, capturing call site metadata.

By default, forms include :line and :column metadata. Additionally, this macro captures the calling namespace, with the metadata on the form taking precedence.

logger, type, context and opts are as defined on Logger.

warn clj macro

(warn logger type)

(warn logger type context)

(warn logger type context opts)

Log event at warn level, capturing call site metadata.

By default, forms include :line and :column metadata. Additionally, this macro captures the calling namespace, with the metadata on the form taking precedence.

logger, type, context and opts are as defined on Logger.

with-context clj

(with-context logger context)

Returns a new logger which merges the provided context map into that of any subsequent log call.

Entries in the context map provided at log time takes precedence over entries in the context map passed to this function. The applied merge is shallow.

with-levels-ignored clj

(with-levels-ignored logger levels)

(with-levels-ignored logger operator level)

Returns a new logger which ignores log events matching the provided criteria.

The arity-2 version expects a logger and a seq of levels to ignore. The arity-3 version expects a logger, an operator and a level. Supported operators are <=, <, =, >, >= passed as symbols.

with-levels-retained clj

(with-levels-retained logger levels)

(with-levels-retained logger operator level)

Returns a new logger which retains log events matching the provided criteria.

The arity-2 version expects a logger and a seq of levels to ignore. The arity-3 version expects a logger, an operator and a level. Supported operators are <=, <, =, >, >= passed as symbols.

with-transformation clj

(with-transformation logger xform)

Returns a new logger which applies the provided transducer to any logged event before passing it on to the underlying logger.

The transducer will receive the logged event as a map with keys :level, :type, :context and :opts set to the corresponding arguments to the log function and should return a map of the same shape.

with-types-ignored clj

(with-types-ignored logger types)

Returns a new logger which ignores log events having any of the provided types.

with-types-retained clj

(with-types-retained logger types)

Returns a new logger which retains log events having one of the provided types.