Project

Topics

Namespaces

Public Vars

cartus.core

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.

debug

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.

view source

error

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.

view source

fatal

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.

view source

info

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.

view source

Logger

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.

members

log

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

Log the provided event.

view source

trace

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.

view source

warn

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.

view source

with-context

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

view source

with-levels-ignored

(with-levels-ignored logger operator level)(with-levels-ignored logger levels)

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.

view source

with-levels-retained

(with-levels-retained logger operator level)(with-levels-retained logger levels)

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.

view source

with-transformation

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

view source

with-types-ignored

(with-types-ignored logger types)

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

view source

with-types-retained

(with-types-retained logger types)

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

view source