A minimal, modern logging facade for Clojure/Script. Supports both traditional and structured logging.
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.
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 log-fn wrap-ctx-fn)For custom backend (log-fn) authors that wish to support `with-ctx-bridge`. 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-ctx-bridge` when `trove/*ctx*` is non-empty. It should establish relevant native context, then execute and return (thunk).
(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! f)Sets the root value of `*log-fn*` (see its docstring for more info).
(set-root-ctx! root-ctx)Sets the root value of `*ctx*` (see its docstring for more info).
(with-ctx ctx & body)Evaluates given body with given ?map `*ctx*` value. See `*ctx*` for details.
(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.
(with-ctx-bridge & 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`.cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |