luciano/telemere
1
0
Fork 0
mirror of https://github.com/taoensso/telemere.git synced 2026-01-20 13:59:02 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
telemere/taoensso.telemere.html
Peter Taoussanis 57eafd497c v1.0.0-SNAPSHOT (2024-03-06)
2024-03-06 13:23:24 +01:00

325 lines
No EOL
42 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-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="taoensso.telemere.html#var-rate-limiter"><div class="inner"><span>rate-limiter</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-remove-handler.21"><div class="inner"><span>remove-handler!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-set-ctx.21"><div class="inner"><span>set-ctx!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.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.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.html#var-set-middleware.21"><div class="inner"><span>set-middleware!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.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.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.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.html#var-signal.21"><div class="inner"><span>signal!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-spy.21"><div class="inner"><span>spy!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-streams-.3Ereset.21"><div class="inner"><span>streams-&gt;reset!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-streams-.3Etelemere.21"><div class="inner"><span>streams-&gt;telemere!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-thread-id"><div class="inner"><span>thread-id</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-thread-name"><div class="inner"><span>thread-name</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-tools-logging-.3Etelemere.21"><div class="inner"><span>tools-logging-&gt;telemere!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-trace.21"><div class="inner"><span>trace!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-uncaught-.3Eerror.21"><div class="inner"><span>uncaught-&gt;error!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-uncaught-.3Ehandler.21"><div class="inner"><span>uncaught-&gt;handler!</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.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.html#var-with-ctx"><div class="inner"><span>with-ctx</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-with-ctx.2B"><div class="inner"><span>with-ctx+</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.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.html#var-with-handler"><div class="inner"><span>with-handler</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-with-handler.2B"><div class="inner"><span>with-handler+</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-with-id-filter"><div class="inner"><span>with-id-filter</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-with-kind-filter"><div class="inner"><span>with-kind-filter</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-with-middleware"><div class="inner"><span>with-middleware</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-with-min-level"><div class="inner"><span>with-min-level</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.html#var-with-ns-filter"><div class="inner"><span>with-ns-filter</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.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.html#var-with-signal"><div class="inner"><span>with-signal</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.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.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 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 View git blame Copy permalink