<<ahref="https://www.taoensso.com/telemere">https://www.taoensso.com/telemere</a>></pre></div><divclass="public anchor"id="var-*ctx*"><h3>*ctx*</h3><h4class="dynamic">dynamic</h4><h4class="lang"><ahref="taoensso.telemere.html#var-*ctx*">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"></div><divclass="doc"><preclass="plaintext">Dynamic context: arbitrary user-level state attached as `:ctx` to all signals.
Value may be any type, but is usually nil or a map.
Re/bind dynamic value using `with-ctx`, `with-ctx+`, or `binding`.
Modify root (base) value using `set-ctx!`.
Default root (base) value is `default-ctx`.
Note that as with all dynamic Clojure vars, "binding conveyance" applies
when using futures, agents, etc.
Tips:
- Value may be (or may contain) an atom if you want mutable semantics
- Value may be of form {<scope-id><data>} for custom scoping, etc.</pre></div></div><divclass="public anchor"id="var-*middleware*"><h3>*middleware*</h3><h4class="dynamic">dynamic</h4><h4class="lang"><ahref="taoensso.telemere.html#var-*middleware*">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"></div><divclass="doc"><preclass="plaintext">Optional vector of unary middleware fns to apply (sequentially/left-to-right)
to each signal before passing it to handlers. If any middleware fn returns nil,
aborts immediately without calling handlers.
Useful for transforming each signal before handling.
Re/bind dynamic value using `with-middleware`, `binding`.
Modify root (base) value using `set-middleware!`.</pre></div></div><divclass="public anchor"id="var-add-handler.21"><h3>add-handler!</h3><h4class="lang"><ahref="taoensso.telemere.html#var-add-handler.21">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(add-handler! handler-id handler-fn)</code><code>(add-handler! handler-id handler-fn dispatch-opts)</code></div><divclass="doc"><preclass="plaintext">Registers given signal handler and returns
{<handler-id> {:keys [dispatch-opts handler-fn]}} for all signal handlers
otherwise calls will be suppressed before reaching handlers.</pre></div></div><divclass="public anchor"id="var-catch-.3Eerror.21"><h3>catch->error!</h3><h4class="type">macro</h4><h4class="lang"><ahref="taoensso.telemere.html#var-catch-.3Eerror.21">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(catch->error! form)</code><code>(catch->error! id form)</code><code>(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)</code></div><divclass="doc"><preclass="plaintext">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],
then return (:catch-val opts) if it exists, or rethrow the error.
API: [form] [id-or-opts form] => form's result (value/throw) (unconditional), or (:catch-val opts)
:catch-sym my-error ; Sym of caught error, available to `:data` and `:msg`
}
(/ 1 0)) ; %> {... :data {x "x"}, :msg_ "My msg: x <caught>" ...}
Tips:
- Test using `with-signals`: (with-signals (catch->error! ...)).
- Supports the same options as other signals [1].
- Useful for recording errors in forms, futures, callbacks, etc.
See also `error!`.
[1] See `help:signal-options` docstring</pre></div></div><divclass="public anchor"id="var-chance"><h3>chance</h3><h4class="lang"><ahref="taoensso.telemere.html#var-chance">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(chance prob)</code></div><divclass="doc"><preclass="plaintext">Returns true with given probability ∈ ℝ[0,1].
</pre></div></div><divclass="public anchor"id="var-check-interop"><h3>check-interop</h3><h4class="lang"><ahref="taoensso.telemere.html#var-check-interop">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(check-interop)</code></div><divclass="doc"><preclass="plaintext">Experimental, subject to change.
Runs Telemere's registered interop checks and returns
Useful for tests/debugging.</pre></div></div><divclass="public anchor"id="var-console-handler-fn"><h3>console-handler-fn</h3><h4class="lang"><ahref="taoensso.telemere.html#var-console-handler-fn">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(console-handler-fn)</code><code>(console-handler-fn {:keys [format-signal-fn], :or {format-signal-fn (utils/format-signal->str-fn)}})</code></div><divclass="doc"><preclass="plaintext">Experimental, subject to change.
If `js/console` exists, returns a (fn handler [signal]) that:
- Takes a Telemere signal.
- Writes a formatted signal string to JavaScript console.
Common formatting alternatives:
(utils/format-signal-str->fn) ; For human-readable string output (default)
(utils/format-signal->edn-fn) ; For edn output
(utils/format-signal->json-fn) ; For JSON output
etc.
See each format builder for options, etc.</pre></div></div><divclass="public anchor"id="var-default-ctx"><h3>default-ctx</h3><h4class="lang"><ahref="taoensso.telemere.html#var-default-ctx">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"></div><divclass="doc"><preclass="plaintext">Advanced feature. Default root (base) value of `*ctx*` var, controlled by:
See `get-env` for details.</pre></div></div><divclass="public anchor"id="var-error.21"><h3>error!</h3><h4class="type">macro</h4><h4class="lang"><ahref="taoensso.telemere.html#var-error.21">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(error! error)</code><code>(error! id error)</code><code>(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)</code></div><divclass="doc"><preclass="plaintext">"Error" signal call, focused on error + id.
API: [error] [id-or-opts error] => given error (unconditional)
- Test using `with-signals`: (with-signals (error! ...)).
- Supports the same options as other signals [3].
- `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` docstring</pre></div></div><divclass="public anchor"id="var-event.21"><h3>event!</h3><h4class="type">macro</h4><h4class="lang"><ahref="taoensso.telemere.html#var-event.21">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(event! id)</code><code>(event! id level)</code><code>(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]})</code></div><divclass="doc"><preclass="plaintext">"Event" signal call, focused on id + level.
API: [id] [id level-or-opts] => true iff signal call 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.).
`:as` - Parse found value as given type ∈ #{:str :bool :edn} (default :str).
`:default` - Fallback to return if no value found during search (default nil).
`:return` - Return type ∈ #{:value :map :debug} (default :value).
TIP: Use `:debug` to inspect/verify search behaviour!
Result must be something that can be safely embedded in code during
macro-expansion. Symbols in edn will be evaluated during expansion.</pre></div></div><divclass="public anchor"id="var-get-filters"><h3>get-filters</h3><h4class="lang"><ahref="taoensso.telemere.html#var-get-filters">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(get-filters)</code></div><divclass="doc"><preclass="plaintext">Returns current ?{:keys [compile-time runtime]} filter config.
</pre></div></div><divclass="public anchor"id="var-get-handlers"><h3>get-handlers</h3><h4class="lang"><ahref="taoensso.telemere.html#var-get-handlers">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(get-handlers)</code></div><divclass="doc"><preclass="plaintext">Returns ?{<handler-id> {:keys [dispatch-opts handler-fn]}} for all
registered signal handlers.</pre></div></div><divclass="public anchor"id="var-get-min-level"><h3>get-min-level</h3><h4class="lang"><ahref="taoensso.telemere.html#var-get-min-level">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(get-min-level)</code><code>(get-min-level kind)</code><code>(get-min-level kind ns)</code></div><divclass="doc"><preclass="plaintext">Returns current ?{:keys [compile-time runtime]} minimum levels.
</pre></div></div><divclass="public anchor"id="var-help.3Afilters"><h3>help:filters</h3><h4class="lang"><ahref="taoensso.telemere.html#var-help.3Afilters">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"></div><divclass="doc"><preclass="plaintext">Your filter config determines which signal calls will be allowed.
improve these docs!</pre></div></div><divclass="public anchor"id="var-help.3Ahandlers"><h3>help:handlers</h3><h4class="lang"><ahref="taoensso.telemere.html#var-help.3Ahandlers">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"></div><divclass="doc"><preclass="plaintext">The handler API consists of the following:
improve these docs!</pre></div></div><divclass="public anchor"id="var-help.3Asignal-content"><h3>help:signal-content</h3><h4class="lang"><ahref="taoensso.telemere.html#var-help.3Asignal-content">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"></div><divclass="doc"><preclass="plaintext">Signals are initially maps with {:keys [inst id ns level data msg_ ...]},
though they can be modified by call and/or handler middleware.
Default keys:
`:schema` - Int version of signal schema (current: 1)
`:inst` - Platform instant [1] when signal was created
`: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 ?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
`: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
`: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)
`: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
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`</pre></div></div><divclass="public anchor"id="var-help.3Asignal-handling"><h3>help:signal-handling</h3><h4class="lang"><ahref="taoensso.telemere.html#var-help.3Asignal-handling">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"></div><divclass="doc"><preclass="plaintext">A signal will be provided to a handler iff ALL of the following are true:
1. Signal call is allowed by compile-time filters
2. Signal call is allowed by runtime filters
3. Handler is allowed by runtime filters
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. <<ahref="https://tinyurl.com/telemere-signal-flowchart">https://tinyurl.com/telemere-signal-flowchart</a>>
If anything is unclear, please ping me (@ptaoussanis) so that I can
improve these docs!</pre></div></div><divclass="public anchor"id="var-help.3Asignal-options"><h3>help:signal-options</h3><h4class="lang"><ahref="taoensso.telemere.html#var-help.3Asignal-options">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"></div><divclass="doc"><preclass="plaintext">Signal options (shared by `signal!`, `event!`, ...):
`:inst` - Platform instant [1] when signal was created, ∈ #{nil :auto <user-val>}
`:trace?` - Should tracing be enabled for `:run` form?
<extra-kvs> - Arb 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`</pre></div></div><divclass="public anchor"id="var-level-aliases"><h3>level-aliases</h3><h4class="lang"><ahref="taoensso.telemere.html#var-level-aliases">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"></div><divclass="doc"><preclass="plaintext"></pre></div></div><divclass="public anchor"id="var-log.21"><h3>log!</h3><h4class="type">macro</h4><h4class="lang"><ahref="taoensso.telemere.html#var-log.21">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(log! msg)</code><code>(log! level msg)</code><code>(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)</code></div><divclass="doc"><preclass="plaintext">"Log" signal call, focused on message + level.
API: [msg] [level-or-opts msg] => true iff signal call 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.).
- Test using `with-signals`: (with-signals (log! ...)).
- Supports the same options as other signals [3].
- Prefer `event!` to `log!` by default, since it better encourages structured
data over unstructured messages.
- `msg` arg may be a string, or vector of strings to join with `\space`.
- See also `msg-splice`, `msg-skip` utils.
----------------------------------------
[1] See `help:signal-handling` docstring
[2] See `help:signal-content` docstring
[3] See `help:signal-options` docstring</pre></div></div><divclass="public anchor"id="var-msg-skip"><h3>msg-skip</h3><h4class="lang"><ahref="taoensso.telemere.html#var-msg-skip">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"></div><divclass="doc"><preclass="plaintext"></pre></div></div><divclass="public anchor"id="var-msg-splice"><h3>msg-splice</h3><h4class="lang"><ahref="taoensso.telemere.html#var-msg-splice">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(msg-splice args)</code></div><divclass="doc"><preclass="plaintext">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.:
(signal! {:msg [(when <cond> (msg-splice ["Username:" "Steve"])) <...>]}) or
%> {:msg_ "Username: Steve"}</pre></div></div><divclass="public anchor"id="var-newline"><h3>newline</h3><h4class="lang"><ahref="taoensso.telemere.html#var-newline">clj</a></h4><h4class="lang current">cljs</h4><h4class="added">added in Encore v3.68.0 (2023-09-25)</h4><divclass="usage"></div><divclass="doc"><preclass="plaintext">Single system newline
</pre></div></div><divclass="public anchor"id="var-rate-limiter"><h3>rate-limiter</h3><h4class="lang"><ahref="taoensso.telemere.html#var-rate-limiter">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(rate-limiter spec)</code><code>(rate-limiter opts spec)</code></div><divclass="doc"><preclass="plaintext">Takes a map spec of form {<limit-id> [<n-max-reqs><msecs-window>]},
and returns a basic stateful (fn rate-limiter [req-id] [command req-id]).
Call fn with a single request id (e.g. username) by which to count/limit.
If `js/console` exists, returns a (fn handler [signal]) that:
- Takes a Telemere signal.
- Writes raw signal data to JavaScript console.
Intended for use with browser formatting tools like `binaryage/devtools`,
Ref. <<ahref="https://github.com/binaryage/cljs-devtools">https://github.com/binaryage/cljs-devtools</a>>.</pre></div></div><divclass="public anchor"id="var-remove-handler.21"><h3>remove-handler!</h3><h4class="lang"><ahref="taoensso.telemere.html#var-remove-handler.21">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(remove-handler! handler-id)</code></div><divclass="doc"><preclass="plaintext">Deregisters signal handler with given id, and returns
still registered.</pre></div></div><divclass="public anchor"id="var-set-ctx.21"><h3>set-ctx!</h3><h4class="type">macro</h4><h4class="lang"><ahref="taoensso.telemere.html#var-set-ctx.21">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(set-ctx! root-val)</code></div><divclass="doc"><preclass="plaintext">Set `*ctx*` var's root (base) value. See `*ctx*` for details.
</pre></div></div><divclass="public anchor"id="var-set-id-filter.21"><h3>set-id-filter!</h3><h4class="lang"><ahref="taoensso.telemere.html#var-set-id-filter.21">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(set-id-filter! id-filter)</code></div><divclass="doc"><preclass="plaintext">Sets signal call id filter based on given `id-filter` spec.
- A vector or set of regex patterns or strs/kws/syms.
- {:allow <spec> :deny <spec>} with specs as above.</pre></div></div><divclass="public anchor"id="var-set-kind-filter.21"><h3>set-kind-filter!</h3><h4class="lang"><ahref="taoensso.telemere.html#var-set-kind-filter.21">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(set-kind-filter! kind-filter)</code></div><divclass="doc"><preclass="plaintext">Sets signal call kind filter based on given `kind-filter` spec.
- {:allow <spec> :deny <spec>} with specs as above.</pre></div></div><divclass="public anchor"id="var-set-middleware.21"><h3>set-middleware!</h3><h4class="type">macro</h4><h4class="lang"><ahref="taoensso.telemere.html#var-set-middleware.21">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(set-middleware! root-val)</code></div><divclass="doc"><preclass="plaintext">Set `*middleware*` var's root (base) value. See `*middleware*` for details.
</pre></div></div><divclass="public anchor"id="var-set-min-level.21"><h3>set-min-level!</h3><h4class="lang"><ahref="taoensso.telemere.html#var-set-min-level.21">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(set-min-level! min-level)</code><code>(set-min-level! kind min-level)</code><code>(set-min-level! kind ns-filter min-level)</code></div><divclass="doc"><preclass="plaintext">Sets minimum signal call level based on given `min-level` spec.
- A level keyword (see `level-aliases` var for details).
If `ns-filter` is provided, then the given minimum level
will apply only for namespaces that match `ns-filter`.
See `set-ns-filter!` for details.
If non-nil `kind` is provided, then the given minimum level
will apply only for that signal kind.</pre></div></div><divclass="public anchor"id="var-set-ns-filter.21"><h3>set-ns-filter!</h3><h4class="lang"><ahref="taoensso.telemere.html#var-set-ns-filter.21">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(set-ns-filter! ns-filter)</code></div><divclass="doc"><preclass="plaintext">Sets signal call namespace filter based on given `ns-filter` spec.
- {:allow <spec> :deny <spec>} with specs as above.</pre></div></div><divclass="public anchor"id="var-set-var-root.21"><h3>set-var-root!</h3><h4class="type">macro</h4><h4class="lang"><ahref="taoensso.telemere.html#var-set-var-root.21">clj</a></h4><h4class="lang current">cljs</h4><h4class="added">added in Encore v3.75.0 (2024-01-29)</h4><divclass="usage"><code>(set-var-root! var-sym root-val)</code></div><divclass="doc"><preclass="plaintext">Sets root binding (value) of the var identified by given symbol, and returns
the new value. Cross-platform. See also `update-var-root!`.</pre></div></div><divclass="public anchor"id="var-signal.21"><h3>signal!</h3><h4class="type">macro</h4><h4class="lang"><ahref="taoensso.telemere.html#var-signal.21">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(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]})</code></div><divclass="doc"><preclass="plaintext">Low-level generic signal call.
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.).
If `:run` option is provided: returns value of given run form, or throws.
Otherwise: returns true iff call conditions were met.
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
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
`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)
Tips:
- Test using `with-signals`: (with-signals (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` docstring</pre></div></div><divclass="public anchor"id="var-spy.21"><h3>spy!</h3><h4class="type">macro</h4><h4class="lang"><ahref="taoensso.telemere.html#var-spy.21">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(spy! form)</code><code>(spy! id form)</code><code>(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)</code></div><divclass="doc"><preclass="plaintext">"Spy" signal call, 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.).
- Test using `with-signals`: (with-signals (spy! ...)).
- Supports the same options as other signals [3].
- 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.
Each signal's `:parent` key will indicate its immediate parent.
----------------------------------------
[1] See `help:signal-handling` docstring
[2] See `help:signal-content` docstring
[3] See `help:signal-options` docstring</pre></div></div><divclass="public anchor"id="var-trace.21"><h3>trace!</h3><h4class="type">macro</h4><h4class="lang"><ahref="taoensso.telemere.html#var-trace.21">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(trace! form)</code><code>(trace! id form)</code><code>(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)</code></div><divclass="doc"><preclass="plaintext">"Trace" signal call, 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.).
- Test using `with-signals`: (with-signals (trace! ...)).
- Supports the same options as other signals [3].
- 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.
Each signal's `:parent` key will indicate its immediate parent.
- Default level is `:info`, not `:trace`! The name "trace" in "trace signal"
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` docstring</pre></div></div><divclass="public anchor"id="var-uncaught-.3Eerror.21"><h3>uncaught->error!</h3><h4class="type">macro</h4><h4class="lang"><ahref="taoensso.telemere.html#var-uncaught-.3Eerror.21">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(uncaught->error!)</code><code>(uncaught->error! id)</code><code>(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]})</code></div><divclass="doc"><preclass="plaintext">Uses `uncaught->handler!` so that `error!` will be called for
uncaught JVM errors.
See `uncaught->handler!` and `error!` for details.</pre></div></div><divclass="public anchor"id="var-update-var-root.21"><h3>update-var-root!</h3><h4class="type">macro</h4><h4class="lang"><ahref="taoensso.telemere.html#var-update-var-root.21">clj</a></h4><h4class="lang current">cljs</h4><h4class="added">added in Encore v3.68.0 (2023-09-25)</h4><divclass="usage"><code>(update-var-root! var-sym update-fn)</code></div><divclass="doc"><preclass="plaintext">Updates root binding (value) of the var identified by given symbol, and returns
Similar to `alter-var-root` but cross-platform and takes a symbol rather than a var.
See also `set-var-root!`.</pre></div></div><divclass="public anchor"id="var-with-ctx"><h3>with-ctx</h3><h4class="type">macro</h4><h4class="lang"><ahref="taoensso.telemere.html#var-with-ctx">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(with-ctx init-val form)</code></div><divclass="doc"><preclass="plaintext">Evaluates given form with given `*ctx*` value. See `*ctx*` for details.
</pre></div></div><divclass="public anchor"id="var-with-ctx.2B"><h3>with-ctx+</h3><h4class="type">macro</h4><h4class="lang"><ahref="taoensso.telemere.html#var-with-ctx.2B">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(with-ctx+ update-map-or-fn form)</code></div><divclass="doc"><preclass="plaintext">Evaluates given form 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
See `*ctx*` for details.</pre></div></div><divclass="public anchor"id="var-with-err-.3Etelemere"><h3>with-err->telemere</h3><h4class="type">macro</h4><h4class="lang"><ahref="taoensso.telemere.html#var-with-err-.3Etelemere">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(with-err->telemere form)</code><code>(with-err->telemere opts form)</code></div><divclass="doc"><preclass="plaintext">Executes form with `*err*` bound to flush to Telemere signals with given opts.
</pre></div></div><divclass="public anchor"id="var-with-handler"><h3>with-handler</h3><h4class="type">macro</h4><h4class="lang"><ahref="taoensso.telemere.html#var-with-handler">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(with-handler handler-id handler-fn dispatch-opts form)</code></div><divclass="doc"><preclass="plaintext">Executes form with ONLY the given handler-fn registered.
Useful for tests/debugging. See also `with-handler+`.</pre></div></div><divclass="public anchor"id="var-with-handler.2B"><h3>with-handler+</h3><h4class="type">macro</h4><h4class="lang"><ahref="taoensso.telemere.html#var-with-handler.2B">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(with-handler+ handler-id handler-fn dispatch-opts form)</code></div><divclass="doc"><preclass="plaintext">Executes form with the given handler-fn registered.
Useful for tests/debugging. See also `with-handler`.</pre></div></div><divclass="public anchor"id="var-with-id-filter"><h3>with-id-filter</h3><h4class="type">macro</h4><h4class="lang"><ahref="taoensso.telemere.html#var-with-id-filter">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(with-id-filter id-filter form)</code></div><divclass="doc"><preclass="plaintext">Executes form with given signal call id filter in effect.
See `set-id-filter!` for details.</pre></div></div><divclass="public anchor"id="var-with-kind-filter"><h3>with-kind-filter</h3><h4class="type">macro</h4><h4class="lang"><ahref="taoensso.telemere.html#var-with-kind-filter">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(with-kind-filter kind-filter form)</code></div><divclass="doc"><preclass="plaintext">Executes form with given signal call kind filter in effect.
See `set-kind-filter!` for details.</pre></div></div><divclass="public anchor"id="var-with-middleware"><h3>with-middleware</h3><h4class="type">macro</h4><h4class="lang"><ahref="taoensso.telemere.html#var-with-middleware">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(with-middleware init-val form)</code></div><divclass="doc"><preclass="plaintext">Evaluates given form with given `*middleware*` value.
See `*middleware*` for details.</pre></div></div><divclass="public anchor"id="var-with-min-level"><h3>with-min-level</h3><h4class="type">macro</h4><h4class="lang"><ahref="taoensso.telemere.html#var-with-min-level">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(with-min-level min-level form)</code><code>(with-min-level kind min-level form)</code><code>(with-min-level kind ns-filter min-level form)</code></div><divclass="doc"><preclass="plaintext">Executes form with given minimum signal call level in effect.
See `set-min-level!` for details.</pre></div></div><divclass="public anchor"id="var-with-ns-filter"><h3>with-ns-filter</h3><h4class="type">macro</h4><h4class="lang"><ahref="taoensso.telemere.html#var-with-ns-filter">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(with-ns-filter ns-filter form)</code></div><divclass="doc"><preclass="plaintext">Executes form with given signal call namespace filter in effect.
See `set-ns-filter!` for details.</pre></div></div><divclass="public anchor"id="var-with-out-.3Etelemere"><h3>with-out->telemere</h3><h4class="type">macro</h4><h4class="lang"><ahref="taoensso.telemere.html#var-with-out-.3Etelemere">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(with-out->telemere form)</code><code>(with-out->telemere opts form)</code></div><divclass="doc"><preclass="plaintext">Executes form with `*out*` bound to flush to Telemere signals with given opts.
Executes given form and returns the last signal triggered by it.
Useful for tests/debugging.
- Always allows registered handlers to receive signals as usual.
- Always traps form errors.
- Never forces `:msg_` key.
See also `with-signals` for more options.</pre></div></div><divclass="public anchor"id="var-with-signals"><h3>with-signals</h3><h4class="type">macro</h4><h4class="lang"><ahref="taoensso.telemere.html#var-with-signals">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(with-signals form)</code><code>(with-signals {:keys [handle? trap-errors? force-msg?], :or {handle? true}} form)</code></div><divclass="doc"><preclass="plaintext">Experimental.
Executes given form and records any signals triggered by it.
Return value depends on given options. Useful for tests/debugging.
Options:
`handle?`
Should registered handlers receive signals triggered by form, as usual?
Default: true.
`trap-errors?`
If true: returns [[form-value form-error] signals], trapping any form error.
If false: returns [ form-value signals], throwing on form error.
Default: false.
`force-msg?`
Should delayed `:msg_` keys in signals be replaced with realized strings?
Default: false.
See also `with-signal` for a simpler API.</pre></div></div><divclass="public anchor"id="var-with-streams-.3Etelemere"><h3>with-streams->telemere</h3><h4class="type">macro</h4><h4class="lang"><ahref="taoensso.telemere.html#var-with-streams-.3Etelemere">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(with-streams->telemere form)</code><code>(with-streams->telemere {:keys [out err], :or {out default-out-opts, err default-err-opts}} form)</code></div><divclass="doc"><preclass="plaintext">Executes form with `*out*` and/or `*err*` bound to flush to Telemere signals
with given opts.</pre></div></div><divclass="public anchor"id="var-without-filters"><h3>without-filters</h3><h4class="type">macro</h4><h4class="lang"><ahref="taoensso.telemere.html#var-without-filters">clj</a></h4><h4class="lang current">cljs</h4><divclass="usage"><code>(without-filters form)</code></div><divclass="doc"><preclass="plaintext">Executes form without any runtime filters.
