luciano/telemere
1
0
Fork 0
mirror of https://github.com/taoensso/telemere.git synced 2025-12-28 06:08:25 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
telemere/taoensso.telemere.cljs.html
Peter Taoussanis d564c3db93 v1.0.0-beta4 (2024-04-29)
2024-04-29 09:21:13 +02:00

778 lines
No EOL
66 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html PUBLIC ""
"">
<html><head><meta charset="UTF-8" /><title>taoensso.telemere documentation</title><link rel="stylesheet" type="text/css" href="css/default.css" /><link rel="stylesheet" type="text/css" href="css/highlight.css" /><script type="text/javascript" src="js/highlight.min.js"></script><script type="text/javascript" src="js/jquery.min.js"></script><script type="text/javascript" src="js/page_effects.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body><div id="header"><h2>Generated by <a href="https://github.com/weavejester/codox">Codox</a></h2><h1><a href="index.html"><span class="project-title"><span class="project-name">Telemere</span> <span class="project-version">1.0.0-beta4</span></span></a></h1><div id="langs"><div class="lang"><a href="index.clj.html">clj</a></div><div class="lang current">cljs</div></div></div><div class="sidebar primary"><h3 class="no-link"><span class="inner">Namespaces</span></h3><ul><li class="depth-1"><div class="no-link"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>taoensso</span></div></div></li><li class="depth-2 current"><a href="taoensso.telemere.cljs.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>telemere</span></div></a></li><li class="depth-3 branch"><a href="taoensso.telemere.timbre.cljs.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>timbre</span></div></a></li><li class="depth-3"><a href="taoensso.telemere.utils.cljs.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>utils</span></div></a></li></ul></div><div class="sidebar secondary"><h3><a href="#top"><span class="inner">Public Vars</span></a></h3><ul><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-*ctx*"><div class="inner"><span>*ctx*</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-*middleware*"><div class="inner"><span>*middleware*</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-add-handler.21"><div class="inner"><span>add-handler!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-catch-.3Eerror.21"><div class="inner"><span>catch-&gt;error!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-chance"><div class="inner"><span>chance</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-default-ctx"><div class="inner"><span>default-ctx</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-error.21"><div class="inner"><span>error!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-error-signal.3F"><div class="inner"><span>error-signal?</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-event.21"><div class="inner"><span>event!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-get-env"><div class="inner"><span>get-env</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-get-filters"><div class="inner"><span>get-filters</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-get-handlers"><div class="inner"><span>get-handlers</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-get-min-level"><div class="inner"><span>get-min-level</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-handler.3Aconsole"><div class="inner"><span>handler:console</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-handler.3Aconsole-raw"><div class="inner"><span>handler:console-raw</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-help.3Afilters"><div class="inner"><span>help:filters</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-help.3Ahandlers"><div class="inner"><span>help:handlers</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-help.3Asignal-content"><div class="inner"><span>help:signal-content</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-help.3Asignal-creators"><div class="inner"><span>help:signal-creators</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-help.3Asignal-filters"><div class="inner"><span>help:signal-filters</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-help.3Asignal-flow"><div class="inner"><span>help:signal-flow</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-help.3Asignal-formatters"><div class="inner"><span>help:signal-formatters</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-help.3Asignal-handlers"><div class="inner"><span>help:signal-handlers</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-help.3Asignal-options"><div class="inner"><span>help:signal-options</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-level-aliases"><div class="inner"><span>level-aliases</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-log.21"><div class="inner"><span>log!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-msg-skip"><div class="inner"><span>msg-skip</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-msg-splice"><div class="inner"><span>msg-splice</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-newline"><div class="inner"><span>newline</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-rate-limiter"><div class="inner"><span>rate-limiter</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-remove-handler.21"><div class="inner"><span>remove-handler!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-set-ctx.21"><div class="inner"><span>set-ctx!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-set-id-filter.21"><div class="inner"><span>set-id-filter!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-set-kind-filter.21"><div class="inner"><span>set-kind-filter!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-set-middleware.21"><div class="inner"><span>set-middleware!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-set-min-level.21"><div class="inner"><span>set-min-level!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-set-ns-filter.21"><div class="inner"><span>set-ns-filter!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-set-var-root.21"><div class="inner"><span>set-var-root!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-shut-down-handlers.21"><div class="inner"><span>shut-down-handlers!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-signal.21"><div class="inner"><span>signal!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-spy.21"><div class="inner"><span>spy!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-trace.21"><div class="inner"><span>trace!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-uncaught-.3Eerror.21"><div class="inner"><span>uncaught-&gt;error!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-update-var-root.21"><div class="inner"><span>update-var-root!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-with-ctx"><div class="inner"><span>with-ctx</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-with-ctx.2B"><div class="inner"><span>with-ctx+</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-with-err-.3Etelemere"><div class="inner"><span>with-err-&gt;telemere</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-with-handler"><div class="inner"><span>with-handler</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-with-handler.2B"><div class="inner"><span>with-handler+</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-with-id-filter"><div class="inner"><span>with-id-filter</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-with-kind-filter"><div class="inner"><span>with-kind-filter</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-with-middleware"><div class="inner"><span>with-middleware</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-with-min-level"><div class="inner"><span>with-min-level</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-with-ns-filter"><div class="inner"><span>with-ns-filter</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-with-out-.3Etelemere"><div class="inner"><span>with-out-&gt;telemere</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-with-signal"><div class="inner"><span>with-signal</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-with-signals"><div class="inner"><span>with-signals</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-with-streams-.3Etelemere"><div class="inner"><span>with-streams-&gt;telemere</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-without-filters"><div class="inner"><span>without-filters</span></div></a></li></ul></div><div class="namespace-docs" id="content"><h1 class="anchor" id="top">taoensso.telemere</h1><div class="doc"><pre class="plaintext">Structured telemetry for Clojure/Script applications.
See the GitHub page (esp. Wiki) for info on motivation and design:
&lt;<a href="https://www.taoensso.com/telemere">https://www.taoensso.com/telemere</a>&gt;</pre></div><div class="public anchor" id="var-*ctx*"><h3>*ctx*</h3><h4 class="dynamic">dynamic</h4><h4 class="lang"><a href="taoensso.telemere.html#var-*ctx*">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"></div><div class="doc"><pre class="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 {&lt;scope-id&gt; &lt;data&gt;} for custom scoping, etc.</pre></div></div><div class="public anchor" id="var-*middleware*"><h3>*middleware*</h3><h4 class="dynamic">dynamic</h4><h4 class="lang"><a href="taoensso.telemere.html#var-*middleware*">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"></div><div class="doc"><pre class="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><div class="public anchor" id="var-add-handler.21"><h3>add-handler!</h3><h4 class="lang"><a href="taoensso.telemere.html#var-add-handler.21">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(add-handler! handler-id handler-fn)</code><code>(add-handler! handler-id handler-fn dispatch-opts)</code></div><div class="doc"><pre class="plaintext">Registers given signal handler and returns
{&lt;handler-id&gt; {:keys [dispatch-opts handler-fn]}} for all signal handlers
now registered.
`handler-fn` should be a fn of 1-2 arities:
([handler-arg]) =&gt; Handle the given argument (e.g. write to disk/db, etc.)
([]) =&gt; Optional arity, called exactly once on system shutdown.
Provides an opportunity for handler to close/release
any resources that it may have opened/acquired.
See the relevant docstring/s for `handler-arg` details.
Handler ideas:
Save to a db, `tap&gt;`, log, `put!` to an appropriate `core.async`
channel, filter, aggregate, use for a realtime analytics dashboard,
examine for outliers or unexpected data, etc.
Dispatch options include:
`async` (Clj only)
Options for running handler asynchronously via `taoensso.encore/runner`,
{:keys [mode buffer-size n-threads daemon-threads? ...]}
Supports `:blocking`, `:dropping`, and `:sliding` back-pressure modes.
NB handling order may be non-sequential when `n-threads` &gt; 1.
Default:
{:mode :dropping, :buffer-size 1024, :n-threads 1, :daemon-threads? true}
I.e. async by default, with a buffer of size 1024 that drops new entries
when full.
Options:
`mode` - Mode of operation, ∈ #{:sync :blocking :dropping :sliding}.
`buffer-size` - Size of buffer before back-pressure mechanism is engaged.
`n-threads` - Number of threads for asynchronously executing fns.
NB execution order may be non-sequential when n &gt; 1.
`priority`
Optional handler priority ∈ℤ (default 100). Handlers will be called in
descending priority order.
`sample-rate`
Optional sample rate ∈ℝ[0,1], or (fn dyamic-sample-rate []) =&gt; ℝ[0,1].
When present, handle only this (random) proportion of args:
1.0 =&gt; handle every arg (same as `nil` rate, default)
0.0 =&gt; noop every arg
0.5 =&gt; handle random 50% of args
`kind-filter` - Kind filter as in `set-kind-filter!` (when relevant)
`ns-filter` - Namespace filter as in `set-ns-filter!`
`id-filter` - Id filter as in `set-id-filter!` (when relevant)
`min-level` - Minimum level as in `set-min-level!`
`when-fn`
Optional nullary (fn allow? []) that must return truthy for handler to be
called. When present, called *after* sampling and other filters, but before
rate limiting.
`rate-limit`
Optional rate limit spec as provided to `taoensso.encore/rate-limiter`,
{&lt;limit-id&gt; [&lt;n-max-calls&gt; &lt;msecs-window&gt;]}.
Examples:
{"1/sec" [1 1000]} =&gt; Max 1 call per 1000 msecs
{"1/sec" [1 1000]
"10/min" [10 60000]} =&gt; Max 1 call per 1000 msecs,
and 10 calls per 60 secs
`middleware`
Optional vector of unary middleware fns to apply (left-to-right/sequentially)
to `handler-arg` before passing to `handler-fn`. If any middleware fn returns
nil, aborts immediately without calling `handler-fn`.
Useful for transforming `handler-arg` before handling.
`error-fn` - (fn [{:keys [handler-id handler-arg error]}]) to call on handler error.
`backp-fn` - (fn [{:keys [handler-id ]}]) to call on handler back-pressure.
Flow sequence:
1. Per call (n=1)
a. Sampling
b. Filtering (kind, namespace, id, level, when-form)
c. Rate limiting
d. Middleware
2. Per handler (n&gt;=0)
a. Sampling
b. Filtering (kind, namespace, id, level, when-fn)
c. Rate limiting
d. Middleware
e. Hander fn
Note: call filters should generally be at least as permissive as handler filters,
otherwise calls will be suppressed before reaching handlers.</pre></div></div><div class="public anchor" id="var-catch-.3Eerror.21"><h3>catch-&gt;error!</h3><h4 class="type">macro</h4><h4 class="lang"><a href="taoensso.telemere.html#var-catch-.3Eerror.21">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(catch-&gt;error! form)</code><code>(catch-&gt;error! id form)</code><code>(catch-&gt;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 &amp; kvs]} form)</code></div><div class="doc"><pre class="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 [2],
then return (:catch-val opts) if it exists, or rethrow the error.
API: [form] [id-or-opts form] =&gt; form's result (value/throw) (unconditional), or (:catch-val opts)
Default kind: `:error`
Default level: `:error`
Examples:
(catch-&gt;error! (/ 1 0)) ; %&gt; {:kind :error, :level :error, :error &lt;caught&gt; ...}
(catch-&gt;error! ::my-id (/ 1 0)) ; %&gt; {... :id ::my-id ...}
(catch-&gt;error!
{:let [x "x"] ; Available to `:data` and `:msg`
:data {:x x}
:msg ["My msg:" x my-error]
:catch-val "Return value when form throws"
:catch-sym my-error ; Sym of caught error, available to `:data` and `:msg`
}
(/ 1 0)) ; %&gt; {... :data {x "x"}, :msg_ "My msg: x &lt;caught&gt;" ...}
Tips:
- Test using `with-signal`: (with-signal (catch-&gt;error! ...)).
- Supports the same options [2] as other signals [1].
- Useful for recording errors in forms, futures, callbacks, etc.
See also `error!`.
-------------------------------------------------------------------
[1] See `help:signal-creators` - (`signal!`, `log!`, `event!`, ...)
[2] See `help:signal-options` - {:keys [kind level id data ...]}
[3] See `help:signal-content` - {:keys [kind level id data ...]}
[4] See `help:signal-flow` - (filters, handling, etc.)</pre></div></div><div class="public anchor" id="var-chance"><h3>chance</h3><h4 class="lang"><a href="taoensso.telemere.html#var-chance">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(chance prob)</code></div><div class="doc"><pre class="plaintext">Returns true with given probability ∈ ℝ[0,1].
</pre></div></div><div class="public anchor" id="var-default-ctx"><h3>default-ctx</h3><h4 class="lang"><a href="taoensso.telemere.html#var-default-ctx">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"></div><div class="doc"><pre class="plaintext">Default root (base) value of `*ctx*` var.
Defaults to `nil`, controlled by:
(get-env {:as :edn} :taoensso.telemere/default-ctx&lt;.platform&gt;&lt;.edn&gt;)
See `get-env` for details.</pre></div></div><div class="public anchor" id="var-error.21"><h3>error!</h3><h4 class="type">macro</h4><h4 class="lang"><a href="taoensso.telemere.html#var-error.21">clj</a></h4><h4 class="lang current">cljs</h4><div class="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 &amp; kvs]} error)</code></div><div class="doc"><pre class="plaintext">"Error" signal creator, emphasizing error + id.
API: [error] [id-or-opts error] =&gt; given error (unconditional)
Default kind: `:error`
Default level: `:error`
Examples:
(throw (error! (ex-info "MyEx" {}))) ; %&gt; {:kind :error, :level :error, :error &lt;MyEx&gt; ...}
(throw (error! ::my-id (ex-info "MyEx" {}))) ; %&gt; {... :id ::my-id ...}
(throw
(error!
{:let [x "x"] ; Available to `:data` and `:msg`
:data {:x x}
:msg ["My message:" x]}
(ex-info "MyEx" {}))) ; %&gt; {... :data {x "x"}, :msg_ "My msg: x" ...}
Tips:
- Test using `with-signal`: (with-signal (error! ...)).
- Supports the same options [2] as other signals [1].
- `error` arg is a platform error (`java.lang.Throwable` or `js/Error`).
- Can conveniently be wrapped by `throw`: (throw (error! ...)).
-------------------------------------------------------------------
[1] See `help:signal-creators` - (`signal!`, `log!`, `event!`, ...)
[2] See `help:signal-options` - {:keys [kind level id data ...]}
[3] See `help:signal-content` - {:keys [kind level id data ...]}
[4] See `help:signal-flow` - (filters, handling, etc.)</pre></div></div><div class="public anchor" id="var-error-signal.3F"><h3>error-signal?</h3><h4 class="lang"><a href="taoensso.telemere.html#var-error-signal.3F">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(error-signal? signal)</code></div><div class="doc"><pre class="plaintext">Experimental, subject to change.
Returns true iff given signal has an `:error` value, or a `:kind` or `:level`
that indicates that it's an error.</pre></div></div><div class="public anchor" id="var-event.21"><h3>event!</h3><h4 class="type">macro</h4><h4 class="lang"><a href="taoensso.telemere.html#var-event.21">clj</a></h4><h4 class="lang current">cljs</h4><div class="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 &amp; kvs]})</code></div><div class="doc"><pre class="plaintext">"Event" signal creator, emphasizing id + level.
API: [id] [id level-or-opts] =&gt; true iff signal was allowed
Default kind: `:event`
Default level: `:info`
When filtering conditions are met [4], creates a Telemere signal [3] and
dispatches it to registered handlers for processing (e.g. writing to
console/file/queue/db, etc.).
Examples:
(event! ::my-id) ; %&gt; {:kind :event, :level :info, :id ::my-id ...}
(event! ::my-id :warn) ; %&gt; {... :level :warn ...}
(event! ::my-id
{:let [x "x"] ; Available to `:data` and `:msg`
:data {:x x}
:msg ["My msg:" x]}) ; %&gt; {... :data {x "x"}, :msg_ "My msg: x" ...}
Tips:
- Test using `with-signal`: (with-signal (event! ...)).
- Supports the same options [2] as other signals [1].
- `log!` and `event!` are both good default/general-purpose signal creators.
- `log!` emphasizes messages, while `event!` emphasizes ids.
- Has a different 2-arity arg order to all other signals!
Mnemonic: the arg that's typically larger is *always* in the rightmost
position, and for `event!` that's the `level-or-opts` arg.
-------------------------------------------------------------------
[1] See `help:signal-creators` - (`signal!`, `log!`, `event!`, ...)
[2] See `help:signal-options` - {:keys [kind level id data ...]}
[3] See `help:signal-content` - {:keys [kind level id data ...]}
[4] See `help:signal-flow` - (filters, handling, etc.)</pre></div></div><div class="public anchor" id="var-get-env"><h3>get-env</h3><h4 class="type">macro</h4><h4 class="lang"><a href="taoensso.telemere.html#var-get-env">clj</a></h4><h4 class="lang current">cljs</h4><h4 class="added">added in Encore v3.75.0 (2024-01-29)</h4><div class="usage"><code>(get-env {:keys [as default return], :or {as :str, return :value}} spec)</code></div><div class="doc"><pre class="plaintext">Flexible cross-platform util for embedding a config value during
macro expansion. Used by other Taoensso libraries.
Given a const kw/string id or vector of desc-priority alternative ids,
parse and return the first of the following that exists:
- JVM property value for id
- Environment variable value for id
- Classpath resource content for id
Ids may include optional segment in `&lt;&gt;` tag (e.g. `&lt;.edn&gt;`).
Ids may include `&lt;.?platform.?&gt;` tag for auto replacement, useful
for supporting platform-specific config.
Search order: desc by combined [alt-index platform(y/n) optional(y/n)].
So (get-env {:as :edn} [:my-app/alt1&lt;.platform&gt;&lt;.edn&gt; :my-app/alt2])
will parse and return the first of the following that exists:
1. Alt1 +platform +optional (.edn suffix)
1a. `my-app.alt1.clj.edn` JVM property value
1b. `MY_APP_ALT1_CLJ_EDN` environment variable value
1c. `my-app.alt1.clj.edn` classpath resource content
2. Alt1 +platform -optional (.edn suffix)
2a. `my-app.alt1.clj` JVM property value
2b. `MY_APP_ALT1_CLJ` environment variable value
2c. `my-app.alt1.clj` classpath resource content
3. Alt1 -platform +optional (.edn suffix)
3a. `my-app.alt1.edn` JVM property value
3b. `MY_APP_ALT1_EDN` environment variable value
3c. `my-app.alt1.edn` classpath resource content
4. Alt1 -platform -optional (.edn suffix)
4a. `my-app.alt1` JVM property value
4b. `MY_APP_ALT1` environment variable value
4c. `my-app.alt1` classpath resource content
5. Alt2
5a. `my-app.alt2` JVM property value
5b. `MY_APP_ALT2` environment variable value
5c. `my-app.alt2` classpath resource content
Options:
`:as` - Parse found value as given type ∈ #{:str :bool :edn} (default `:str`).
`:default` - Fallback to return unparsed if no value found during search (default `nil`).
`:return` - Return type ∈ #{:value :map :explain} (default `:value`).
Resulting config value must be something that can be safely embedded in code during
macro-expansion. Symbols in edn will be evaluated during expansion.
TIP!: Use the {:return :explain} option in tests or at the REPL to verify/inspect
resulting config value, config source, and specific search order of prop/env/res ids.</pre></div></div><div class="public anchor" id="var-get-filters"><h3>get-filters</h3><h4 class="lang"><a href="taoensso.telemere.html#var-get-filters">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(get-filters)</code></div><div class="doc"><pre class="plaintext">Returns current ?{:keys [compile-time runtime]} filter config.
</pre></div></div><div class="public anchor" id="var-get-handlers"><h3>get-handlers</h3><h4 class="lang"><a href="taoensso.telemere.html#var-get-handlers">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(get-handlers)</code></div><div class="doc"><pre class="plaintext">Returns ?{&lt;handler-id&gt; {:keys [dispatch-opts handler-fn]}} for all
registered signal handlers.</pre></div></div><div class="public anchor" id="var-get-min-level"><h3>get-min-level</h3><h4 class="lang"><a href="taoensso.telemere.html#var-get-min-level">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(get-min-level)</code><code>(get-min-level kind)</code><code>(get-min-level kind ns)</code></div><div class="doc"><pre class="plaintext">Returns current ?{:keys [compile-time runtime]} minimum levels.
</pre></div></div><div class="public anchor" id="var-handler.3Aconsole"><h3>handler:console</h3><h4 class="lang"><a href="taoensso.telemere.html#var-handler.3Aconsole">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(handler:console)</code><code>(handler:console {:keys [format-signal-fn], :or {format-signal-fn (utils/format-signal-&gt;str-fn)}})</code></div><div class="doc"><pre class="plaintext">Experimental, subject to change. Feedback welcome!
If `js/console` exists, returns a (fn handler [signal]) that:
- Takes a Telemere signal.
- Writes a formatted signal string to JavaScript console.
A general-purpose `println`-style handler that's well suited for outputting
signals formatted as edn, JSON, or human-readable strings.
Options:
`:format-signal-fn` - (fn [signal]) =&gt; output, see `help:signal-formatters`</pre></div></div><div class="public anchor" id="var-handler.3Aconsole-raw"><h3>handler:console-raw</h3><h4 class="lang current">cljs</h4><div class="usage"><code>(handler:console-raw)</code><code>(handler:console-raw {:keys [format-signal-&gt;prelude-fn format-nsecs-fn], :as opts, :or {format-signal-&gt;prelude-fn (utils/format-signal-&gt;prelude-fn), format-nsecs-fn (utils/format-nsecs-fn)}})</code></div><div class="doc"><pre class="plaintext">Experimental, subject to change. Feedback welcome!
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. &lt;<a href="https://github.com/binaryage/cljs-devtools">https://github.com/binaryage/cljs-devtools</a>&gt;.</pre></div></div><div class="public anchor" id="var-help.3Afilters"><h3>help:filters</h3><h4 class="lang"><a href="taoensso.telemere.html#var-help.3Afilters">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"></div><div class="doc"><pre class="plaintext">Your filter config determines which signal calls will be allowed.
Filtering can occur at compile-time, runtime, or both.
Compile-time filtering elides (permanently removes!) code for
disallowed signals. Most users will want only runtime filtering.
Both compile-time and runtime config can be specified via
environmental config (JVM properties, environment variables, or
classpath resources) [1].
Runtime config can also be specified with:
`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-min-level!`, `with-min-level!` - for filtering calls by signal level
See the relevant docstrings for details.
Filtering can also be applied per handler, 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!
[1] (impl/signal-docstring :filter-env-config)</pre></div></div><div class="public anchor" id="var-help.3Ahandlers"><h3>help:handlers</h3><h4 class="lang"><a href="taoensso.telemere.html#var-help.3Ahandlers">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"></div><div class="doc"><pre class="plaintext">Manage handlers with:
`get-handlers` - Returns info on registered handlers
`shut-down-handlers!` - Shuts down registered handlers
`add-handler!` - Registers given handler
`remove-handler!` - Unregisters given handler
See the relevant docstrings for details.
Clj only: `shut-down-handlers!` is called automatically on JVM shutdown.
If anything is unclear, please ping me (@ptaoussanis) so that I can
improve these docs!</pre></div></div><div class="public anchor" id="var-help.3Asignal-content"><h3>help:signal-content</h3><h4 class="lang"><a href="taoensso.telemere.html#var-help.3Asignal-content">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"></div><div class="doc"><pre class="plaintext">Signals are maps with {:keys [inst id ns level data msg_ ...]},
though they can be modified by signal and/or handler middleware.
Default signal keys:
`:schema` ------ Int version of signal schema (current: 1)
`:inst` -------- Platform instant [1] when signal was created
`:level` ------- Signal level ∈ #{&lt;int&gt; :trace :debug :info :warn :error :fatal :report ...}
`:kind` -------- Signal ?kind ∈ #{nil :event :error :log :trace :spy &lt;user-val&gt; ...}
`: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 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 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 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 =&gt; allow 75% of signals, nil =&gt; allow all)
&lt;kvs&gt; ---------- Other arb user-level ?kvs given to signal creator. Typically NOT included
in handler output, so a great way to provide custom data/opts for use
(only) by custom middleware/handlers.
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><div class="public anchor" id="var-help.3Asignal-creators"><h3>help:signal-creators</h3><h4 class="lang"><a href="taoensso.telemere.html#var-help.3Asignal-creators">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"></div><div class="doc"><pre class="plaintext">Call a Telemere signal creator to conditionally create a signal at that callsite.
When filtering conditions are met [4], the call creates a Telemere signal [3]
and dispatches it to registered handlers for processing (e.g. writing to
console/file/queue/db, etc.).
Telemere doesn't make a hard distinction between different kinds of signals
(log, event, error, etc.) - they're all just plain Clojure/Script maps with
various keys:
- All signal creators offer the same options [2], and
- All signal kinds can contain the same content [3]
Creators vary only in in their default options and call APIs (expected args
and return values), making them more/less convenient for certain use cases:
`log!` ---------- [message + opts/level] =&gt; true iff signal was created (allowed)
`event!` -------- [id + opts/level] =&gt; true iff signal was created (allowed)
`error!` -------- [error + opts/id ] =&gt; given error (unconditional)
`trace!` -------- [form + opts/id ] =&gt; form result (value/throw) (unconditional)
`spy!` ---------- [form + opts/level] =&gt; form result (value/throw) (unconditional)
`catch-&gt;error!` - [error + opts/id ] =&gt; form value, or given fallback
`signal!` ------- [ opts ] =&gt; depends on options
- `log!` and `event!` are both good default/general-purpose signal creators.
- `log!` emphasizes messages, while `event!` emphasizes ids.
- `signal!` is the generic creator, and is used by all the others.
-------------------------------------------------------------------
[2] See `help:signal-options` - {:keys [kind level id data ...]}
[3] See `help:signal-content` - {:keys [kind level id data ...]}
[4] See `help:signal-flow` - (filters, handling, etc.)</pre></div></div><div class="public anchor" id="var-help.3Asignal-filters"><h3>help:signal-filters</h3><h4 class="lang"><a href="taoensso.telemere.html#var-help.3Asignal-filters">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"></div><div class="doc"><pre class="plaintext"></pre></div></div><div class="public anchor" id="var-help.3Asignal-flow"><h3>help:signal-flow</h3><h4 class="lang"><a href="taoensso.telemere.html#var-help.3Asignal-flow">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"></div><div class="doc"><pre class="plaintext">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
Compile-time vs runtime filtering:
Compile-time filtering is an advanced feature that can be tricky to set
and use correctly. Most folks will want ONLY runtime filtering.
Compile-time filtering works by eliding (completely removing the code for)
disallowed signals. This means zero performance cost for these signals,
but also means that compile-time filtering is PERMANENT once applied.
So if you set `:info` as the compile-time minimum level, that'll REMOVE
CODE for every signal call below `:info` level. To decrease that minimum
level, you'll need to rebuild.
Compile-time filtering can be set ONLY with environmental config
(JVM properties, environment variables, or classpath resources).
Signal and handler sampling is multiplicative:
Both signals and handlers can have independent sample rates, and these
MULTIPLY!
If a signal is created with 20% sampling and a handler handles 50%
of received signals, then 10% of possible signals will be handled
(50% of 20%).
The multiplicative rate is helpfully reflected in each signal's final
`:sample-rate` value.
For more info:
- Signal visual flowchart, Ref. &lt;<a href="https://www.taoensso.com/telemere/flow">https://www.taoensso.com/telemere/flow</a>&gt;
- On signal filters, see: `help:signal-filters` docstring
- On handler filters, see: `help:signal-handlers` docstring
If anything is unclear, please ping me (@ptaoussanis) so that I can
improve these docs!</pre></div></div><div class="public anchor" id="var-help.3Asignal-formatters"><h3>help:signal-formatters</h3><h4 class="lang"><a href="taoensso.telemere.html#var-help.3Asignal-formatters">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"></div><div class="doc"><pre class="plaintext">Common signal formatters include:
(utils/format-signal-str-&gt;fn) {&lt;opts&gt;}) ; For human-readable string output (default)
(utils/format-signal-&gt;edn-fn) {&lt;opts&gt;}) ; For edn output
(utils/format-signal-&gt;json-fn {&lt;opts&gt;}) ; For JSON output
See relevant docstrings for details.</pre></div></div><div class="public anchor" id="var-help.3Asignal-handlers"><h3>help:signal-handlers</h3><h4 class="lang"><a href="taoensso.telemere.html#var-help.3Asignal-handlers">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"></div><div class="doc"><pre class="plaintext"></pre></div></div><div class="public anchor" id="var-help.3Asignal-options"><h3>help:signal-options</h3><h4 class="lang"><a href="taoensso.telemere.html#var-help.3Asignal-options">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"></div><div class="doc"><pre class="plaintext">Signal options (shared by all signal creators):
`:inst` -------- Platform instant [1] when signal was created, ∈ #{nil :auto &lt;user-val&gt;}
`:level` ------- Signal level ∈ #{&lt;int&gt; :trace :debug :info :warn :error :fatal :report ...}
`:kind` -------- Signal ?kind ∈ #{nil :event :error :log :trace :spy &lt;user-val&gt; ...}
`: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]
`: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 creator callsite location
`:elidable?` --- Should signal be subject to compile-time elision? (Default: true)
`:sample-rate` - ?rate ∈ℝ[0,1] for signal sampling (0.75 =&gt; allow 75% of signals, nil =&gt; allow all)
`: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])=&gt;modified-signal ...] signal middleware
`:trace?` ------ Should tracing be enabled for `:run` form?
&lt;kvs&gt; ---------- Other arb user-level ?kvs to incl. in signal. Typically NOT included in
handler output, so a great way to provide custom data/opts for use
(only) by custom middleware/handlers.
handler-specific data that can just be ignored by other handlers
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><div class="public anchor" id="var-level-aliases"><h3>level-aliases</h3><h4 class="lang"><a href="taoensso.telemere.html#var-level-aliases">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"></div><div class="doc"><pre class="plaintext"></pre></div></div><div class="public anchor" id="var-log.21"><h3>log!</h3><h4 class="type">macro</h4><h4 class="lang"><a href="taoensso.telemere.html#var-log.21">clj</a></h4><h4 class="lang current">cljs</h4><div class="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 &amp; kvs]} msg)</code></div><div class="doc"><pre class="plaintext">"Log" signal creator, emphasizing message + level.
API: [msg] [level-or-opts msg] =&gt; true iff signal was allowed.
Default kind: `:log`
Default level: `:info`
When filtering conditions are met [4], creates a Telemere signal [3] and
dispatches it to registered handlers for processing (e.g. writing to
console/file/queue/db, etc.).
Examples:
(log! "My msg") ; %&gt; {:kind :log, :level :info, :id ::my-id ...}
(log! :warn "My msg") ; %&gt; {... :level :warn ...}
(log!
{:let [x "x"] ; Available to `:data` and `:msg`
:data {:x x}}
["My msg:" x]) ; %&gt; {... :data {x "x"}, :msg_ "My msg: x" ...}
Tips:
- Test using `with-signal`: (with-signal (log! ...)).
- Supports the same options [2] as other signals [1].
- `log!` and `event!` are both good default/general-purpose signal creators.
- `log!` emphasizes messages, while `event!` emphasizes ids.
- `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-creators` - (`signal!`, `log!`, `event!`, ...)
[2] See `help:signal-options` - {:keys [kind level id data ...]}
[3] See `help:signal-content` - {:keys [kind level id data ...]}
[4] See `help:signal-flow` - (filters, handling, etc.)</pre></div></div><div class="public anchor" id="var-msg-skip"><h3>msg-skip</h3><h4 class="lang"><a href="taoensso.telemere.html#var-msg-skip">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"></div><div class="doc"><pre class="plaintext"></pre></div></div><div class="public anchor" id="var-msg-splice"><h3>msg-splice</h3><h4 class="lang"><a href="taoensso.telemere.html#var-msg-splice">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(msg-splice args)</code></div><div class="doc"><pre class="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 &lt;cond&gt; (msg-splice ["Username:" "Steve"])) &lt;...&gt;]}) or
(log! [(when &lt;cond&gt; (msg-splice ["Username:" "Steve"]))])
%&gt; {:msg_ "Username: Steve"}</pre></div></div><div class="public anchor" id="var-newline"><h3>newline</h3><h4 class="lang"><a href="taoensso.telemere.html#var-newline">clj</a></h4><h4 class="lang current">cljs</h4><h4 class="added">added in Encore v3.68.0 (2023-09-25)</h4><div class="usage"></div><div class="doc"><pre class="plaintext">Single system newline
</pre></div></div><div class="public anchor" id="var-rate-limiter"><h3>rate-limiter</h3><h4 class="lang"><a href="taoensso.telemere.html#var-rate-limiter">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(rate-limiter spec)</code><code>(rate-limiter opts spec)</code></div><div class="doc"><pre class="plaintext">Takes a spec of form
[ [&lt;n-max-reqs&gt; &lt;msecs-window&gt;] ...] or
{&lt;limit-id&gt; [&lt;n-max-reqs&gt; &lt;msecs-window&gt;]},
and returns a basic stateful (fn a-rate-limiter [req-id] [command req-id]).
Call the limiter fn with a request id (e.g. username) by which to count/limit.
Will return:
- nil when allowed (all limits pass for given req-id), or
- [&lt;worst-limit-id&gt; &lt;worst-backoff-msecs&gt; {&lt;limit-id&gt; &lt;backoff-msecs&gt;}]
when denied (any limits fail for given req-id).
Or call the limiter fn with an additional command argument:
`:rl/peek` &lt;req-id&gt; - Check limits w/o incrementing count.
`:rl/reset` &lt;req-id&gt; - Reset all limits for given req-id.
Example:
(defonce my-rate-limiter
(rate-limiter
{"1 per sec" [1 1000]
"10 per min" [10 60000]}))
(defn send-message! [username msg-content]
(if-let [fail (my-rate-limiter username)]
(throw (ex-info "Sorry, rate limited!" {:fail fail}))
&lt;send message&gt;))</pre></div></div><div class="public anchor" id="var-remove-handler.21"><h3>remove-handler!</h3><h4 class="lang"><a href="taoensso.telemere.html#var-remove-handler.21">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(remove-handler! handler-id)</code></div><div class="doc"><pre class="plaintext">Deregisters signal handler with given id, and returns
?{&lt;handler-id&gt; {:keys [dispatch-opts handler-fn]}} for all signal handlers
still registered.</pre></div></div><div class="public anchor" id="var-set-ctx.21"><h3>set-ctx!</h3><h4 class="type">macro</h4><h4 class="lang"><a href="taoensso.telemere.html#var-set-ctx.21">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(set-ctx! root-val)</code></div><div class="doc"><pre class="plaintext">Set `*ctx*` var's root (base) value. See `*ctx*` for details.
</pre></div></div><div class="public anchor" id="var-set-id-filter.21"><h3>set-id-filter!</h3><h4 class="lang"><a href="taoensso.telemere.html#var-set-id-filter.21">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(set-id-filter! id-filter)</code></div><div class="doc"><pre class="plaintext">Sets signal call id filter based on given `id-filter` spec.
`id-filter` may be:
- A str/kw/sym, in which "*"s act as wildcards.
- A regex pattern of id/s to allow.
- A vector or set of regex patterns or strs/kws/syms.
- {:allow &lt;spec&gt; :deny &lt;spec&gt;} with specs as above.
If present, `:allow` spec MUST match, AND
If present, `:deny` spec MUST NOT match.</pre></div></div><div class="public anchor" id="var-set-kind-filter.21"><h3>set-kind-filter!</h3><h4 class="lang"><a href="taoensso.telemere.html#var-set-kind-filter.21">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(set-kind-filter! kind-filter)</code></div><div class="doc"><pre class="plaintext">Sets signal call kind filter based on given `kind-filter` spec.
`kind-filter` may be:
- A str/kw/sym, in which "*"s act as wildcards.
- A regex pattern of kind/s to allow.
- A vector or set of regex patterns or strs/kws/syms.
- {:allow &lt;spec&gt; :deny &lt;spec&gt;} with specs as above.
If present, `:allow` spec MUST match, AND
If present, `:deny` spec MUST NOT match.</pre></div></div><div class="public anchor" id="var-set-middleware.21"><h3>set-middleware!</h3><h4 class="type">macro</h4><h4 class="lang"><a href="taoensso.telemere.html#var-set-middleware.21">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(set-middleware! root-val)</code></div><div class="doc"><pre class="plaintext">Set `*middleware*` var's root (base) value. See `*middleware*` for details.
</pre></div></div><div class="public anchor" id="var-set-min-level.21"><h3>set-min-level!</h3><h4 class="lang"><a href="taoensso.telemere.html#var-set-min-level.21">clj</a></h4><h4 class="lang current">cljs</h4><div class="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><div class="doc"><pre class="plaintext">Sets minimum signal call level based on given `min-level` spec.
`min-level` may be:
- `nil` (=&gt; no minimum level).
- A level keyword (see `level-aliases` var for details).
- An integer.
If `ns-filter` is provided, then the given minimum level
will apply only for the namespace/s 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.
Examples:
(set-min-level! nil) ; Disable minimum level
(set-min-level! :info) ; Set `:info` as minimum level
(set-min-level! 100) ; Set 100 as minimum level
;; Set `:debug` as minimum level for current namespace
;; (nil `kind` =&gt; apply to all kinds)
(set-min-level! nil *ns* :debug)</pre></div></div><div class="public anchor" id="var-set-ns-filter.21"><h3>set-ns-filter!</h3><h4 class="lang"><a href="taoensso.telemere.html#var-set-ns-filter.21">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(set-ns-filter! ns-filter)</code></div><div class="doc"><pre class="plaintext">Sets signal call namespace filter based on given `ns-filter` spec.
`ns-filter` may be:
- A namespace.
- A str/kw/sym, in which "*"s act as wildcards.
- A regex pattern of namespace/s to allow.
- A vector or set of regex patterns or strs/kws/syms.
- {:allow &lt;spec&gt; :deny &lt;spec&gt;} with specs as above.
If present, `:allow` spec MUST match, AND
If present, `:deny` spec MUST NOT match.</pre></div></div><div class="public anchor" id="var-set-var-root.21"><h3>set-var-root!</h3><h4 class="type">macro</h4><h4 class="lang"><a href="taoensso.telemere.html#var-set-var-root.21">clj</a></h4><h4 class="lang current">cljs</h4><h4 class="added">added in Encore v3.75.0 (2024-01-29)</h4><div class="usage"><code>(set-var-root! var-sym root-val)</code></div><div class="doc"><pre class="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><div class="public anchor" id="var-shut-down-handlers.21"><h3>shut-down-handlers!</h3><h4 class="lang"><a href="taoensso.telemere.html#var-shut-down-handlers.21">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(shut-down-handlers!)</code></div><div class="doc"><pre class="plaintext">Shuts down all registered signal handlers in parallel, and returns
?{&lt;handler-id&gt; {:keys [okay error]}}.
Future calls to handlers will no-op.
Clj only: `shut-down-handlers!` is called automatically on JVM shutdown.</pre></div></div><div class="public anchor" id="var-signal.21"><h3>signal!</h3><h4 class="type">macro</h4><h4 class="lang"><a href="taoensso.telemere.html#var-signal.21">clj</a></h4><h4 class="lang current">cljs</h4><div class="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 &amp; kvs]})</code></div><div class="doc"><pre class="plaintext">Low-level generic signal creator.
API: [opts] =&gt; depends on options [2]
Default kind: none (optional)
Default level: none (must be provided)
When filtering conditions are met [4], creates a Telemere signal [3] 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 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 higher-level signal creators optimized for ease-of-use in
common cases [1].
Tips:
- Test using `with-signal`: (with-signal (signal! ...)).
- Supports the same options [2] as other signals [1].
-------------------------------------------------------------------
[1] See `help:signal-creators` - (`signal!`, `log!`, `event!`, ...)
[2] See `help:signal-options` - {:keys [kind level id data ...]}
[3] See `help:signal-content` - {:keys [kind level id data ...]}
[4] See `help:signal-flow` - (filters, handling, etc.)</pre></div></div><div class="public anchor" id="var-spy.21"><h3>spy!</h3><h4 class="type">macro</h4><h4 class="lang"><a href="taoensso.telemere.html#var-spy.21">clj</a></h4><h4 class="lang current">cljs</h4><div class="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 &amp; kvs]} form)</code></div><div class="doc"><pre class="plaintext">"Spy" signal creator, emphasizing form + level.
API: [form] [level-or-opts form] =&gt; form's result (value/throw) (unconditional)
Default kind: `:spy`
Default level: `:info`
When filtering conditions are met [4], creates a Telemere signal [3] and
dispatches it to registered handlers for processing (e.g. writing to
console/file/queue/db, etc.).
Examples:
(spy! (+ 1 2)) ; %&gt; {:kind :trace, :level :info, :run-form '(+ 1 2),
; :run-val 3, :run-nsecs &lt;int&gt;, :parent {:keys [id uid]}
; :msg "(+ 1 2) =&gt; 3" ...}
(spy! ::my-id (+ 1 2)) ; %&gt; {... :id ::my-id ...}
(spy!
{:let [x "x"] ; Available to `:data` and `:msg`
:data {:x x}}
(+ 1 2)) ; %&gt; {... :data {x "x"}, :msg_ "My msg: x" ...}
Tips:
- Test using `with-signal`: (with-signal (spy! ...)).
- Supports the same options [2] as other signals [1].
- Identical to `trace!`, but emphasizes form + level rather than form + id.
- Useful for debugging/monitoring forms, and tracing (nested) execution flow.
- 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-&gt;error!`:
(catch-&gt;error! ::error-id (spy! ...)).
-------------------------------------------------------------------
[1] See `help:signal-creators` - (`signal!`, `log!`, `event!`, ...)
[2] See `help:signal-options` - {:keys [kind level id data ...]}
[3] See `help:signal-content` - {:keys [kind level id data ...]}
[4] See `help:signal-flow` - (filters, handling, etc.)</pre></div></div><div class="public anchor" id="var-trace.21"><h3>trace!</h3><h4 class="type">macro</h4><h4 class="lang"><a href="taoensso.telemere.html#var-trace.21">clj</a></h4><h4 class="lang current">cljs</h4><div class="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 &amp; kvs]} form)</code></div><div class="doc"><pre class="plaintext">"Trace" signal creator, emphasizing form + id.
API: [form] [id-or-opts form] =&gt; form's result (value/throw) (unconditional)
Default kind: `:trace`
Default level: `:info` (intentionally NOT `:trace`!)
When filtering conditions are met [4], creates a Telemere signal [3] and
dispatches it to registered handlers for processing (e.g. writing to
console/file/queue/db, etc.).
Examples:
(trace! (+ 1 2)) ; %&gt; {:kind :trace, :level :info, :run-form '(+ 1 2),
; :run-val 3, :run-nsecs &lt;int&gt;, :parent {:keys [id uid]} ...
; :msg "(+ 1 2) =&gt; 3" ...}
(trace! ::my-id (+ 1 2)) ; %&gt; {... :id ::my-id ...}
(trace!
{:let [x "x"] ; Available to `:data` and `:msg`
:data {:x x}}
(+ 1 2)) ; %&gt; {... :data {x "x"}, :msg_ "My msg: x" ...}
Tips:
- Test using `with-signal`: (with-signal (trace! ...)).
- Supports the same options [2] as other signals [1].
- Identical to `spy!`, but emphasizes form + id rather than form + level.
- Useful for debugging/monitoring forms, and tracing (nested) execution flow.
- 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-&gt;error!`:
(catch-&gt;error! ::error-id (trace! ...)).
- 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-creators` - (`signal!`, `log!`, `event!`, ...)
[2] See `help:signal-options` - {:keys [kind level id data ...]}
[3] See `help:signal-content` - {:keys [kind level id data ...]}
[4] See `help:signal-flow` - (filters, handling, etc.)</pre></div></div><div class="public anchor" id="var-uncaught-.3Eerror.21"><h3>uncaught-&gt;error!</h3><h4 class="type">macro</h4><h4 class="lang"><a href="taoensso.telemere.html#var-uncaught-.3Eerror.21">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(uncaught-&gt;error!)</code><code>(uncaught-&gt;error! id)</code><code>(uncaught-&gt;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 &amp; kvs]})</code></div><div class="doc"><pre class="plaintext">Uses `uncaught-&gt;handler!` so that `error!` will be called for
uncaught JVM errors.
See `uncaught-&gt;handler!` and `error!` for details.</pre></div></div><div class="public anchor" id="var-update-var-root.21"><h3>update-var-root!</h3><h4 class="type">macro</h4><h4 class="lang"><a href="taoensso.telemere.html#var-update-var-root.21">clj</a></h4><h4 class="lang current">cljs</h4><h4 class="added">added in Encore v3.68.0 (2023-09-25)</h4><div class="usage"><code>(update-var-root! var-sym update-fn)</code></div><div class="doc"><pre class="plaintext">Updates root binding (value) of the var identified by given symbol, and returns
the new value:
(update-var-root! my-var (fn [old-root-val] &lt;new-root-val&gt;)) =&gt; &lt;new-root-val&gt;
Similar to `alter-var-root` but cross-platform and takes a symbol rather than a var.
See also `set-var-root!`.</pre></div></div><div class="public anchor" id="var-with-ctx"><h3>with-ctx</h3><h4 class="type">macro</h4><h4 class="lang"><a href="taoensso.telemere.html#var-with-ctx">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(with-ctx init-val form)</code></div><div class="doc"><pre class="plaintext">Evaluates given form with given `*ctx*` value. See `*ctx*` for details.
</pre></div></div><div class="public anchor" id="var-with-ctx.2B"><h3>with-ctx+</h3><h4 class="type">macro</h4><h4 class="lang"><a href="taoensso.telemere.html#var-with-ctx.2B">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(with-ctx+ update-map-or-fn form)</code></div><div class="doc"><pre class="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><div class="public anchor" id="var-with-err-.3Etelemere"><h3>with-err-&gt;telemere</h3><h4 class="type">macro</h4><h4 class="lang"><a href="taoensso.telemere.html#var-with-err-.3Etelemere">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(with-err-&gt;telemere form)</code><code>(with-err-&gt;telemere opts form)</code></div><div class="doc"><pre class="plaintext">Executes form with `*err*` bound to flush to Telemere signals with given opts.
</pre></div></div><div class="public anchor" id="var-with-handler"><h3>with-handler</h3><h4 class="type">macro</h4><h4 class="lang"><a href="taoensso.telemere.html#var-with-handler">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(with-handler handler-id handler-fn dispatch-opts form)</code></div><div class="doc"><pre class="plaintext">Executes form with ONLY the given handler-fn registered.
Useful for tests/debugging. See also `with-handler+`.</pre></div></div><div class="public anchor" id="var-with-handler.2B"><h3>with-handler+</h3><h4 class="type">macro</h4><h4 class="lang"><a href="taoensso.telemere.html#var-with-handler.2B">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(with-handler+ handler-id handler-fn dispatch-opts form)</code></div><div class="doc"><pre class="plaintext">Executes form with the given handler-fn registered.
Useful for tests/debugging. See also `with-handler`.</pre></div></div><div class="public anchor" id="var-with-id-filter"><h3>with-id-filter</h3><h4 class="type">macro</h4><h4 class="lang"><a href="taoensso.telemere.html#var-with-id-filter">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(with-id-filter id-filter form)</code></div><div class="doc"><pre class="plaintext">Executes form with given signal call id filter in effect.
See `set-id-filter!` for details.</pre></div></div><div class="public anchor" id="var-with-kind-filter"><h3>with-kind-filter</h3><h4 class="type">macro</h4><h4 class="lang"><a href="taoensso.telemere.html#var-with-kind-filter">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(with-kind-filter kind-filter form)</code></div><div class="doc"><pre class="plaintext">Executes form with given signal call kind filter in effect.
See `set-kind-filter!` for details.</pre></div></div><div class="public anchor" id="var-with-middleware"><h3>with-middleware</h3><h4 class="type">macro</h4><h4 class="lang"><a href="taoensso.telemere.html#var-with-middleware">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(with-middleware init-val form)</code></div><div class="doc"><pre class="plaintext">Evaluates given form with given `*middleware*` value.
See `*middleware*` for details.</pre></div></div><div class="public anchor" id="var-with-min-level"><h3>with-min-level</h3><h4 class="type">macro</h4><h4 class="lang"><a href="taoensso.telemere.html#var-with-min-level">clj</a></h4><h4 class="lang current">cljs</h4><div class="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><div class="doc"><pre class="plaintext">Executes form with given minimum signal call level in effect.
See `set-min-level!` for details.</pre></div></div><div class="public anchor" id="var-with-ns-filter"><h3>with-ns-filter</h3><h4 class="type">macro</h4><h4 class="lang"><a href="taoensso.telemere.html#var-with-ns-filter">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(with-ns-filter ns-filter form)</code></div><div class="doc"><pre class="plaintext">Executes form with given signal call namespace filter in effect.
See `set-ns-filter!` for details.</pre></div></div><div class="public anchor" id="var-with-out-.3Etelemere"><h3>with-out-&gt;telemere</h3><h4 class="type">macro</h4><h4 class="lang"><a href="taoensso.telemere.html#var-with-out-.3Etelemere">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(with-out-&gt;telemere form)</code><code>(with-out-&gt;telemere opts form)</code></div><div class="doc"><pre class="plaintext">Executes form with `*out*` bound to flush to Telemere signals with given opts.
</pre></div></div><div class="public anchor" id="var-with-signal"><h3>with-signal</h3><h4 class="type">macro</h4><h4 class="lang"><a href="taoensso.telemere.html#var-with-signal">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(with-signal form)</code><code>(with-signal trap-signals? form)</code><code>(with-signal raw-msg? trap-signals? form)</code></div><div class="doc"><pre class="plaintext">Experimental.
Executes given form, trapping errors. Returns the LAST signal created by form.
Useful for tests/debugging.
Options:
`trap-signals?` (default: false)
Should ALL signals created by form be trapped to prevent normal dispatch
to registered handlers?
`raw-msg?` (default: false)
Should delayed `:msg_` in returned signal be retained as-is?
Delay is otherwise replaced by realized string.
See also `with-signals`.</pre></div></div><div class="public anchor" id="var-with-signals"><h3>with-signals</h3><h4 class="type">macro</h4><h4 class="lang"><a href="taoensso.telemere.html#var-with-signals">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(with-signals form)</code><code>(with-signals trap-signals? form)</code><code>(with-signals raw-msgs? trap-signals? form)</code></div><div class="doc"><pre class="plaintext">Experimental.
Like `with-signal` but returns [[&lt;form-value&gt; &lt;form-error&gt;] [&lt;signal1&gt; ...]].
Useful for tests/debugging.</pre></div></div><div class="public anchor" id="var-with-streams-.3Etelemere"><h3>with-streams-&gt;telemere</h3><h4 class="type">macro</h4><h4 class="lang"><a href="taoensso.telemere.html#var-with-streams-.3Etelemere">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(with-streams-&gt;telemere form)</code><code>(with-streams-&gt;telemere {:keys [out err], :or {out default-out-opts, err default-err-opts}} form)</code></div><div class="doc"><pre class="plaintext">Executes form with `*out*` and/or `*err*` bound to flush to Telemere signals
with given opts.</pre></div></div><div class="public anchor" id="var-without-filters"><h3>without-filters</h3><h4 class="type">macro</h4><h4 class="lang"><a href="taoensso.telemere.html#var-without-filters">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(without-filters form)</code></div><div class="doc"><pre class="plaintext">Executes form without any runtime filters.
</pre></div></div></div></body></html>
Reference in a new issue View git blame Copy permalink