luciano/telemere
1
0
Fork 0
mirror of https://github.com/taoensso/telemere.git synced 2026-01-30 17:50:34 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
telemere/taoensso.telemere.html

325 lines
42 KiB
HTML
Raw Normal View History

v1.0.0-SNAPSHOT (2024-03-06)
2024-03-05 10:18:56 +00:00
<!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-SNAPSHOT</span></span></a></h1><div id="langs"><div class="lang current">clj</div><div class="lang"><a href="index.cljs.html">cljs</a></div></div></div><div class="sidebar primary"><h3 class="no-link"><span class="inner">Namespaces</span></h3><ul><li class="depth-1 current"><a href="taoensso.telemere.html"><div class="inner"><span>taoensso.telemere</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.html#var-*ctx*"><div class="inner"><span>*ctx*</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-*middleware*"><div class="inner"><span>*middleware*</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-add-handler.21"><div class="inner"><span>add-handler!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-catch-.3Eerror.21"><div class="inner"><span>catch-&gt;error!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-chance"><div class="inner"><span>chance</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-check-interop"><div class="inner"><span>check-interop</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-default-ctx"><div class="inner"><span>default-ctx</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-error.21"><div class="inner"><span>error!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-event.21"><div class="inner"><span>event!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-filtering-help"><div class="inner"><span>filtering-help</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-format-error"><div class="inner"><span>format-error</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-format-instant"><div class="inner"><span>format-instant</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-get-env"><div class="inner"><span>get-env</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-get-filters"><div class="inner"><span>get-filters</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-get-handlers"><div class="inner"><span>get-handlers</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-get-min-level"><div class="inner"><span>get-min-level</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-handlers-help"><div class="inner"><span>handlers-help</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-hostname"><div class="inner"><span>hostname</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-level-aliases"><div class="inner"><span>level-aliases</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-log.21"><div class="inner"><span>log!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-msg-skip"><div class="inner"><span>msg-skip</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-msg-splice"><div class="inner"><span>msg-splice</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-newline"><div class="inner"><span>newline</span></div></a></li><li class="depth-1"><a href=
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 current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-*ctx*">cljs</a></h4><div class="usage"></div><div class="doc"><pre class="plaintext">Dynamic context: arbitrary app-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 current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-*middleware*">cljs</a></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 current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-add-handler.21">cljs</a></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.
`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
`ns-filter` - Namespace filter as in `set-ns-filter!`
`kind-filter` - Kind filter as in `set-kind-filter!` (when relevant)
`id-filter` - Id filter as in `set-id-filter!` (when relevant)
`min-level` - Minimum level as in `set-min-level!`
`filter-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 (namespace, kind, id, level, filter-fn)
c. Rate limiting
d. Middleware
2. Per handler (n&gt;=0):
a. Sampling
b. Filtering (namespace, kind, id, level, filter-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 current">clj</h4><div class="usage"><code>(catch-&gt;error! form)</code><code>(catch-&gt;error! level form)</code><code>(catch-&gt;error! {:as opts, :keys [rethrow? catch-val elidable? location instant uid middleware sample-rate ns kind id level filter when rate-limit ctx parent trace? let data msg error &amp; user-opts]} form)</code></div><div class="doc"><pre class="plaintext">TODO Docstring [form] [id-or-opts form] =&gt; run value or ?catch-val
</pre></div></div><div class="public anchor" id="var-chance"><h3>chance</h3><h4 class="lang current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-chance">cljs</a></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-check-interop"><h3>check-interop</h3><h4 class="lang current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-check-interop">cljs</a></h4><div class="usage"><code>(check-interop)</code></div><div class="doc"><pre class="plaintext">Experimental, subject to change.
Runs Telemere's registered interop checks and returns
{&lt;interop-id&gt; {:keys [sending-&gt;telemere? telemere-receiving? ...]}}.
Useful for tests/debugging.</pre></div></div><div class="public anchor" id="var-default-ctx"><h3>default-ctx</h3><h4 class="lang current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-default-ctx">cljs</a></h4><div class="usage"></div><div class="doc"><pre class="plaintext">Advanced feature. Default root (base) value of `*ctx*` var, 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 current">clj</h4><div class="usage"><code>(error! error)</code><code>(error! id error)</code><code>(error! {:as opts, :keys [elidable? location instant uid middleware sample-rate ns kind id level filter when rate-limit ctx parent trace? let data msg error &amp; user-opts]} error)</code></div><div class="doc"><pre class="plaintext">TODO Docstring [error] [id-or-opts error] =&gt; error
(throw (error! &lt;error&gt;)) example.</pre></div></div><div class="public anchor" id="var-event.21"><h3>event!</h3><h4 class="type">macro</h4><h4 class="lang current">clj</h4><div class="usage"><code>(event! id)</code><code>(event! level id)</code><code>(event! {:as opts, :keys [elidable? location instant uid middleware sample-rate ns kind id level filter when rate-limit ctx parent trace? let data msg error &amp; user-opts]} id)</code></div><div class="doc"><pre class="plaintext">TODO Docstring [id] [level-or-opts id] =&gt; allowed?
</pre></div></div><div class="public anchor" id="var-filtering-help"><h3>filtering-help</h3><h4 class="lang current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-filtering-help">cljs</a></h4><div class="usage"></div><div class="doc"><pre class="plaintext">Your filter config determines which signal calls will be enabled.
Filtering can occur at compile-time (=&gt; elision), or runtime.
Both compile-time and runtime config can be specified via:
1. System values (JVM properties, environment variables, or
classpath resources). See library docs for details.
2. The filter API consting of the following:
`set-ns-filter!`, `with-ns-filter` - for filtering calls by namespace
`set-minimum-level!`, `with-minimum-level!` - for filtering calls by signal level
`set-id-filter!`, `with-id-filter` - for filtering calls by signal id (when relevant)
`set-kind-filter!`, `with-kind-filter` - for filtering calls by signal kind (when relevant)
See the relevant docstrings for details.
Additional filtering can also be applied on a per-handler basis, see
`add-handler!` for details.
See also:
`get-filters` - to see current filter config
`get-min-level` - to see current minimum level
`without-filters` - to disable all runtime filtering
If anything is unclear, please ping me (@ptaoussanis) so that I can
improve these docs!</pre></div></div><div class="public anchor" id="var-format-error"><h3>format-error</h3><h4 class="lang current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-format-error">cljs</a></h4><div class="usage"><code>(format-error error)</code><code>(format-error {:keys [use-fonts? sort-stacktrace-by fonts], :or {use-fonts? :auto, sort-stacktrace-by :chronological, fonts clj-commons.format.exceptions/default-fonts}} error)</code></div><div class="doc"><pre class="plaintext">TODO Docstring
</pre></div></div><div class="public anchor" id="var-format-instant"><h3>format-instant</h3><h4 class="lang current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-format-instant">cljs</a></h4><div class="usage"><code>(format-instant instant)</code><code>(format-instant {:keys [formatter], :or {formatter java.time.format.DateTimeFormatter/ISO_INSTANT}} instant)</code></div><div class="doc"><pre class="plaintext">TODO Docstring
</pre></div></div><div class="public anchor" id="var-get-env"><h3>get-env</h3><h4 class="type">macro</h4><h4 class="lang current">clj</h4><h4 class="added">added in Encore v3.75.0 (2024-01-29)</h4><div class="usage"><code>(get-env {:keys [as default return]} spec)</code><code>(get-env {:keys [as default return spec], :or {as :str, return :value}})</code></div><div class="doc"><pre class="plaintext">Cross-platform util for embedding flexible environmental config during
macro expansion. Used by other Taoensso libraries.
Given a const kw/string id or vector of desc-priority alternative ids,
parse and return the first of the following that exists:
- JVM property value for id ("prop")
- Environment variable value for id ("env")
- Classpath resource content for id ("res")
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)].
(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 (content type)
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 (content type)
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 (content type)
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 (content type)
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 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><div class="public anchor" id="var-get-filters"><h3>get-filters</h3><h4 class="lang current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-get-filters">cljs</a></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 current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-get-handlers">cljs</a></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 current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-get-min-level">cljs</a></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-handlers-help"><h3>handlers-help</h3><h4 class="lang current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-handlers-help">cljs</a></h4><div class="usage"></div><div class="doc"><pre class="plaintext">The handler API consists of the following:
`get-handlers` - Returns info on currently registered handlers
`add-handler!` - Used to register handlers
`remove-handler!` - Used to unregister handlers
See the relevant docstrings for details.
If anything is unclear, please ping me (@ptaoussanis) so that I can
improve these docs!</pre></div></div><div class="public anchor" id="var-hostname"><h3>hostname</h3><h4 class="lang current">clj</h4><div class="usage"><code>(hostname)</code><code>(hostname timeout-msecs timeout-val)</code></div><div class="doc"><pre class="plaintext">Returns local cached hostname string, or `timeout-val` (default "UnknownHost").
</pre></div></div><div class="public anchor" id="var-level-aliases"><h3>level-aliases</h3><h4 class="lang current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-level-aliases">cljs</a></h4><div class="usage"></div><div class="doc"><pre class="plaintext">Map of {&lt;level-keyword&gt; &lt;level-integer&gt;} aliases.
</pre></div></div><div class="public anchor" id="var-log.21"><h3>log!</h3><h4 class="type">macro</h4><h4 class="lang current">clj</h4><div class="usage"><code>(log! msg)</code><code>(log! level msg)</code><code>(log! {:as opts, :keys [elidable? location instant uid middleware sample-rate ns kind id level filter when rate-limit ctx parent trace? let data msg error &amp; user-opts]} msg)</code></div><div class="doc"><pre class="plaintext">TODO Docstring [msg] [level-or-opts msg] =&gt; allowed?
</pre></div></div><div class="public anchor" id="var-msg-skip"><h3>msg-skip</h3><h4 class="lang current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-msg-skip">cljs</a></h4><div class="usage"><code>(msg-skip)</code></div><div class="doc"><pre class="plaintext">TODO Docstring
</pre></div></div><div class="public anchor" id="var-msg-splice"><h3>msg-splice</h3><h4 class="lang current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-msg-splice">cljs</a></h4><div class="usage"><code>(msg-splice args)</code></div><div class="doc"><pre class="plaintext">TODO Docstring
</pre></div></div><div class="public anchor" id="var-newline"><h3>newline</h3><h4 class="lang current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-newline">cljs</a></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 current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-rate-limiter">cljs</a></h4><div class="usage"><code>(rate-limiter spec)</code><code>(rate-limiter opts spec)</code></div><div class="doc"><pre class="plaintext">Takes a map spec of form {&lt;limit-id&gt; [&lt;n-max-reqs&gt; &lt;msecs-window&gt;]},
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.
Will return:
- nil when all limits pass for that id, or
- [&lt;worst-limit-id&gt; &lt;worst-backoff-msecs&gt; {&lt;limit-id&gt; &lt;backoff-msecs&gt;}]
when any limits fail for that id.
Or call 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 current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-remove-handler.21">cljs</a></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 current">clj</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 current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-set-id-filter.21">cljs</a></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 regex pattern of id/s to allow.
- A str/kw/sym, in which "*"s act as wildcards.
- A vector or set of regex patterns or strs/kws/syms.
- {:allow &lt;spec&gt; :deny &lt;spec&gt;} with specs as above.</pre></div></div><div class="public anchor" id="var-set-kind-filter.21"><h3>set-kind-filter!</h3><h4 class="lang current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-set-kind-filter.21">cljs</a></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 regex pattern of kind/s to allow.
- A str/kw/sym, in which "*"s act as wildcards.
- A vector or set of regex patterns or strs/kws/syms.
- {:allow &lt;spec&gt; :deny &lt;spec&gt;} with specs as above.</pre></div></div><div class="public anchor" id="var-set-middleware.21"><h3>set-middleware!</h3><h4 class="type">macro</h4><h4 class="lang current">clj</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 current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-set-min-level.21">cljs</a></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:
- An integer.
- 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><div class="public anchor" id="var-set-ns-filter.21"><h3>set-ns-filter!</h3><h4 class="lang current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-set-ns-filter.21">cljs</a></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 regex pattern of namespace/s to allow.
- A str/kw/sym, in which "*"s act as wildcards.
- A vector or set of regex patterns or strs/kws/syms.
- {:allow &lt;spec&gt; :deny &lt;spec&gt;} with specs as above.</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 current">clj</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-signal.21"><h3>signal!</h3><h4 class="type">macro</h4><h4 class="lang current">clj</h4><div class="usage"><code>(signal! {:as opts, :keys [elidable? location instant uid middleware sample-rate ns kind id level filter when rate-limit ctx parent trace? let data msg error run &amp; user-opts]})</code></div><div class="doc"><pre class="plaintext">Expands to a low-level signal call.
TODO Docstring
- How low-level is this? Should location, ctx, etc. be in public arglists?
- Describe
- Reference diagram link [1]
- Mention ability to delay-wrap :data
- Mention combo `:sample-rate` stuff (call * handler)
- If :run =&gt; returns body run-result (re-throwing)
Otherwise returns true iff call allowed
[1] Ref. &lt;<a href="https://github.com/taoensso/telemere/blob/master/signal-flow.svg">https://github.com/taoensso/telemere/blob/master/signal-flow.svg</a>&gt;</pre></div></div><div class="public anchor" id="var-spy.21"><h3>spy!</h3><h4 class="type">macro</h4><h4 class="lang current">clj</h4><div class="usage"><code>(spy! form)</code><code>(spy! id form)</code><code>(spy! {:as opts, :keys [elidable? location instant uid middleware sample-rate ns kind id level filter when rate-limit ctx parent trace? let data msg error run &amp; user-opts]} form)</code></div><div class="doc"><pre class="plaintext">TODO Docstring [form] [level-or-opts form] =&gt; run result (value or throw)
</pre></div></div><div class="public anchor" id="var-streams-.3Ereset.21"><h3>streams-&gt;reset!</h3><h4 class="lang current">clj</h4><div class="usage"><code>(streams-&gt;reset!)</code></div><div class="doc"><pre class="plaintext">Experimental, subject to change without notice!
Resets `System/out` and `System/err` to their original value (prior to any
`streams-&gt;telemere!` call).</pre></div></div><div class="public anchor" id="var-streams-.3Etelemere.21"><h3>streams-&gt;telemere!</h3><h4 class="lang current">clj</h4><div class="usage"><code>(streams-&gt;telemere!)</code><code>(streams-&gt;telemere! {:keys [out err], :or {out default-out-opts, err default-err-opts}})</code></div><div class="doc"><pre class="plaintext">Experimental, subject to change without notice!
When given `out`, sets JVM's `System/out` to flush to Telemere signals with those opts.
When given `err`, sets JVM's `System/err` to flush to Telemere signals with those opts.
Note that setting `System/out` won't necessarily affect Clojure's `*out*`,
and setting `System/err` won't necessarily affect Clojure's `*err*`.
See also:
`with-out-&gt;telemere`,
`with-err-&gt;telemere`,
`with-streams-&gt;telemere`.</pre></div></div><div class="public anchor" id="var-thread-id"><h3>thread-id</h3><h4 class="lang current">clj</h4><div class="usage"><code>(thread-id)</code></div><div class="doc"><pre class="plaintext"></pre></div></div><div class="public anchor" id="var-thread-name"><h3>thread-name</h3><h4 class="lang current">clj</h4><div class="usage"><code>(thread-name)</code></div><div class="doc"><pre class="plaintext"></pre></div></div><div class="public anchor" id="var-tools-logging-.3Etelemere.21"><h3>tools-logging-&gt;telemere!</h3><h4 class="lang current">clj</h4><div class="usage"><code>(tools-logging-&gt;telemere!)</code></div><div class="doc"><pre class="plaintext">Configures `clojure.tools.logging` to use Telemere as its logging implementation.
</pre></div></div><div class="public anchor" id="var-trace.21"><h3>trace!</h3><h4 class="type">macro</h4><h4 class="lang current">clj</h4><div class="usage"><code>(trace! form)</code><code>(trace! id form)</code><code>(trace! {:as opts, :keys [elidable? location instant uid middleware sample-rate ns kind id level filter when rate-limit ctx parent trace? let data msg error run &amp; user-opts]} form)</code></div><div class="doc"><pre class="plaintext">TODO Docstring [form] [id-or-opts form] =&gt; run result (value or throw)
</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 current">clj</h4><div class="usage"><code>(uncaught-&gt;error!)</code><code>(uncaught-&gt;error! id)</code><code>(uncaught-&gt;error! {:as opts, :keys [elidable? location instant uid middleware sample-rate ns kind id level filter when rate-limit ctx parent trace? let data msg error &amp; user-opts]})</code></div><div class="doc"><pre class="plaintext">TODO Docstring
See also `uncaught-&gt;handler!`.</pre></div></div><div class="public anchor" id="var-uncaught-.3Ehandler.21"><h3>uncaught-&gt;handler!</h3><h4 class="lang current">clj</h4><div class="usage"><code>(uncaught-&gt;handler! handler)</code></div><div class="doc"><pre class="plaintext">Sets JVM's global `DefaultUncaughtExceptionHandler` to given
(fn handler [`&lt;java.lang.Thread&gt;` `&lt;java.lang.Throwable&gt;`]).
See also `uncaught-&gt;error!`.</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 current">clj</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 current">clj</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 current">clj</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 current">clj</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 current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-with-handler">cljs</a></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 current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-with-handler.2B">cljs</a></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 current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-with-id-filter">cljs</a></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 current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-with-kind-filter">cljs</a></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 current">clj</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 current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-with-min-level">cljs</a></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 current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-with-ns-filter">cljs</a></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 current">clj</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 current">clj</h4><div class="usage"><code>(with-signal form)</code><code>(with-signal {:keys [return trap-errors? stop-propagation? force-msg?]} form)</code></div><div class="doc"><pre class="plaintext">Util for tests/debugging.
Executes given form and returns [&lt;form-result&gt; &lt;last-signal-dispatched-by-form&gt;].
If `trap-errors?` is true, form result will be wrapped by {:keys [okay error]}.</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 current">clj</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 current">clj</h4><h4 class="lang"><a href="taoensso.telemere.cljs.html#var-without-filters">cljs</a></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 Copy permalink