Telemere 1.0.0-alpha4
Released under the Eclipse Public License - v 1.0
Structured telemetry library for Clojure/Script.
Installation
To install, add the following dependency to your project or build file:
[com.taoensso/telemere "1.0.0-alpha4"]
Namespaces
taoensso.telemere
Structured telemetry for Clojure/Script applications.
Public variables and functions:
- *ctx*
- *middleware*
- add-handler!
- catch->error!
- chance
- check-interop
- default-ctx
- error!
- event!
- get-env
- get-filters
- get-handlers
- get-min-level
- handler:console
- handler:file
- help:filters
- help:handlers
- help:signal-content
- help:signal-formatters
- help:signal-handling
- help:signal-options
- level-aliases
- log!
- msg-skip
- msg-splice
- newline
- rate-limiter
- remove-handler!
- set-ctx!
- set-id-filter!
- set-kind-filter!
- set-middleware!
- set-min-level!
- set-ns-filter!
- set-var-root!
- shut-down-handlers!
- signal!
- spy!
- streams->reset!
- streams->telemere!
- tools-logging->telemere!
- trace!
- uncaught->error!
- uncaught->handler!
- update-var-root!
- with-ctx
- with-ctx+
- with-err->telemere
- with-handler
- with-handler+
- with-id-filter
- with-kind-filter
- with-middleware
- with-min-level
- with-ns-filter
- with-out->telemere
- with-signal
- with-signals
- with-streams->telemere
- without-filters
taoensso.telemere.timbre
Main Timbre macros, reimplemented on top of Telemere. +Telemere 1.0.0-alpha5 \ No newline at end of file diff --git a/index.cljs.html b/index.cljs.html index ce61ce7..45d6f9f 100644 --- a/index.cljs.html +++ b/index.cljs.html @@ -1,4 +1,4 @@ -Telemere 1.0.0-alpha5
Released under the Eclipse Public License - v 1.0
Structured telemetry library for Clojure/Script.
Installation
To install, add the following dependency to your project or build file:
[com.taoensso/telemere "1.0.0-alpha5"]Namespaces
taoensso.telemere
Structured telemetry for Clojure/Script applications.Public variables and functions:
- *ctx*
- *middleware*
- add-handler!
- catch->error!
- chance
- check-interop
- default-ctx
- error!
- event!
- get-env
- get-filters
- get-handlers
- get-min-level
- handler:console
- handler:file
- help:filters
- help:handlers
- help:signal-content
- help:signal-filters
- help:signal-flow
- help:signal-formatters
- help:signal-handlers
- help:signal-options
- level-aliases
- log!
- msg-skip
- msg-splice
- newline
- rate-limiter
- remove-handler!
- set-ctx!
- set-id-filter!
- set-kind-filter!
- set-middleware!
- set-min-level!
- set-ns-filter!
- set-var-root!
- shut-down-handlers!
- signal!
- spy!
- streams->reset!
- streams->telemere!
- tools-logging->telemere!
- trace!
- uncaught->error!
- uncaught->handler!
- update-var-root!
- with-ctx
- with-ctx+
- with-err->telemere
- with-handler
- with-handler+
- with-id-filter
- with-kind-filter
- with-middleware
- with-min-level
- with-ns-filter
- with-out->telemere
- with-signal
- with-signals
- with-streams->telemere
- without-filters
taoensso.telemere.timbre
Main Timbre macros, reimplemented on top of Telemere. Intended to help ease migration from Timbre to Telemere.taoensso.telemere.utils
Misc utils useful for Telemere handlers, middleware, etc.Telemere 1.0.0-alpha4 Telemere 1.0.0-alpha4
Released under the Eclipse Public License - v 1.0
Structured telemetry library for Clojure/Script.
Installation
To install, add the following dependency to your project or build file:
[com.taoensso/telemere "1.0.0-alpha4"]Namespaces
taoensso.telemere
Structured telemetry for Clojure/Script applications.Public variables and functions:
- *ctx*
- *middleware*
- add-handler!
- catch->error!
- chance
- check-interop
- default-ctx
- error!
- event!
- get-env
- get-filters
- get-handlers
- get-min-level
- handler:console
- handler:console-raw
- help:filters
- help:handlers
- help:signal-content
- help:signal-formatters
- help:signal-handling
- help:signal-options
- level-aliases
- log!
- msg-skip
- msg-splice
- newline
- rate-limiter
- remove-handler!
- set-ctx!
- set-id-filter!
- set-kind-filter!
- set-middleware!
- set-min-level!
- set-ns-filter!
- set-var-root!
- shut-down-handlers!
- signal!
- spy!
- trace!
- uncaught->error!
- update-var-root!
- with-ctx
- with-ctx+
- with-err->telemere
- with-handler
- with-handler+
- with-id-filter
- with-kind-filter
- with-middleware
- with-min-level
- with-ns-filter
- with-out->telemere
- with-signal
- with-signals
- with-streams->telemere
- without-filters
taoensso.telemere.timbre
Main Timbre macros, reimplemented on top of Telemere. +Telemere 1.0.0-alpha5 \ No newline at end of file diff --git a/index.html b/index.html index 3972a89..be7cc9f 100644 --- a/index.html +++ b/index.html @@ -1,3 +1,3 @@ -Telemere 1.0.0-alpha5
Released under the Eclipse Public License - v 1.0
Structured telemetry library for Clojure/Script.
Installation
To install, add the following dependency to your project or build file:
[com.taoensso/telemere "1.0.0-alpha5"]Namespaces
taoensso.telemere
Structured telemetry for Clojure/Script applications.Public variables and functions:
- *ctx*
- *middleware*
- add-handler!
- catch->error!
- chance
- check-interop
- default-ctx
- error!
- event!
- get-env
- get-filters
- get-handlers
- get-min-level
- handler:console
- handler:console-raw
- help:filters
- help:handlers
- help:signal-content
- help:signal-filters
- help:signal-flow
- help:signal-formatters
- help:signal-handlers
- help:signal-options
- level-aliases
- log!
- msg-skip
- msg-splice
- newline
- rate-limiter
- remove-handler!
- set-ctx!
- set-id-filter!
- set-kind-filter!
- set-middleware!
- set-min-level!
- set-ns-filter!
- set-var-root!
- shut-down-handlers!
- signal!
- spy!
- trace!
- uncaught->error!
- update-var-root!
- with-ctx
- with-ctx+
- with-err->telemere
- with-handler
- with-handler+
- with-id-filter
- with-kind-filter
- with-middleware
- with-min-level
- with-ns-filter
- with-out->telemere
- with-signal
- with-signals
- with-streams->telemere
- without-filters
taoensso.telemere.timbre
Main Timbre macros, reimplemented on top of Telemere. Intended to help ease migration from Timbre to Telemere.Public variables and functions:
taoensso.telemere.utils
Misc utils useful for Telemere handlers, middleware, etc.Telemere 1.0.0-alpha4 \ No newline at end of file +Telemere 1.0.0-alpha4
Released under the Eclipse Public License - v 1.0
Structured telemetry library for Clojure/Script.
Installation
To install, add the following dependency to your project or build file:
[com.taoensso/telemere "1.0.0-alpha4"]Platforms
This project includes code for multiple platforms, please choose a platform to view its documentation:
Telemere 1.0.0-alpha5 \ No newline at end of file diff --git a/taoensso.telemere.cljs.html b/taoensso.telemere.cljs.html index 88dafc9..c2f27d9 100644 --- a/taoensso.telemere.cljs.html +++ b/taoensso.telemere.cljs.html @@ -1,6 +1,6 @@ -Telemere 1.0.0-alpha5
Released under the Eclipse Public License - v 1.0
Structured telemetry library for Clojure/Script.
Installation
To install, add the following dependency to your project or build file:
[com.taoensso/telemere "1.0.0-alpha5"]Platforms
This project includes code for multiple platforms, please choose a platform to view its documentation:
taoensso.telemere documentation taoensso.telemere
Structured telemetry for Clojure/Script applications. +taoensso.telemere documentation taoensso.telemere
Structured telemetry for Clojure/Script applications. See the GitHub page (esp. Wiki) for info on motivation and design: <https://www.taoensso.com/telemere>*ctx*
dynamic
clj
cljs
Dynamic context: arbitrary user-level state attached as `:ctx` to all signals. @@ -107,7 +107,7 @@ Flow sequence: e. Hander fn Note: call filters should generally be at least as permissive as handler filters, - otherwise calls will be suppressed before reaching handlers.catch->error!
macro
clj
cljs
(catch->error! form)(catch->error! id form)(catch->error! {:as opts, :keys [rethrow? catch-val elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & extra-kvs]} form)Unconditionally executes given form and- + otherwise calls will be suppressed before reaching handlers.catch->error!
macro
clj
cljs
(catch->error! form)(catch->error! id form)(catch->error! {:as opts, :keys [rethrow? catch-val elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & kvs]} form)Unconditionally executes given form and- If form succeeds: return the form's result. If form throws: Call `error!` with the thrown error and the given signal options [1], @@ -140,6 +140,7 @@ Tips: See also `error!`. +--------------------------------------- [1] See `help:signal-options` docstringcheck-interop
clj
cljs
(check-interop)Experimental, subject to change. Runs Telemere's registered interop checks and returns @@ -148,7 +149,7 @@ Runs Telemere's registered interop checks and returns Useful for tests/debugging.default-ctx
clj
cljs
Advanced feature. Default root (base) value of `*ctx*` var, controlled by: (get-env {:as :edn} :taoensso.telemere/default-ctx<.platform><.edn>) -See `get-env` for details.error!
macro
clj
cljs
(error! error)(error! id error)(error! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & extra-kvs]} error)"Error" signal call, focused on error + id. +See `get-env` for details.error!
macro
clj
cljs
(error! error)(error! id error)(error! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & kvs]} error)"Error" signal creator, focused on error + id. API: [error] [id-or-opts error] => given error (unconditional) Default kind: `:error` @@ -174,16 +175,18 @@ Tips: - `error` arg is a platform error (`java.lang.Throwable` or `js/Error`). - Can conveniently be wrapped by `throw`: (throw (error! ...)). -[1] See `help:signal-handling` docstring -[2] See `help:signal-content` docstring -[3] See `help:signal-options` docstringevent!
macro
clj
cljs
(event! id)(event! id level)(event! id {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & extra-kvs]})"Event" signal call, focused on id + level. +---------------------------------------- +[1] See `help:signal-flow` docstring +[2] See `help:signal-content` docstring +[3] See `help:signal-options` docstringevent!
macro
clj
cljs
(event! id)(event! id level)(event! id {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & kvs]})"Event" signal creator, focused on id + level. -API: [id] [id level-or-opts] => true iff signal call was allowed +API: [id] [id level-or-opts] => true iff signal was allowed Default kind: `:event` Default level: `:info` -When conditions are met [1], creates a Telemere signal [2] and dispatches it to -registered handlers for processing (writing to console/disk/db, etc.). +When filtering conditions are met [1], creates a Telemere signal [2] and +dispatches it to registered handlers for processing (e.g. writing to +console/file/queue/db, etc.). Examples: @@ -207,9 +210,9 @@ Tips: position, and for `event!` that's the `level-or-opts` arg. ---------------------------------------- -[1] See `help:signal-handling` docstring -[2] See `help:signal-content` docstring -[3] See `help:signal-options` docstringget-env
macro
clj
cljs
added in Encore v3.75.0 (2024-01-29)
(get-env {:keys [as default return]} spec)(get-env {:keys [as default return spec], :or {as :str, return :value}})Cross-platform util for embedding flexible environmental config during +[1] See `help:signal-flow` docstring +[2] See `help:signal-content` docstring +[3] See `help:signal-options` docstringget-env
macro
clj
cljs
added in Encore v3.75.0 (2024-01-29)
(get-env {:keys [as default return]} spec)(get-env {:keys [as default return spec], :or {as :str, return :value}})Cross-platform util for embedding flexible environmental config during macro expansion. Used by other Taoensso libraries. Given a const kw/string id or vector of desc-priority alternative ids, @@ -313,103 +316,112 @@ improve these docs!help:signal-content
clj
cljs
Signals are initially maps with {:keys [inst id ns level data msg_ ...]}, -though they can be modified by call and/or handler middleware. +improve these docs!help:signal-content
clj
cljs
Signals are maps with {:keys [inst id ns level data msg_ ...]}, +though they can be modified by signal and/or handler middleware. -Default keys: +Default signal keys: -`:schema` - Int version of signal schema (current: 1) -`:inst` - Platform instant [1] when signal was created -`:level` - Signal level ∈ #{<int> :trace :debug :info :warn :error :fatal :report ...} -`:kind` - Signal ?kind ∈ #{nil :event :error :log :trace :spy <user-val> ...} -`:id` - ?id of signal call (common to all signals created by signal call, contrast with `:uid`) -`:uid` - ?id of signal instance (unique to each signal created by signal call, contrast with `:id`) +`:schema` ------ Int version of signal schema (current: 1) +`:inst` -------- Platform instant [1] when signal was created +`:level` ------- Signal level ∈ #{<int> :trace :debug :info :warn :error :fatal :report ...} +`:kind` -------- Signal ?kind ∈ #{nil :event :error :log :trace :spy <user-val> ...} +`:id` ---------- ?id of signal (common to all signals created at callsite, contrast with `:uid`) +`:uid` --------- ?id of signal instance (unique to each signal created at callsite, contrast with `:id`) -`:msg` - Arb user-level message ?str given to signal call -`:data` - Arb user-level data ?val (usu. a map) given to signal call -`:error` - Arb user-level platform ?error [2] given to signal call +`:msg` --------- Arb user-level message ?str given to signal creator +`:data` -------- Arb user-level data ?val (usu. a map) given to signal creator +`:error` ------- Arb user-level platform ?error [2] given to signal creator -`:run-form` - Unevaluated ?form given to signal call as `:run` -`:run-val` - Successful return ?val of `:run` ?form -`:run-nsecs`- ?int nanosecs runtime of `:run` ?form -`:end-inst` - Platform ?instant [1] when `:run` ?form completed +`:run-form` ---- Unevaluated ?form given to signal creator as `:run` +`:run-val` ----- Successful return ?val of `:run` ?form +`:run-nsecs` --- ?int nanosecs runtime of `:run` ?form +`:end-inst` ---- Platform ?instant [1] when `:run` ?form completed -`:ctx` - ?val of `*ctx*` (arb user-level state) when signal was created -`:parent` - ?{:keys [id uid]} of parent signal, present in nested signals when tracing -`:location` - ?{:keys [ns file line column]} signal call location -`:ns` - ?str namespace of signal call, same as (:ns location) -`:line` - ?int line of signal call, same as (:line location) -`:column` - ?int column of signal call, same as (:column location) -`:file` - ?str filename of signal call, same as (:file location) +`:ctx` --------- ?val of `*ctx*` (arb user-level state) when signal was created +`:parent` ------ ?{:keys [id uid]} of parent signal, present in nested signals when tracing +`:location` ---- ?{:keys [ns file line column]} signal creator callsite +`:ns` ---------- ?str namespace of signal creator callsite, same as (:ns location) +`:line` -------- ?int line of signal creator callsite, same as (:line location) +`:column` ------ ?int column of signal creator callsite, same as (:column location) +`:file` -------- ?str filename of signal creator callsite, same as (:file location) +`:sample-rate` - ?rate ∈ℝ[0,1] for combined signal AND handler sampling (0.75 => allow 75% of signals, nil => allow all) -`:sample-rate` - ?rate ∈ℝ[0,1] for combined call AND handler sampling (0.75 => allow 75% of signals, nil => allow all) - -<extra-kvs> - Arb user-level ?kvs given to signal call +<kvs> ---------- Arb other user-level ?kvs given to signal creator If anything is unclear, please ping me (@ptaoussanis) so that I can improve these docs! [1] `java.time.Instant` or `js/Date` -[2] `java.lang.Throwable` or `js/Error`help:signal-formatters
clj
cljs
Common signal formatters include: +[2] `java.lang.Throwable` or `js/Error`help:signal-flow
clj
cljs
A signal will be provided to a handler iff ALL of the following are true: + 1. Signal (creation) is allowed by compile-time filters + 2. Signal (creation) is allowed by runtime filters + 3. Signal (handling) is allowed by handler filters + + 4. Signal middleware does not suppress the signal (return nil) + 5. Handler middleware does not suppress the signal (return nil) + +For 1-3, filtering may depend on (in order): + Sample rate → namespace → kind → id → level → when form/fn → rate limit + +Note that sample rates are multiplicative: + If a signal is created with 20% sampling and a handler handles 50% + of given signals, then 10% of possible signals will be handled. + + This multiplicative rate is helpfully reflected in the signal's final + `:sample-rate` value. + +For a visual flowchart, see: Ref. <https://www.taoensso.com/telemere/flow> + +For more info: + - On signal filters, see: `help:filters` docstring + - On handler filters, see: `help:handlers` docstring + +If anything is unclear, please ping me (@ptaoussanis) so that I can +improve these docs!help:signal-formatters
clj
cljs
Common signal formatters include: (utils/format-signal-str->fn) {<opts>}) ; For human-readable string output (default) (utils/format-signal->edn-fn) {<opts>}) ; For edn output (utils/format-signal->json-fn {<opts>}) ; For JSON output -See relevant docstrings for details.help:signal-handling
clj
cljs
A signal will be provided to a handler iff ALL of the following are true: +See relevant docstrings for details.help:signal-options
clj
cljs
Signal options (shared by all signal creators): - 1. Signal call is allowed by compile-time filters - 2. Signal call is allowed by runtime filters - 3. Handler is allowed by runtime filters +`:inst` -------- Platform instant [1] when signal was created, ∈ #{nil :auto <user-val>} +`:level` ------- Signal level ∈ #{<int> :trace :debug :info :warn :error :fatal :report ...} +`:kind` -------- Signal ?kind ∈ #{nil :event :error :log :trace :spy <user-val> ...} +`:id` ---------- ?id of signal (common to all signals created at callsite, contrast with `:uid`) +`:uid` --------- ?id of signal instance (unique to each signal created at callsite, contrast with `:id`) - 4. Signal call middleware does not suppress the signal (return nil) - 5. Handler middleware does not suppress the signal (return nil) +`:msg` --------- Arb user-level ?message to incl. in signal: str or vec of strs to join (with `\space`) +`:data` -------- Arb user-level ?data to incl. in signal: usu. a map +`:error` ------- Arb user-level ?error to incl. in signal: platform error [2] -For more info: +`:run` --------- ?form to execute UNCONDITIONALLY; will incl. `:run-value` in signal +`:do` ---------- ?form to execute conditionally (iff signal allowed), before establishing `:let` ?binding +`:let` --------- ?bindings to establish conditionally (iff signal allowed), BEFORE evaluating `:data` and `:msg` (useful!) - - On call filters, see: `help:filters` docstring - - On handler filters, see: `help:handlers` docstring - - On signal flow, see: Ref. <https://tinyurl.com/telemere-signal-flowchart> +`:ctx` --------- Custom ?val to override auto (dynamic `*ctx*`) in signal +`:parent` ------ Custom ?{:keys [id uid]} to override auto (dynamic) parent signal info in signal +`:location` ---- Custom ?{:keys [ns line column file]} to override auto signal call location -If anything is unclear, please ping me (@ptaoussanis) so that I can -improve these docs!help:signal-options
clj
cljs
Signal options (shared by `signal!`, `event!`, ...): - -`:inst` - Platform instant [1] when signal was created, ∈ #{nil :auto <user-val>} -`:level` - Signal level ∈ #{<int> :trace :debug :info :warn :error :fatal :report ...} -`:kind` - Signal ?kind ∈ #{nil :event :error :log :trace :spy <user-val> ...} -`:id` - ?id of signal call (common to all signals created by signal call, contrast with `:uid`) -`:uid` - ?id of signal instance (unique to each signal created by signal call, contrast with `:id`) - -`:msg` - Arb user-level ?message to incl. in signal: str or vec of strs to join (with `\space`) -`:data` - Arb user-level ?data to incl. in signal: usu. a map -`:error` - Arb user-level ?error to incl. in signal: platform error [2] - -`:run` - ?form to execute UNCONDITIONALLY; will incl. `:run-value` in signal -`:do` - ?form to execute conditionally (iff signal allowed), before establishing `:let` ?binding -`:let` - ?binding to establish conditionally (iff signal allowed), BEFORE evaluating `:data` and `:msg` (useful!) - -`:ctx` - Custom ?val to override auto (dynamic `*ctx*`) in signal -`:parent` - Custom ?{:keys [id uid]} to override auto (dynamic) parent signal info in signal -`:location` - Custom ?{:keys [ns line column file]} to override auto signal call location - -`:elidable?` - Should signal call be subject to compile-time elision? (Default: true) +`:elidable?` --- Should signal be subject to compile-time elision? (Default: true). `:sample-rate` - ?rate ∈ℝ[0,1] for call sampling (0.75 => allow 75% of signals, nil => allow all) -`:when` - Arb ?form; when present, form must return truthy to allow signal -`:rate-limit` - ?spec as given to `telemere/rate-limiter`, see its docstring for details -`:middleware` - ?[(fn [signal])=>modified-signal ...] call middleware -`:trace?` - Should tracing be enabled for `:run` form? +`:when` -------- Arb ?form; when present, form must return truthy to allow signal +`:rate-limit` -- ?spec as given to `taoensso.telemere/rate-limiter`, see its docstring for details +`:middleware` -- ?[(fn [signal])=>modified-signal ...] signal middleware +`:trace?` ------ Should tracing be enabled for `:run` form? -<extra-kvs> - Arb user-level ?kvs to incl. in signal +<kvs> ---------- Arb other user-level ?kvs to incl. in signal If anything is unclear, please ping me (@ptaoussanis) so that I can improve these docs! [1] `java.time.Instant` or `js/Date` -[2] `java.lang.Throwable` or `js/Error`log!
macro
clj
cljs
(log! msg)(log! level msg)(log! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & extra-kvs]} msg)"Log" signal call, focused on message + level. +[2] `java.lang.Throwable` or `js/Error`log!
macro
clj
cljs
(log! msg)(log! level msg)(log! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & kvs]} msg)"Log" signal creator, focused on message + level. -API: [msg] [level-or-opts msg] => true iff signal call was allowed. +API: [msg] [level-or-opts msg] => true iff signal was allowed. Default kind: `:log` Default level: `:info` -When conditions are met [1], creates a Telemere signal [2] and dispatches it to -registered handlers for processing (writing to console/disk/db, etc.). +When filtering conditions are met [1], creates a Telemere signal [2] and +dispatches it to registered handlers for processing (e.g. writing to +console/file/queue/db, etc.). Examples: @@ -433,9 +445,9 @@ Tips: - See also `msg-splice`, `msg-skip` utils. ---------------------------------------- -[1] See `help:signal-handling` docstring -[2] See `help:signal-content` docstring -[3] See `help:signal-options` docstringmsg-splice
clj
cljs
(msg-splice args)For use within signal message vectors. +[1] See `help:signal-flow` docstring +[2] See `help:signal-content` docstring +[3] See `help:signal-options` docstringmsg-splice
clj
cljs
(msg-splice args)For use within signal message vectors. Wraps given arguments so that they're spliced when creating message. Useful for conditionally splicing in extra message content, etc.: @@ -475,13 +487,17 @@ still registered.set-kind-filter!
clj
cljs
(set-kind-filter! kind-filter)Sets signal call kind filter based on given `kind-filter` spec. + - {:allow <spec> :deny <spec>} with specs as above. + If present, `:allow` spec MUST match, AND + If present, `:deny` spec MUST NOT match.set-kind-filter!
clj
cljs
(set-kind-filter! kind-filter)Sets signal call kind filter based on given `kind-filter` spec. `kind-filter` may be: - A regex pattern of kind/s to allow. - A str/kw/sym, in which "*"s act as wildcards. - A vector or set of regex patterns or strs/kws/syms. - - {:allow <spec> :deny <spec>} with specs as above.set-middleware!
macro
clj
cljs
(set-middleware! root-val)Set `*middleware*` var's root (base) value. See `*middleware*` for details. + - {:allow <spec> :deny <spec>} with specs as above. + If present, `:allow` spec MUST match, AND + If present, `:deny` spec MUST NOT match.set-middleware!
macro
clj
cljs
(set-middleware! root-val)Set `*middleware*` var's root (base) value. See `*middleware*` for details.set-min-level!
clj
cljs
(set-min-level! min-level)(set-min-level! kind min-level)(set-min-level! kind ns-filter min-level)Sets minimum signal call level based on given `min-level` spec. `min-level` may be: @@ -499,33 +515,36 @@ will apply only for that signal kind.set-var-root!
macro
clj
cljs
added in Encore v3.75.0 (2024-01-29)
(set-var-root! var-sym root-val)Sets root binding (value) of the var identified by given symbol, and returns + - {:allow <spec> :deny <spec>} with specs as above. + If present, `:allow` spec MUST match, AND + If present, `:deny` spec MUST NOT match.set-var-root!
macro
clj
cljs
added in Encore v3.75.0 (2024-01-29)
(set-var-root! var-sym root-val)Sets root binding (value) of the var identified by given symbol, and returns the new value. Cross-platform. See also `update-var-root!`.shut-down-handlers!
clj
cljs
(shut-down-handlers!)Shuts down all registered signal handlers and returns ?{<handler-id> {:keys [okay error]}}. Future calls to handlers will no-op. -Clj only: `shut-down-handlers!` is called automatically on JVM shutdown.signal!
macro
clj
cljs
(signal! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & extra-kvs]})Low-level generic signal call. +Clj only: `shut-down-handlers!` is called automatically on JVM shutdown.signal!
macro
clj
cljs
(signal! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & kvs]})Low-level generic signal creator. API: [opts] => depends on options [3] Default kind: none (optional) Default level: none (must be provided) -When conditions are met [1], creates a Telemere signal [2] and dispatches it to -registered handlers for processing (writing to console/disk/db, etc.). +When filtering conditions are met [1], creates a Telemere signal [2] and +dispatches it to registered handlers for processing (e.g. writing to +console/file/queue/db, etc.). If `:run` option is provided: returns value of given run form, or throws. - Otherwise: returns true iff call conditions were met. + Otherwise: returns true iff signal was created (allowed). Generic signals are fairly low-level and useful mostly for library authors or advanced users writing their own wrapper macros. Regular users will typically -prefer one of the provided wrapper macros optimized for ease-of-use in +prefer one of the higher-level signal creators optimized for ease-of-use in common cases. These all use `signal!` underneath and offer the same options, but vary in their defaults and the focus of their call APIs (args and return values): - `event!` - (id + opts/level) => true iff signal call was allowed - `log!` - (message + opts/level) => true iff signal call was allowed + `event!` - (id + opts/level) => true iff signal was created (allowed) + `log!` - (message + opts/level) => true iff signal was created (allowed) `error!` - (error + opts/id) => given error (unconditional) `trace!` - (form + opts/id) => form's result (value/throw) (unconditional) `spy!` - (form + opts/level) => form's result (value/throw) (unconditional) @@ -535,17 +554,18 @@ Tips: - Test using `with-signal`: (with-signal (signal! ...)). - Supports the same options as other signals [3]. ----------------------------------------- -[1] See `help:signal-handling` docstring -[2] See `help:signal-content` docstring -[3] See `help:signal-options` docstringspy!
macro
clj
cljs
(spy! form)(spy! id form)(spy! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & extra-kvs]} form)"Spy" signal call, focused on form + level. +--------------------------------------- +[1] See `help:signal-flow` docstring +[2] See `help:signal-content` docstring +[3] See `help:signal-options` docstringspy!
macro
clj
cljs
(spy! form)(spy! id form)(spy! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & kvs]} form)"Spy" signal creator, focused on form + level. API: [form] [level-or-opts form] => form's result (value/throw) (unconditional) Default kind: `:spy` Default level: `:info` -When conditions are met [1], creates a Telemere signal [2] and dispatches it to -registered handlers for processing (writing to console/disk/db, etc.). +When filtering conditions are met [1], creates a Telemere signal [2] and +dispatches it to registered handlers for processing (e.g. writing to +console/file/queue/db, etc.). Examples: @@ -567,23 +587,24 @@ Tips: - Identical to `trace!`, but focused on form + level rather than form + id. - Useful for debugging/monitoring forms, and tracing (nested) execution flow. - - Execution of `form` arg may trigger additional (nested) signals. + - Execution of `form` arg may create additional (nested) signals. Each signal's `:parent` key will indicate its immediate parent. - Can be useful to wrap with `catch->error!`: (catch->error! ::error-id (spy! ...)). ----------------------------------------- -[1] See `help:signal-handling` docstring -[2] See `help:signal-content` docstring -[3] See `help:signal-options` docstringtrace!
macro
clj
cljs
(trace! form)(trace! id form)(trace! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & extra-kvs]} form)"Trace" signal call, focused on form + id. +--------------------------------------- +[1] See `help:signal-flow` docstring +[2] See `help:signal-content` docstring +[3] See `help:signal-options` docstringtrace!
macro
clj
cljs
(trace! form)(trace! id form)(trace! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & kvs]} form)"Trace" signal creator, focused on form + id. API: [form] [id-or-opts form] => form's result (value/throw) (unconditional) Default kind: `:trace` Default level: `:info` (intentionally NOT `:trace`!) -When conditions are met [1], creates a Telemere signal [2] and dispatches it to -registered handlers for processing (writing to console/disk/db, etc.). +When filtering conditions are met [1], creates a Telemere signal [2] and +dispatches it to registered handlers for processing (e.g. writing to +console/file/queue/db, etc.). Examples: @@ -605,7 +626,7 @@ Tips: - Identical to `spy!`, but focused on form + id rather than form + level. - Useful for debugging/monitoring forms, and tracing (nested) execution flow. - - Execution of `form` arg may trigger additional (nested) signals. + - Execution of `form` arg may create additional (nested) signals. Each signal's `:parent` key will indicate its immediate parent. - Can be useful to wrap with `catch->error!`: @@ -615,10 +636,10 @@ Tips: refers to the general action of tracing program flow rather than to the common logging level of the same name. ----------------------------------------- -[1] See `help:signal-handling` docstring -[2] See `help:signal-content` docstring -[3] See `help:signal-options` docstringuncaught->error!
macro
clj
cljs
(uncaught->error!)(uncaught->error! id)(uncaught->error! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & extra-kvs]})Uses `uncaught->handler!` so that `error!` will be called for +--------------------------------------- +[1] See `help:signal-flow` docstring +[2] See `help:signal-content` docstring +[3] See `help:signal-options` docstringuncaught->error!
macro
clj
cljs
(uncaught->error!)(uncaught->error! id)(uncaught->error! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & kvs]})Uses `uncaught->handler!` so that `error!` will be called for uncaught JVM errors. See `uncaught->handler!` and `error!` for details.update-var-root!
macro
clj
cljs
added in Encore v3.68.0 (2023-09-25)
(update-var-root! var-sym update-fn)Updates root binding (value) of the var identified by given symbol, and returns @@ -643,12 +664,12 @@ See `*middleware*` for details.with-ns-filter
macro
clj
cljs
(with-ns-filter ns-filter form)Executes form with given signal call namespace filter in effect. See `set-ns-filter!` for details.with-out->telemere
macro
clj
cljs
(with-out->telemere form)(with-out->telemere opts form)Executes form with `*out*` bound to flush to Telemere signals with given opts.with-signal
macro
clj
cljs
(with-signal form)(with-signal trap-signals? form)(with-signal raw-msg? trap-signals? form)Experimental. -Executes given form, trapping errors. Returns the LAST signal triggered by form. +Executes given form, trapping errors. Returns the LAST signal created by form. Useful for tests/debugging. Options: `trap-signals?` (default: false) - Should ALL signals triggered by form be trapped to prevent normal dispatch + Should ALL signals created by form be trapped to prevent normal dispatch to registered handlers? `raw-msg?` (default: false) diff --git a/taoensso.telemere.html b/taoensso.telemere.html index 95057fb..abf174a 100644 --- a/taoensso.telemere.html +++ b/taoensso.telemere.html @@ -1,6 +1,6 @@ -taoensso.telemere documentation taoensso.telemere
Structured telemetry for Clojure/Script applications. +taoensso.telemere documentation taoensso.telemere
Structured telemetry for Clojure/Script applications. See the GitHub page (esp. Wiki) for info on motivation and design: <https://www.taoensso.com/telemere>*ctx*
dynamic
clj
cljs
Dynamic context: arbitrary user-level state attached as `:ctx` to all signals. @@ -107,7 +107,7 @@ Flow sequence: e. Hander fn Note: call filters should generally be at least as permissive as handler filters, - otherwise calls will be suppressed before reaching handlers.catch->error!
macro
clj
cljs
(catch->error! form)(catch->error! id form)(catch->error! {:as opts, :keys [rethrow? catch-val elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & extra-kvs]} form)Unconditionally executes given form and- + otherwise calls will be suppressed before reaching handlers.catch->error!
macro
clj
cljs
(catch->error! form)(catch->error! id form)(catch->error! {:as opts, :keys [rethrow? catch-val elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & kvs]} form)Unconditionally executes given form and- If form succeeds: return the form's result. If form throws: Call `error!` with the thrown error and the given signal options [1], @@ -140,6 +140,7 @@ Tips: See also `error!`. +--------------------------------------- [1] See `help:signal-options` docstringcheck-interop
clj
cljs
(check-interop)Experimental, subject to change. Runs Telemere's registered interop checks and returns @@ -148,7 +149,7 @@ Runs Telemere's registered interop checks and returns Useful for tests/debugging.default-ctx
clj
cljs
Advanced feature. Default root (base) value of `*ctx*` var, controlled by: (get-env {:as :edn} :taoensso.telemere/default-ctx<.platform><.edn>) -See `get-env` for details.error!
macro
clj
cljs
(error! error)(error! id error)(error! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & extra-kvs]} error)"Error" signal call, focused on error + id. +See `get-env` for details.error!
macro
clj
cljs
(error! error)(error! id error)(error! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & kvs]} error)"Error" signal creator, focused on error + id. API: [error] [id-or-opts error] => given error (unconditional) Default kind: `:error` @@ -174,16 +175,18 @@ Tips: - `error` arg is a platform error (`java.lang.Throwable` or `js/Error`). - Can conveniently be wrapped by `throw`: (throw (error! ...)). -[1] See `help:signal-handling` docstring -[2] See `help:signal-content` docstring -[3] See `help:signal-options` docstringevent!
macro
clj
cljs
(event! id)(event! id level)(event! id {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & extra-kvs]})"Event" signal call, focused on id + level. +---------------------------------------- +[1] See `help:signal-flow` docstring +[2] See `help:signal-content` docstring +[3] See `help:signal-options` docstringevent!
macro
clj
cljs
(event! id)(event! id level)(event! id {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & kvs]})"Event" signal creator, focused on id + level. -API: [id] [id level-or-opts] => true iff signal call was allowed +API: [id] [id level-or-opts] => true iff signal was allowed Default kind: `:event` Default level: `:info` -When conditions are met [1], creates a Telemere signal [2] and dispatches it to -registered handlers for processing (writing to console/disk/db, etc.). +When filtering conditions are met [1], creates a Telemere signal [2] and +dispatches it to registered handlers for processing (e.g. writing to +console/file/queue/db, etc.). Examples: @@ -207,9 +210,9 @@ Tips: position, and for `event!` that's the `level-or-opts` arg. ---------------------------------------- -[1] See `help:signal-handling` docstring -[2] See `help:signal-content` docstring -[3] See `help:signal-options` docstringget-env
macro
clj
cljs
added in Encore v3.75.0 (2024-01-29)
(get-env {:keys [as default return]} spec)(get-env {:keys [as default return spec], :or {as :str, return :value}})Cross-platform util for embedding flexible environmental config during +[1] See `help:signal-flow` docstring +[2] See `help:signal-content` docstring +[3] See `help:signal-options` docstringget-env
macro
clj
cljs
added in Encore v3.75.0 (2024-01-29)
(get-env {:keys [as default return]} spec)(get-env {:keys [as default return spec], :or {as :str, return :value}})Cross-platform util for embedding flexible environmental config during macro expansion. Used by other Taoensso libraries. Given a const kw/string id or vector of desc-priority alternative ids, @@ -339,104 +342,150 @@ improve these docs!help:signal-content
clj
cljs
Signals are initially maps with {:keys [inst id ns level data msg_ ...]}, -though they can be modified by call and/or handler middleware. +improve these docs!help:signal-content
clj
cljs
Signals are maps with {:keys [inst id ns level data msg_ ...]}, +though they can be modified by signal and/or handler middleware. -Default keys: +Default signal keys: -`:schema` - Int version of signal schema (current: 1) -`:inst` - Platform instant [1] when signal was created -`:level` - Signal level ∈ #{<int> :trace :debug :info :warn :error :fatal :report ...} -`:kind` - Signal ?kind ∈ #{nil :event :error :log :trace :spy <user-val> ...} -`:id` - ?id of signal call (common to all signals created by signal call, contrast with `:uid`) -`:uid` - ?id of signal instance (unique to each signal created by signal call, contrast with `:id`) +`:schema` ------ Int version of signal schema (current: 1) +`:inst` -------- Platform instant [1] when signal was created +`:level` ------- Signal level ∈ #{<int> :trace :debug :info :warn :error :fatal :report ...} +`:kind` -------- Signal ?kind ∈ #{nil :event :error :log :trace :spy <user-val> ...} +`:id` ---------- ?id of signal (common to all signals created at callsite, contrast with `:uid`) +`:uid` --------- ?id of signal instance (unique to each signal created at callsite, contrast with `:id`) -`:msg` - Arb user-level message ?str given to signal call -`:data` - Arb user-level data ?val (usu. a map) given to signal call -`:error` - Arb user-level platform ?error [2] given to signal call +`:msg` --------- Arb user-level message ?str given to signal creator +`:data` -------- Arb user-level data ?val (usu. a map) given to signal creator +`:error` ------- Arb user-level platform ?error [2] given to signal creator -`:run-form` - Unevaluated ?form given to signal call as `:run` -`:run-val` - Successful return ?val of `:run` ?form -`:run-nsecs`- ?int nanosecs runtime of `:run` ?form -`:end-inst` - Platform ?instant [1] when `:run` ?form completed +`:run-form` ---- Unevaluated ?form given to signal creator as `:run` +`:run-val` ----- Successful return ?val of `:run` ?form +`:run-nsecs` --- ?int nanosecs runtime of `:run` ?form +`:end-inst` ---- Platform ?instant [1] when `:run` ?form completed -`:ctx` - ?val of `*ctx*` (arb user-level state) when signal was created -`:parent` - ?{:keys [id uid]} of parent signal, present in nested signals when tracing -`:location` - ?{:keys [ns file line column]} signal call location -`:ns` - ?str namespace of signal call, same as (:ns location) -`:line` - ?int line of signal call, same as (:line location) -`:column` - ?int column of signal call, same as (:column location) -`:file` - ?str filename of signal call, same as (:file location) +`:ctx` --------- ?val of `*ctx*` (arb user-level state) when signal was created +`:parent` ------ ?{:keys [id uid]} of parent signal, present in nested signals when tracing +`:location` ---- ?{:keys [ns file line column]} signal creator callsite +`:ns` ---------- ?str namespace of signal creator callsite, same as (:ns location) +`:line` -------- ?int line of signal creator callsite, same as (:line location) +`:column` ------ ?int column of signal creator callsite, same as (:column location) +`:file` -------- ?str filename of signal creator callsite, same as (:file location) +`:sample-rate` - ?rate ∈ℝ[0,1] for combined signal AND handler sampling (0.75 => allow 75% of signals, nil => allow all) -`:sample-rate` - ?rate ∈ℝ[0,1] for combined call AND handler sampling (0.75 => allow 75% of signals, nil => allow all) - -<extra-kvs> - Arb user-level ?kvs given to signal call +<kvs> ---------- Arb other user-level ?kvs given to signal creator If anything is unclear, please ping me (@ptaoussanis) so that I can improve these docs! [1] `java.time.Instant` or `js/Date` -[2] `java.lang.Throwable` or `js/Error`help:signal-formatters
clj
cljs
Common signal formatters include: +[2] `java.lang.Throwable` or `js/Error`help:signal-filters
clj
cljs
Your filter config determines which signal calls will be allowed. + +Filtering can occur at compile-time (=> elision), or runtime. +Both compile-time and runtime config can be specified via: + + 1. System values (JVM properties, environment variables, or + classpath resources). See library docs for details. + + 2. The filter API consting of the following: + + `set-kind-filter!`, `with-kind-filter` - for filtering calls by signal kind (when relevant) + `set-ns-filter!`, `with-ns-filter` - for filtering calls by namespace + `set-id-filter!`, `with-id-filter` - for filtering calls by signal id (when relevant) + `set-minimum-level!`, `with-minimum-level!` - for filtering calls by signal level + + See the relevant docstrings for details. + +Additional filtering can also be applied on a per-handler basis, see +`add-handler!` for details. + +See also: + + `get-filters` - to see current filter config + `get-min-level` - to see current minimum level + `without-filters` - to disable all runtime filtering + +If anything is unclear, please ping me (@ptaoussanis) so that I can +improve these docs!help:signal-flow
clj
cljs
A signal will be provided to a handler iff ALL of the following are true: + 1. Signal (creation) is allowed by compile-time filters + 2. Signal (creation) is allowed by runtime filters + 3. Signal (handling) is allowed by handler filters + + 4. Signal middleware does not suppress the signal (return nil) + 5. Handler middleware does not suppress the signal (return nil) + +For 1-3, filtering may depend on (in order): + Sample rate → namespace → kind → id → level → when form/fn → rate limit + +Note that sample rates are multiplicative: + If a signal is created with 20% sampling and a handler handles 50% + of given signals, then 10% of possible signals will be handled. + + This multiplicative rate is helpfully reflected in the signal's final + `:sample-rate` value. + +For a visual flowchart, see: Ref. <https://www.taoensso.com/telemere/flow> + +For more info: + - On signal filters, see: `help:filters` docstring + - On handler filters, see: `help:handlers` docstring + +If anything is unclear, please ping me (@ptaoussanis) so that I can +improve these docs!help:signal-formatters
clj
cljs
Common signal formatters include: (utils/format-signal-str->fn) {<opts>}) ; For human-readable string output (default) (utils/format-signal->edn-fn) {<opts>}) ; For edn output (utils/format-signal->json-fn {<opts>}) ; For JSON output -See relevant docstrings for details.help:signal-handling
clj
cljs
A signal will be provided to a handler iff ALL of the following are true: +See relevant docstrings for details.help:signal-handlers
clj
cljs
The handler API consists of the following: - 1. Signal call is allowed by compile-time filters - 2. Signal call is allowed by runtime filters - 3. Handler is allowed by runtime filters + `get-handlers` - Returns info on currently registered handlers + `add-handler!` - Used to register handlers + `remove-handler!` - Used to unregister handlers + `shut-down-handlers!` - Used to shut down handlers - 4. Signal call middleware does not suppress the signal (return nil) - 5. Handler middleware does not suppress the signal (return nil) - -For more info: - - - On call filters, see: `help:filters` docstring - - On handler filters, see: `help:handlers` docstring - - On signal flow, see: Ref. <https://tinyurl.com/telemere-signal-flowchart> +See the relevant docstrings for details. If anything is unclear, please ping me (@ptaoussanis) so that I can -improve these docs!help:signal-options
clj
cljs
Signal options (shared by all signal creators): -`:inst` - Platform instant [1] when signal was created, ∈ #{nil :auto <user-val>} -`:level` - Signal level ∈ #{<int> :trace :debug :info :warn :error :fatal :report ...} -`:kind` - Signal ?kind ∈ #{nil :event :error :log :trace :spy <user-val> ...} -`:id` - ?id of signal call (common to all signals created by signal call, contrast with `:uid`) -`:uid` - ?id of signal instance (unique to each signal created by signal call, contrast with `:id`) +`:inst` -------- Platform instant [1] when signal was created, ∈ #{nil :auto <user-val>} +`:level` ------- Signal level ∈ #{<int> :trace :debug :info :warn :error :fatal :report ...} +`:kind` -------- Signal ?kind ∈ #{nil :event :error :log :trace :spy <user-val> ...} +`:id` ---------- ?id of signal (common to all signals created at callsite, contrast with `:uid`) +`:uid` --------- ?id of signal instance (unique to each signal created at callsite, contrast with `:id`) -`:msg` - Arb user-level ?message to incl. in signal: str or vec of strs to join (with `\space`) -`:data` - Arb user-level ?data to incl. in signal: usu. a map -`:error` - Arb user-level ?error to incl. in signal: platform error [2] +`:msg` --------- Arb user-level ?message to incl. in signal: str or vec of strs to join (with `\space`) +`:data` -------- Arb user-level ?data to incl. in signal: usu. a map +`:error` ------- Arb user-level ?error to incl. in signal: platform error [2] -`:run` - ?form to execute UNCONDITIONALLY; will incl. `:run-value` in signal -`:do` - ?form to execute conditionally (iff signal allowed), before establishing `:let` ?binding -`:let` - ?binding to establish conditionally (iff signal allowed), BEFORE evaluating `:data` and `:msg` (useful!) +`:run` --------- ?form to execute UNCONDITIONALLY; will incl. `:run-value` in signal +`:do` ---------- ?form to execute conditionally (iff signal allowed), before establishing `:let` ?binding +`:let` --------- ?bindings to establish conditionally (iff signal allowed), BEFORE evaluating `:data` and `:msg` (useful!) -`:ctx` - Custom ?val to override auto (dynamic `*ctx*`) in signal -`:parent` - Custom ?{:keys [id uid]} to override auto (dynamic) parent signal info in signal -`:location` - Custom ?{:keys [ns line column file]} to override auto signal call location +`:ctx` --------- Custom ?val to override auto (dynamic `*ctx*`) in signal +`:parent` ------ Custom ?{:keys [id uid]} to override auto (dynamic) parent signal info in signal +`:location` ---- Custom ?{:keys [ns line column file]} to override auto signal call location -`:elidable?` - Should signal call be subject to compile-time elision? (Default: true) +`:elidable?` --- Should signal be subject to compile-time elision? (Default: true). `:sample-rate` - ?rate ∈ℝ[0,1] for call sampling (0.75 => allow 75% of signals, nil => allow all) -`:when` - Arb ?form; when present, form must return truthy to allow signal -`:rate-limit` - ?spec as given to `telemere/rate-limiter`, see its docstring for details -`:middleware` - ?[(fn [signal])=>modified-signal ...] call middleware -`:trace?` - Should tracing be enabled for `:run` form? +`:when` -------- Arb ?form; when present, form must return truthy to allow signal +`:rate-limit` -- ?spec as given to `taoensso.telemere/rate-limiter`, see its docstring for details +`:middleware` -- ?[(fn [signal])=>modified-signal ...] signal middleware +`:trace?` ------ Should tracing be enabled for `:run` form? -<extra-kvs> - Arb user-level ?kvs to incl. in signal +<kvs> ---------- Arb other user-level ?kvs to incl. in signal If anything is unclear, please ping me (@ptaoussanis) so that I can improve these docs! [1] `java.time.Instant` or `js/Date` [2] `java.lang.Throwable` or `js/Error`log!
macro
clj
cljs
(log! msg)(log! level msg)(log! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & extra-kvs]} msg)"Log" signal call, focused on message + level. +log!
macro
clj
cljs
(log! msg)(log! level msg)(log! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & kvs]} msg)"Log" signal creator, focused on message + level. -API: [msg] [level-or-opts msg] => true iff signal call was allowed. +API: [msg] [level-or-opts msg] => true iff signal was allowed. Default kind: `:log` Default level: `:info` -When conditions are met [1], creates a Telemere signal [2] and dispatches it to -registered handlers for processing (writing to console/disk/db, etc.). +When filtering conditions are met [1], creates a Telemere signal [2] and +dispatches it to registered handlers for processing (e.g. writing to +console/file/queue/db, etc.). Examples: @@ -460,9 +509,9 @@ Tips: - See also `msg-splice`, `msg-skip` utils. ---------------------------------------- -[1] See `help:signal-handling` docstring -[2] See `help:signal-content` docstring -[3] See `help:signal-options` docstringmsg-skip
clj
cljs
For use within signal message vectors. +[1] See `help:signal-flow` docstring +[2] See `help:signal-content` docstring +[3] See `help:signal-options` docstringmsg-skip
clj
cljs
For use within signal message vectors. Special value that will be ignored (no-op) when creating message. Useful for conditionally skipping parts of message content, etc.: @@ -509,13 +558,17 @@ still registered.set-kind-filter!
clj
cljs
(set-kind-filter! kind-filter)Sets signal call kind filter based on given `kind-filter` spec. + - {:allow <spec> :deny <spec>} with specs as above. + If present, `:allow` spec MUST match, AND + If present, `:deny` spec MUST NOT match.set-kind-filter!
clj
cljs
(set-kind-filter! kind-filter)Sets signal call kind filter based on given `kind-filter` spec. `kind-filter` may be: - A regex pattern of kind/s to allow. - A str/kw/sym, in which "*"s act as wildcards. - A vector or set of regex patterns or strs/kws/syms. - - {:allow <spec> :deny <spec>} with specs as above.set-middleware!
macro
clj
cljs
(set-middleware! root-val)Set `*middleware*` var's root (base) value. See `*middleware*` for details. + - {:allow <spec> :deny <spec>} with specs as above. + If present, `:allow` spec MUST match, AND + If present, `:deny` spec MUST NOT match.set-middleware!
macro
clj
cljs
(set-middleware! root-val)Set `*middleware*` var's root (base) value. See `*middleware*` for details.set-min-level!
clj
cljs
(set-min-level! min-level)(set-min-level! kind min-level)(set-min-level! kind ns-filter min-level)Sets minimum signal call level based on given `min-level` spec. `min-level` may be: @@ -533,33 +586,36 @@ will apply only for that signal kind.set-var-root!
macro
clj
cljs
added in Encore v3.75.0 (2024-01-29)
(set-var-root! var-sym root-val)Sets root binding (value) of the var identified by given symbol, and returns -the new value. Cross-platform. See also `update-var-root!`.shut-down-handlers!
clj
cljs
(shut-down-handlers!)(shut-down-handlers! timeout-msecs__9291__auto__)Shuts down all registered signal handlers and returns + - {:allow <spec> :deny <spec>} with specs as above. + If present, `:allow` spec MUST match, AND + If present, `:deny` spec MUST NOT match.set-var-root!
macro
clj
cljs
added in Encore v3.75.0 (2024-01-29)
(set-var-root! var-sym root-val)Sets root binding (value) of the var identified by given symbol, and returns +the new value. Cross-platform. See also `update-var-root!`.shut-down-handlers!
clj
cljs
(shut-down-handlers!)(shut-down-handlers! timeout-msecs__9337__auto__)Shuts down all registered signal handlers and returns ?{<handler-id> {:keys [okay error]}}. Future calls to handlers will no-op. -Clj only: `shut-down-handlers!` is called automatically on JVM shutdown.signal!
macro
clj
cljs
(signal! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & extra-kvs]})Low-level generic signal call. +Clj only: `shut-down-handlers!` is called automatically on JVM shutdown.signal!
macro
clj
cljs
(signal! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & kvs]})Low-level generic signal creator. API: [opts] => depends on options [3] Default kind: none (optional) Default level: none (must be provided) -When conditions are met [1], creates a Telemere signal [2] and dispatches it to -registered handlers for processing (writing to console/disk/db, etc.). +When filtering conditions are met [1], creates a Telemere signal [2] and +dispatches it to registered handlers for processing (e.g. writing to +console/file/queue/db, etc.). If `:run` option is provided: returns value of given run form, or throws. - Otherwise: returns true iff call conditions were met. + Otherwise: returns true iff signal was created (allowed). Generic signals are fairly low-level and useful mostly for library authors or advanced users writing their own wrapper macros. Regular users will typically -prefer one of the provided wrapper macros optimized for ease-of-use in +prefer one of the higher-level signal creators optimized for ease-of-use in common cases. These all use `signal!` underneath and offer the same options, but vary in their defaults and the focus of their call APIs (args and return values): - `event!` - (id + opts/level) => true iff signal call was allowed - `log!` - (message + opts/level) => true iff signal call was allowed + `event!` - (id + opts/level) => true iff signal was created (allowed) + `log!` - (message + opts/level) => true iff signal was created (allowed) `error!` - (error + opts/id) => given error (unconditional) `trace!` - (form + opts/id) => form's result (value/throw) (unconditional) `spy!` - (form + opts/level) => form's result (value/throw) (unconditional) @@ -569,17 +625,18 @@ Tips: - Test using `with-signal`: (with-signal (signal! ...)). - Supports the same options as other signals [3]. ----------------------------------------- -[1] See `help:signal-handling` docstring -[2] See `help:signal-content` docstring -[3] See `help:signal-options` docstringspy!
macro
clj
cljs
(spy! form)(spy! id form)(spy! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & extra-kvs]} form)"Spy" signal call, focused on form + level. +--------------------------------------- +[1] See `help:signal-flow` docstring +[2] See `help:signal-content` docstring +[3] See `help:signal-options` docstringspy!
macro
clj
cljs
(spy! form)(spy! id form)(spy! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & kvs]} form)"Spy" signal creator, focused on form + level. API: [form] [level-or-opts form] => form's result (value/throw) (unconditional) Default kind: `:spy` Default level: `:info` -When conditions are met [1], creates a Telemere signal [2] and dispatches it to -registered handlers for processing (writing to console/disk/db, etc.). +When filtering conditions are met [1], creates a Telemere signal [2] and +dispatches it to registered handlers for processing (e.g. writing to +console/file/queue/db, etc.). Examples: @@ -601,16 +658,16 @@ Tips: - Identical to `trace!`, but focused on form + level rather than form + id. - Useful for debugging/monitoring forms, and tracing (nested) execution flow. - - Execution of `form` arg may trigger additional (nested) signals. + - Execution of `form` arg may create additional (nested) signals. Each signal's `:parent` key will indicate its immediate parent. - Can be useful to wrap with `catch->error!`: (catch->error! ::error-id (spy! ...)). ----------------------------------------- -[1] See `help:signal-handling` docstring -[2] See `help:signal-content` docstring -[3] See `help:signal-options` docstringstreams->reset!
clj
(streams->reset!)Experimental, subject to change without notice! +--------------------------------------- +[1] See `help:signal-flow` docstring +[2] See `help:signal-content` docstring +[3] See `help:signal-options` docstringstreams->reset!
clj
(streams->reset!)Experimental, subject to change without notice! Resets `System/out` and `System/err` to their original value (prior to any `streams->telemere!` call).streams->telemere!
clj
(streams->telemere!)(streams->telemere! {:keys [out err], :or {out default-out-opts, err default-err-opts}})Experimental, subject to change without notice! @@ -624,14 +681,20 @@ See also: `with-out->telemere`, `with-err->telemere`, `with-streams->telemere`.tools-logging->telemere!
clj
(tools-logging->telemere!)Configures `clojure.tools.logging` to use Telemere as its logging implementation. -trace!
macro
clj
cljs
(trace! form)(trace! id form)(trace! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & extra-kvs]} form)"Trace" signal call, focused on form + id. + +Will be AUTOMATICALLY called if `clojure.tools.logging` is present and any of the +following are "true": + - `clojure.tools.logging->telemere?` JVM propety value + - `CLOJURE_TOOLS_LOGGING_>TELEMERE?` Environment variable + - `clojure.tools.logging->telemere?` Classpath resource contenttrace!
macro
clj
cljs
(trace! form)(trace! id form)(trace! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & kvs]} form)"Trace" signal creator, focused on form + id. API: [form] [id-or-opts form] => form's result (value/throw) (unconditional) Default kind: `:trace` Default level: `:info` (intentionally NOT `:trace`!) -When conditions are met [1], creates a Telemere signal [2] and dispatches it to -registered handlers for processing (writing to console/disk/db, etc.). +When filtering conditions are met [1], creates a Telemere signal [2] and +dispatches it to registered handlers for processing (e.g. writing to +console/file/queue/db, etc.). Examples: @@ -653,7 +716,7 @@ Tips: - Identical to `spy!`, but focused on form + id rather than form + level. - Useful for debugging/monitoring forms, and tracing (nested) execution flow. - - Execution of `form` arg may trigger additional (nested) signals. + - Execution of `form` arg may create additional (nested) signals. Each signal's `:parent` key will indicate its immediate parent. - Can be useful to wrap with `catch->error!`: @@ -663,10 +726,10 @@ Tips: refers to the general action of tracing program flow rather than to the common logging level of the same name. ----------------------------------------- -[1] See `help:signal-handling` docstring -[2] See `help:signal-content` docstring -[3] See `help:signal-options` docstringuncaught->error!
macro
clj
cljs
(uncaught->error!)(uncaught->error! id)(uncaught->error! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & extra-kvs]})Uses `uncaught->handler!` so that `error!` will be called for +--------------------------------------- +[1] See `help:signal-flow` docstring +[2] See `help:signal-content` docstring +[3] See `help:signal-options` docstringuncaught->error!
macro
clj
cljs
(uncaught->error!)(uncaught->error! id)(uncaught->error! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & kvs]})Uses `uncaught->handler!` so that `error!` will be called for uncaught JVM errors. See `uncaught->handler!` and `error!` for details.uncaught->handler!
clj
(uncaught->handler! handler)Sets JVM's global `DefaultUncaughtExceptionHandler` to given @@ -694,12 +757,12 @@ See `*middleware*` for details.with-ns-filter
macro
clj
cljs
(with-ns-filter ns-filter form)Executes form with given signal call namespace filter in effect. See `set-ns-filter!` for details.with-out->telemere
macro
clj
cljs
(with-out->telemere form)(with-out->telemere opts form)Executes form with `*out*` bound to flush to Telemere signals with given opts.with-signal
macro
clj
cljs
(with-signal form)(with-signal trap-signals? form)(with-signal raw-msg? trap-signals? form)Experimental. -Executes given form, trapping errors. Returns the LAST signal triggered by form. +Executes given form, trapping errors. Returns the LAST signal created by form. Useful for tests/debugging. Options: `trap-signals?` (default: false) - Should ALL signals triggered by form be trapped to prevent normal dispatch + Should ALL signals created by form be trapped to prevent normal dispatch to registered handlers? `raw-msg?` (default: false) diff --git a/taoensso.telemere.timbre.cljs.html b/taoensso.telemere.timbre.cljs.html index 5b2496f..c83903f 100644 --- a/taoensso.telemere.timbre.cljs.html +++ b/taoensso.telemere.timbre.cljs.html @@ -1,4 +1,4 @@ -taoensso.telemere.timbre documentation taoensso.telemere.timbre
Main Timbre macros, reimplemented on top of Telemere. +taoensso.telemere.timbre documentation \ No newline at end of file diff --git a/taoensso.telemere.timbre.html b/taoensso.telemere.timbre.html index baf1cc0..b0477b5 100644 --- a/taoensso.telemere.timbre.html +++ b/taoensso.telemere.timbre.html @@ -1,6 +1,6 @@ -taoensso.telemere.timbre
Main Timbre macros, reimplemented on top of Telemere. Intended to help ease migration from Timbre to Telemere.taoensso.telemere.timbre documentation taoensso.telemere.timbre
Main Timbre macros, reimplemented on top of Telemere. +taoensso.telemere.timbre documentation taoensso.telemere.timbre
Main Timbre macros, reimplemented on top of Telemere. Intended to help ease migration from Timbre to Telemere.debug
macro
clj
(debug & args)Prefer `telemere/log!`, etc.debugf
macro
clj
(debugf & args)Prefer `telemere/log!`, etc.error
macro
clj
(error & args)Prefer `telemere/log!`, etc. diff --git a/taoensso.telemere.utils.cljs.html b/taoensso.telemere.utils.cljs.html index 8b22089..c503921 100644 --- a/taoensso.telemere.utils.cljs.html +++ b/taoensso.telemere.utils.cljs.html @@ -1,6 +1,6 @@ -taoensso.telemere.utils documentation taoensso.telemere.utils
Misc utils useful for Telemere handlers, middleware, etc. +taoensso.telemere.utils documentation taoensso.telemere.utils
Misc utils useful for Telemere handlers, middleware, etc.error-in-signal->maps
clj
cljs
(error-in-signal->maps signal)Experimental, subject to change. Returns given signal with possible `:error` replaced by [{:keys [type msg data]} ...] cause chain. @@ -50,7 +50,7 @@ Defaults to `js.console.log` for unmatched signal levels. NB: assumes that `js/console` exists, handler constructors should check first!minify-signal
clj
cljs
(minify-signal signal)Experimental, subject to change. Returns minimal signal map, removing: - Keys with nil values, and - - Keys with redundant values (`:extra-kvs`, `:location`, `:file`). + - Keys with redundant values (`:kvs`, `:location`, `:file`). Useful when serializing signals to edn/JSON/etc.pr-edn
clj
cljs
(pr-edn x)Prints given arg to an edn string readable with `read-edn`. diff --git a/taoensso.telemere.utils.html b/taoensso.telemere.utils.html index 7a8fa61..2389fb8 100644 --- a/taoensso.telemere.utils.html +++ b/taoensso.telemere.utils.html @@ -1,6 +1,6 @@ -taoensso.telemere.utils documentation taoensso.telemere.utils
Misc utils useful for Telemere handlers, middleware, etc. +taoensso.telemere.utils documentation taoensso.telemere.utils
Misc utils useful for Telemere handlers, middleware, etc.error-in-signal->maps
clj
cljs
(error-in-signal->maps signal)Experimental, subject to change. Returns given signal with possible `:error` replaced by [{:keys [type msg data]} ...] cause chain. @@ -56,7 +56,7 @@ Returns a (fn format [signal]) that:minify-signal
clj
cljs
(minify-signal signal)Experimental, subject to change. Returns minimal signal map, removing: - Keys with nil values, and - - Keys with redundant values (`:extra-kvs`, `:location`, `:file`). + - Keys with redundant values (`:kvs`, `:location`, `:file`). Useful when serializing signals to edn/JSON/etc.