taoensso.trove — com.taoensso/trove 1.2.0-alpha1

A minimal, modern logging facade for Clojure/Script. Supports both traditional and structured logging.

*ctx* clj/s

Optional context map (state) attached to all Trove logs. Default (root) value is nil.

Useful for dynamically attaching arbitrary app-level state to logs.

Re/bind dynamic value using with-ctx, with-ctx+, or binding. Modify root (default) value using set-root-ctx!.

As with all dynamic Clojure vars, binding conveyance applies when using futures, agents, etc.

*log-fn* clj/s

The value of this var determines the Trove backend, i.e. what happens on trove/log! calls.

When nil, all trove/log! calls will noop. Otherwise value should be a (fn [ns coords level id payload_]) with:

ns ------- String namespace of log! callsite, e.g. "my-app.utils" coords --- ?[line column] of log! callsite, may be lost (nil) for macros wrapping log!

level ---- Keyword :level from log! call ∈ #{:trace :debug :info :warn :error :fatal :report} id ------- ?Keyword :id from log! call, e.g. :auth/login, ::order-complete, etc.

payload_ - {:keys [ctx msg data error kvs]}, MAY be wrapped with delay so access with force: :ctx --- ?Map *ctx* value at log! call time :msg --- ?String :msg from log! call :data -- ?Map :data from log! call, e.g. {:user-id 1234} :error - ?Error :error from log! call, (java.lang.Throwable, js/Error, or nil) :kvs --- ?Map of any other kvs from log! call, handy for custom log-fn opts, etc.

The configured log-fn may filter (conditionally noop), or produce the relevant logging side effects (printing, etc.).

The configured log-fn will be called SYNCHRONOUSLY so:

• It should implement appropriate async/threading/backpressure for expensive work.
• It has access to trove/log! calling thread/context (can be handy).
• It has access to trove/*ctx* for filtering.

Config: Change dynamic value with binding. Change root value with set-log-fn!.

Basic fns are provided for some common backends, see taoensso.trove.x/get-log-fn with x ∈ #{console telemere timbre mulog tools-logging slf4j} (default console).

add-ctx-bridge clj/s

(add-ctx-bridge log-fn wrap-ctx-fn)

For custom backend (log-fn) authors that wish to support with-backend-ctx. Returns given log-fn wrapped with appropriate metadata (retain this!).

Given wrap-ctx-fn should be a (fn [ctx thunk]) -> (with-native-ctx ctx (thunk)): It will be called by with-backend-ctx when trove/*ctx* is non-empty. It should establish relevant native context, then execute and return (thunk).

log! clj/s macro

(log! {:keys [level id msg data error]})

Logs the given info to the currently configured backend (see *log-fn*) and returns nil.

Common options: :level -- ∈ #{:trace :debug :info :warn :error :fatal :report} (default :info) :id ----- Optional keyword used to identify event, e.g. :auth/login, ::order-complete, etc. :msg ---- Optional message string describing event (use str, format, etc. as needed) :data --- Optional arb map of structured data associated with event, e.g. {:user-id 1234} :error -- Optional platform error (java.lang.Throwable, js/Error)

Advanced options: :let ---- Bindings shared by payload args: {:keys [msg data error kvs]} :ns ----- Custom namespace string to override default :coords - Custom [line column] to override default :ctx ---- Custom context map to override default (*ctx*) :ctx+ --- Update for call-time *ctx*: map to merge or unary fn, trumps :ctx :log-fn - Custom log-fn to override default (*log-fn*) <kvs> ----- Any other kvs will also be provided to log-fn, handy for custom log-fn opts, etc.

Traditional logs typically include at least {:keys [level msg ...]}. Structured logs typically include at least {:keys [level id data ...]}.

set-log-fn! clj/s macro

(set-log-fn! f)

Sets the root value of *log-fn* (see its docstring for more info).

set-root-ctx! clj/s macro

(set-root-ctx! root-ctx)

Sets the root value of *ctx* (see its docstring for more info).

with-backend-ctx clj/s macro

(with-backend-ctx & body)

Evals given body and returns its result.

When *log-fn* opts in [1], merges Trove's *ctx* over backend's own native context for the body's scope.

[1] See :bridge-ctx? opt for built-in log-fn constructors. Custom backend authors see add-ctx-bridge.

with-ctx clj/s macro

(with-ctx ctx & body)

Evaluates given body with given ?map *ctx* value. See *ctx* for details.

with-ctx+ clj/s macro

(with-ctx+ update-map-or-fn & body)

Evaluates given body with updated *ctx* value.

update-map-or-fn may be:

• A map to merge with current *ctx* value, or
• A unary fn to apply to current *ctx* value, returning ?map

See *ctx* for details.