telemere/taoensso.telemere.cljs.html
2024-03-14 10:37:32 +01:00

192 lines
No EOL
23 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-alpha1</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 current"><a href="taoensso.telemere.cljs.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.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-chance"><div class="inner"><span>chance</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-check-interop"><div class="inner"><span>check-interop</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-format-error"><div class="inner"><span>format-error</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.cljs.html#var-format-instant"><div class="inner"><span>format-instant</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-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-level-aliases"><div class="inner"><span>level-aliases</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-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-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-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-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-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.
`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!`
`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-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"></div><div class="doc"><pre class="plaintext"></pre></div></div><div class="public anchor" id="var-check-interop"><h3>check-interop</h3><h4 class="lang"><a href="taoensso.telemere.html#var-check-interop">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-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">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-format-error"><h3>format-error</h3><h4 class="lang"><a href="taoensso.telemere.html#var-format-error">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(format-error error)</code><code>(format-error _ 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"><a href="taoensso.telemere.html#var-format-instant">clj</a></h4><h4 class="lang current">cljs</h4><div class="usage"><code>(format-instant instant)</code><code>(format-instant {:keys [format]} instant)</code></div><div class="doc"><pre class="plaintext">TODO Docstring
</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-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 (=&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-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">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-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-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"></div><div class="doc"><pre class="plaintext"></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><div class="usage"></div><div class="doc"><pre class="plaintext"></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"></div><div class="doc"><pre class="plaintext"></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-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 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"><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 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-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:
- 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"><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 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-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-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-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>