From 7c46b7b2d55d66b3a10b39c6741f0e9dbd3174fa Mon Sep 17 00:00:00 2001 From: Peter Taoussanis Date: Tue, 24 Dec 2024 11:23:39 +0100 Subject: [PATCH] v1.0.0-RC2 (2024-12-24) --- index.clj.html | 8 +- index.cljs.html | 4 +- index.html | 2 +- taoensso.telemere.cljs.html | 198 ++++++++++----------- taoensso.telemere.html | 247 +++++++++++++++----------- taoensso.telemere.open-telemetry.html | 2 +- taoensso.telemere.postal.html | 18 +- taoensso.telemere.slack.html | 2 +- taoensso.telemere.sockets.html | 2 +- taoensso.telemere.streams.html | 2 +- taoensso.telemere.timbre.cljs.html | 3 +- taoensso.telemere.timbre.html | 3 +- taoensso.telemere.tools-logging.html | 2 +- taoensso.telemere.utils.cljs.html | 19 +- taoensso.telemere.utils.html | 19 +- 15 files changed, 282 insertions(+), 249 deletions(-) diff --git a/index.clj.html b/index.clj.html index a93fcb6..ac45438 100644 --- a/index.clj.html +++ b/index.clj.html @@ -1,9 +1,9 @@ -Telemere 1.0.0-RC1

Namespaces

Telemere 1.0.0-RC1

Released under the Eclipse Public License - v 1.0

Structured telemetry library for Clojure/Script.

Installation

To install, add the following dependency to your project or build file:

[com.taoensso/telemere "1.0.0-RC1"]

Namespaces

taoensso.telemere

Structured telemetry for Clojure/Script applications.

Public variables and functions:

taoensso.telemere.open-telemetry

OpenTelemetry handler using `opentelemetry-java`,
+Telemere 1.0.0-RC2
Namespaces
Telemere 1.0.0-RC2
Released under the Eclipse Public License - v 1.0
Structured telemetry library for Clojure/Script.
Installation
To install, add the following dependency to your project or build file:
[com.taoensso/telemere "1.0.0-RC2"]
Namespaces
taoensso.telemere
Structured telemetry for Clojure/Script applications.
Public variables and functions:
taoensso.telemere.open-telemetry
OpenTelemetry handler using `opentelemetry-java`,
 Ref. <https://github.com/open-telemetry/opentelemetry-java>,
      <https://javadoc.io/doc/io.opentelemetry/opentelemetry-api/latest/index.html>
Public variables and functions:
taoensso.telemere.postal
Email handler using `postal`,
-Ref. <https://github.com/drewr/postal>.
Public variables and functions:
taoensso.telemere.slack
Slack handler using `clj-slack`,
+Ref. <https://github.com/drewr/postal>.
Public variables and functions:
taoensso.telemere.slack
Slack handler using `clj-slack`,
 Ref. <https://github.com/julienXX/clj-slack>
Public variables and functions:
taoensso.telemere.sockets
Basic TCP/UDP socket handlers.
Public variables and functions:
taoensso.telemere.streams
Interop support for standard stream/s -> Telemere.
Public variables and functions:
taoensso.telemere.timbre
Main Timbre macros, reimplemented on top of Telemere.
-Intended to help ease migration from Timbre to Telemere.
Public variables and functions:
taoensso.telemere.tools-logging
Interop support for tools.logging -> Telemere.
-Telemere will attempt to load this ns automatically when possible.
Public variables and functions:
taoensso.telemere.utils
Misc utils useful for Telemere handlers, middleware, etc.
Public variables and functions:

\ No newline at end of file
+Intended to help ease migration from Timbre to Telemere.

Public variables and functions:

taoensso.telemere.tools-logging

Interop support for tools.logging -> Telemere.
+Telemere will attempt to load this ns automatically when possible.

Public variables and functions:

taoensso.telemere.utils

Misc utils useful for Telemere handlers, middleware, etc.

Public variables and functions:

\ No newline at end of file diff --git a/index.cljs.html b/index.cljs.html index 7c15059..4c05e54 100644 --- a/index.cljs.html +++ b/index.cljs.html @@ -1,4 +1,4 @@ -Telemere 1.0.0-RC1

Namespaces

Telemere 1.0.0-RC1

Released under the Eclipse Public License - v 1.0

Structured telemetry library for Clojure/Script.

Installation

To install, add the following dependency to your project or build file:

[com.taoensso/telemere "1.0.0-RC1"]

Namespaces

taoensso.telemere

Structured telemetry for Clojure/Script applications.

Public variables and functions:

taoensso.telemere.timbre

Main Timbre macros, reimplemented on top of Telemere.
-Intended to help ease migration from Timbre to Telemere.

Public variables and functions:

taoensso.telemere.utils

Misc utils useful for Telemere handlers, middleware, etc.

Public variables and functions:

\ No newline at end of file +Telemere 1.0.0-RC2

Namespaces

Telemere 1.0.0-RC2

Released under the Eclipse Public License - v 1.0

Structured telemetry library for Clojure/Script.

Installation

To install, add the following dependency to your project or build file:

[com.taoensso/telemere "1.0.0-RC2"]

Namespaces

taoensso.telemere

Structured telemetry for Clojure/Script applications.

Public variables and functions:

taoensso.telemere.timbre

Main Timbre macros, reimplemented on top of Telemere.
+Intended to help ease migration from Timbre to Telemere.

Public variables and functions:

taoensso.telemere.utils

Misc utils useful for Telemere handlers, middleware, etc.

Public variables and functions:

\ No newline at end of file diff --git a/index.html b/index.html index 5c5c97e..f3b1caa 100644 --- a/index.html +++ b/index.html @@ -1,3 +1,3 @@ -Telemere 1.0.0-RC1

Platforms

Telemere 1.0.0-RC1

Released under the Eclipse Public License - v 1.0

Structured telemetry library for Clojure/Script.

Installation

To install, add the following dependency to your project or build file:

[com.taoensso/telemere "1.0.0-RC1"]

Platforms

This project includes code for multiple platforms, please choose a platform to view its documentation:

\ No newline at end of file +Telemere 1.0.0-RC2

Platforms

Telemere 1.0.0-RC2

Released under the Eclipse Public License - v 1.0

Structured telemetry library for Clojure/Script.

Installation

To install, add the following dependency to your project or build file:

[com.taoensso/telemere "1.0.0-RC2"]

Platforms

This project includes code for multiple platforms, please choose a platform to view its documentation:

\ No newline at end of file diff --git a/taoensso.telemere.cljs.html b/taoensso.telemere.cljs.html index 3a82015..06a849d 100644 --- a/taoensso.telemere.cljs.html +++ b/taoensso.telemere.cljs.html @@ -1,6 +1,6 @@ -taoensso.telemere documentation

Namespaces

Public Vars

taoensso.telemere

Structured telemetry for Clojure/Script applications.
+taoensso.telemere documentation
Namespaces
Public Vars
taoensso.telemere
Structured telemetry for Clojure/Script applications.
 
 See the GitHub page (esp. Wiki) for info on motivation and design:
   <https://www.taoensso.com/telemere>
*ctx*
dynamic
clj
cljs
Optional context (state) attached to all signals.
@@ -92,45 +92,7 @@ NB you should always call `stop-handlers!` somewhere appropriate - usually
 near the end of your `-main` or shutdown procedure, AFTER all other code has
 completed that could create signals.
 
-See `help:handler-dispatch-options` for handler filters, etc.
catch->error!
macro
clj
cljs
(catch->error! form)(catch->error! id form)(catch->error! {:as opts, :keys [rethrow? catch-val elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]} form)
Unconditionally executes given form and-
-  If form succeeds: return the form's result.
-  If form   throws:
-    Call `error!` with the thrown error and the given signal options [2],
-    then return (:catch-val opts) if it exists, or rethrow the error.
-
-API: [form] [id-or-opts form] => form's result (value/throw) (unconditional), or (:catch-val opts)
-Default  kind: `:error`
-Default level: `:error`
-
-Examples:
-
-  (catch->error! (/ 1 0))         ; %> {:kind :error, :level :error, :error <caught> ...}
-  (catch->error! ::my-id (/ 1 0)) ; %> {... :id ::my-id ...}
-  (catch->error!
-    {:let  [x "x"] ; Available to `:data` and `:msg`
-     :data {:x x}
-     :msg  ["My msg:" x my-error]
-     :catch-val "Return value when form throws"
-     :catch-sym my-error ; Sym of caught error, available to `:data` and `:msg`
-     }
-
-     (/ 1 0)) ; %> {... :data {x "x"}, :msg_ "My msg: x <caught>" ...}
-
-Tips:
-
-  - Test using `with-signal`: (with-signal (catch->error! ...)).
-  - Supports the same options [2] as other signals [1].
-
-  - Useful for preventing errors from going unnoticed in futures, callbacks,
-    agent actions, etc.!: (future (catch->error ::my-future (do-something)))
-
-See also `error!`.
-
-----------------------------------------------------------------------
-[1] See `help:signal-creators` - (`signal!`, `log!`, `event!`, ...)
-[2] See `help:signal-options`  - {:keys [kind level id data ...]}
-[3] See `help:signal-content`  - {:keys [kind level id data ...]}
-[4] See `help:signal-filters`  - (by ns/kind/id/level, sampling, etc.)
chance
clj
cljs
(chance prob)
Returns true with given probability ∈ ℝ[0,1].
+See `help:handler-dispatch-options` for handler filters, etc.
catch->error!
macro
clj
cljs
(catch->error! opts-or-run)(catch->error! id run)(catch->error! {:as opts-map, :keys [catch-val elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]} run)
chance
clj
cljs
(chance prob)
Returns true with given probability ∈ ℝ[0,1].
 
clean-signal-fn
clj
cljs
(clean-signal-fn)(clean-signal-fn {:keys [incl-kvs? incl-nils? incl-keys], :as opts})
Experimental, subject to change.
 Returns a (fn clean [signal]) that:
   - Takes a Telemere  signal (map).
@@ -160,9 +122,10 @@ custom/modified signals, etc.:
 
   (let [original-signal (with-signal :trap (event! ::my-id1))
         modified-signal (assoc original-signal :id ::my-id2)]
-    (dispatch-signal! modified-signal))
error!
macro
clj
cljs
(error! error)(error! id error)(error! {:as opts, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]} error)
"Error" signal creator, emphasizing error + id.
+    (dispatch-signal! modified-signal))
error!
macro
clj
cljs
(error! opts-or-error)(error! id error)(error! {:as opts-map, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]} error)
"Error" signal creator, emphasizing (optional id) + error (Exception, etc.).
+ALWAYS (unconditionally) returns the given error, so can conveniently be wrapped
+by `throw`: (throw (error! (ex-info ...)), etc.
 
-API: [error] [id-or-opts error] => given error (unconditional)
 Default  kind: `:error`
 Default level: `:error`
 
@@ -184,7 +147,6 @@ Tips:
   - Supports the same options [2] as other signals [1].
 
   - `error` arg is a platform error (`java.lang.Throwable` or `js/Error`).
-  - Can conveniently be wrapped by `throw`: (throw (error! ...)).
 
 ----------------------------------------------------------------------
 [1] See `help:signal-creators` - (`signal!`, `log!`, `event!`, ...)
@@ -192,9 +154,9 @@ Tips:
 [3] See `help:signal-content`  - {:keys [kind level id data ...]}
 [4] See `help:signal-filters`  - (by ns/kind/id/level, sampling, etc.)
error-signal?
clj
cljs
(error-signal? signal)
Experimental, subject to change.
 Returns true iff given signal has an `:error` value, or a `:kind` or `:level`
-that indicates that it's an error.
event!
macro
clj
cljs
(event! id)(event! id level)(event! id {:as opts, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]})
"Event" signal creator, emphasizing id + level.
+that indicates that it's an error.
event!
macro
clj
cljs
(event! opts-or-id)(event! id level)(event! id {:as opts-map, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]})
"Event" signal creator, emphasizing id + (optional level).
+Returns true iff signal was created (allowed by filtering).
 
-API: [id] [id level-or-opts] => true iff signal was allowed
 Default  kind: `:event`
 Default level: `:info`
 
@@ -324,18 +286,18 @@ Stats include:
     `:back-pressure` - Handler calls that experienced (async) back-pressure
                        (possible noop, depending on back-pressure mode)
 
-     `:sampled`      - Noop  handler calls due to sample rate
-     `:filtered`     - Noop  handler calls due to kind/ns/id/level/when filtering
-     `:rate-limited` - Noop  handler calls due to rate limit
-     `:disallowed`   - Noop  handler calls due to sampling/filtering/rate-limiting
-     `:allowed`      - Other handler calls    (no sampling/filtering/rate-limiting)
+    `:sampled`      - Noop  handler calls due to sample rate
+    `:filtered`     - Noop  handler calls due to kind/ns/id/level/when filtering
+    `:rate-limited` - Noop  handler calls due to rate limit
+    `:disallowed`   - Noop  handler calls due to sampling/filtering/rate-limiting
+    `:allowed`      - Other handler calls    (no sampling/filtering/rate-limiting)
 
-     `:suppressed`   - Noop handler calls due to nil middleware result
-     `:handled`      - Handler calls that completed successfully
-     `:errors`       - Handler calls that threw an error
+    `:suppressed`   - Noop handler calls due to nil middleware result
+    `:handled`      - Handler calls that completed successfully
+    `:errors`       - Handler calls that threw an error
 
-     Note that for performance reasons returned counts are not mutually atomic,
-     e.g. `:sampled` count may be incremented before `:disallowed` count is.
+    Note that for performance reasons returned counts are not mutually atomic,
+    e.g. `:sampled` count may be incremented before `:disallowed` count is.
 
 Useful for understanding/debugging how your handlers behave in practice,
 especially when they're under stress (high-volumes, etc.).
@@ -496,7 +458,7 @@ defaults specified by `default-handler-dispatch-opts`.
 
 All handlers support the same dispatch options, including:
 
-  `:async` (Clj only) options include:
+  `:async` (Clj only) - may be `nil` (synchronous) or map with options:
 
     `:buffer-size` (default 1024)
       Size of request buffer, and the max number of pending requests before
@@ -646,13 +608,13 @@ various keys:
 Creators vary only in in their default options and call APIs (expected args
 and return values), making them more/less convenient for certain use cases:
 
-  `event!` -------- [id   ] or [id   opts/level] => true iff signal was created (allowed)
-  `log!` ---------- [msg  ] or [opts/level  msg] => true iff signal was created (allowed)
-  `error!` -------- [error] or [opts/id   error] => given error (unconditional)
-  `trace!` -------- [form ] or [opts/id    form] => form result (value/throw) (unconditional)
-  `spy!` ---------- [form ] or [opts/level form] => form result (value/throw) (unconditional)
-  `catch->error!` - [form ] or [opts/id    form] => form value, or given fallback
-  `signal!` ------- [opts ]                      => depends on options
+  `signal!` ------- opts            => allowed? / unconditional run result (value or throw)
+  `event!` -------- id     + ?level => allowed?
+  `log!` ---------- ?level + msg    => allowed?
+  `trace!` -------- ?id    + run    => unconditional run result (value or throw)
+  `spy!` ---------- ?level + run    => unconditional run result (value or throw)
+  `error!` -------- ?id    + error  => unconditional given error
+  `catch->error!` - ?id    + run    => unconditional run value or ?catch-val
 
 - `log!` and `event!` are both good default/general-purpose signal creators.
 - `log!` emphasizes messages, while `event!` emphasizes ids.
@@ -661,7 +623,8 @@ and return values), making them more/less convenient for certain use cases:
 ----------------------------------------------------------------------
 [2] See `help:signal-options` - {:keys [kind level id data ...]}
 [3] See `help:signal-content` - {:keys [kind level id data ...]}
-[4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.)
help:signal-options
clj
cljs
Signal options (shared by all signal creators):
+[4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.)
help:signal-options
clj
cljs
Signal options are provided as a map with COMPILE-TIME keys.
+All options are available for all signal creators:
 
 `:inst` -------- Platform instant [1] when signal was created, ∈ #{nil :auto <[1]>}
 `:level` ------- Signal level ∈ #{<int> :trace :debug :info :warn :error :fatal :report ...}
@@ -670,11 +633,11 @@ and return values), making them more/less convenient for certain use cases:
 `:uid` --------- ?id of signal instance (unique to each signal  created at callsite, contrast with  `:id`)
                  Defaults to `:auto` for tracing signals, and nil otherwise
 
-`:msg` --------- Arb app-level ?message to incl. in signal: str or vec of strs to join (with `\space`)
+`:msg` --------- Arb app-level ?message to incl. in signal: str or vec of strs to join (with `\space`), may be a delay
 `:data` -------- Arb app-level ?data    to incl. in signal: usu. a map
 `:error` ------- Arb app-level ?error   to incl. in signal: platform error [2]
 
-`:run` --------- ?form     to execute UNCONDITIONALLY; will incl. `:run-value` in signal
+`:run` --------- ?form     to execute UNCONDITIONALLY; will incl. `:run-val` in signal
 `:do` ---------- ?form     to execute   conditionally (iff signal allowed), before establishing `:let` ?binding
 `:let` --------- ?bindings to establish conditionally (iff signal allowed), BEFORE evaluating `:data` and `:msg` (useful!)
 
@@ -700,9 +663,9 @@ and return values), making them more/less convenient for certain use cases:
 If anything is unclear, please ping me (@ptaoussanis) so that I can improve these docs!
 
 [1] `java.time.Instant`   or `js/Date`
-[2] `java.lang.Throwable` or `js/Error`
level-aliases
clj
cljs
log!
macro
clj
cljs
(log! msg)(log! level msg)(log! {:as opts, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]} msg)
"Log" signal creator, emphasizing message + level.
+[2] `java.lang.Throwable` or `js/Error`
level-aliases
clj
cljs
log!
macro
clj
cljs
(log! opts-or-msg)(log! level msg)(log! {:as opts-map, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]} msg)
"Log" signal creator, emphasizing (optional level) + message.
+Returns true iff signal was created (allowed by filtering).
 
-API: [msg] [level-or-opts msg] => true iff signal was allowed.
 Default  kind: `:log`
 Default level: `:info`
 
@@ -844,19 +807,20 @@ Examples:
   - A map, {:allow <spec> :disallow <spec>} with specs as above:
     If present, `:allow`    spec MUST     match, AND
     If present, `:disallow` spec MUST NOT match.
set-var-root!
macro
clj
cljs
added in Encore v3.75.0 (2024-01-29)
(set-var-root! var-sym root-val)
Sets root binding (value) of the var identified by given symbol, and returns
-the new value. Cross-platform. See also `update-var-root!`.
signal!
macro
clj
cljs
(signal! {:as opts, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error run & kvs]})
Low-level generic signal creator.
+the new value. Cross-platform. See also `update-var-root!`.
signal!
macro
clj
cljs
(signal! & opts-kvs)(signal! {:as opts-map, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error run & kvs]})
Low-level "generic" signal creator for creating signals of any "kind".
+Takes a single map of options [2] with compile-time keys.
 
-API: [opts] => depends on options [2]
-Default  kind: none (optional)
-Default level: none (must be provided)
+Return value depends on options:
+  - If given `:run` form: unconditionally returns run value, or rethrows run error.
+  - Otherwise: returns true iff signal was created (allowed by filtering).
+
+Default  kind: `:generic` (feel free to change!)
+Default level: `:info`
 
 When filtering conditions are met [4], creates a Telemere signal [3] and
 dispatches it to registered handlers for processing (e.g. writing to
 console/file/queue/db, etc.).
 
-If `:run` option is provided: returns value of given run form, or throws.
-                   Otherwise: returns true iff signal was created (allowed).
-
 Generic signals are fairly low-level and useful mostly for library authors or
 advanced users writing their own wrapper macros. Regular users will typically
 prefer one of the higher-level signal creators optimized for ease-of-use in
@@ -871,7 +835,7 @@ Tips:
 [1] See `help:signal-creators` - (`signal!`, `log!`, `event!`, ...)
 [2] See `help:signal-options`  - {:keys [kind level id data ...]}
 [3] See `help:signal-content`  - {:keys [kind level id data ...]}
-[4] See `help:signal-filters`  - (by ns/kind/id/level, sampling, etc.)
signal-allowed?
macro
clj
cljs
(signal-allowed? {:as opts, :keys [elidable? location sample-rate kind ns id level when rate-limit rate-limit-by]})
Returns true iff signal with given opts would meet filtering conditions:
+[4] See `help:signal-filters`  - (by ns/kind/id/level, sampling, etc.)
signal-allowed?
macro
clj
cljs
(signal-allowed? & opts-kvs)(signal-allowed? {:as opts-map, :keys [elidable? location sample-rate kind ns id level when rate-limit rate-limit-by]})
Returns true iff signal with given opts would meet filtering conditions:
  (when (signal-allowed? {:level :warn, <...>}) (my-custom-code))
 
 Allows you to use Telemere's rich filtering system for conditionally
@@ -881,9 +845,9 @@ under a single set of conditions (incl. rate-limiting, sampling, etc.):
   ;; Logs exactly 2 or 0 messages (never 1):
   (when (signal-allowed? {:level :info, :sample-rate 0.5})
     (log! {:allow? true} "Message 1")
-    (log! {:allow? true} "Message 2"))
spy!
macro
clj
cljs
(spy! form)(spy! level form)(spy! {:as opts, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error run & kvs]} form)
"Spy" signal creator, emphasizing form + level.
+    (log! {:allow? true} "Message 2"))
spy!
macro
clj
cljs
(spy! opts-or-run)(spy! level run)(spy! {:as opts-map, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error run & kvs]} run)
"Spy" signal creator, emphasizing (optional level) + form to run.
+ALWAYS (unconditionally) returns run value, or rethrows run error.
 
-API: [form] [level-or-opts form] => form's result (value/throw) (unconditional)
 Default kind:  `:spy`
 Default level: `:info`
 
@@ -891,14 +855,14 @@ When filtering conditions are met [4], creates a Telemere signal [3] and
 dispatches it to registered handlers for processing (e.g. writing to
 console/file/queue/db, etc.).
 
-Enables tracing of given `form` arg:
+Enables tracing of given `run` form:
 
   - Resulting signal  will include {:keys [run-form run-val run-nsecs]}.
   - Nested    signals will include this signal's id and uid under `:parent`.
 
 Limitations:
 
-  1. Traced code (`form` arg) is usually expected to be synchronous and eager.
+  1. Traced `run` form is usually expected to be synchronous and eager.
      So no lazy seqs, async calls, or inversion of flow control (IoC) macros like
      core.async `go` blocks, etc.
 
@@ -920,7 +884,8 @@ Examples:
   (spy! ::my-id (+ 1 2)) ; %> {... :id ::my-id ...}
   (spy!
     {:let  [x "x"] ; Available to `:data` and `:msg`
-     :data {:x x}}
+     :data {:x x}
+     :msg  ["My message:" x]}
 
     (+ 1 2)) ; %> {... :data {x "x"}, :msg_ "My msg: x" ...}
 
@@ -929,18 +894,28 @@ Tips:
   - Test using `with-signal`: (with-signal (spy! ...)).
   - Supports the same options [2] as other signals [1].
 
-  - Identical to `trace!`, but emphasizes form + level rather than form + id.
+  - Like `trace!`, but takes optional level rather than optional id.
 
   - Useful for debugging/monitoring forms, and tracing (nested) execution flow.
-  - Execution of `form` arg may create additional (nested) signals.
+  - Execution of `run` form may create additional (nested) signals.
     Each signal's `:parent` key will indicate its immediate parent.
 
-  - Can be useful to wrap with `catch->error!`:
-      (catch->error! ::error-id (spy! ...)).
+  - It's often useful to wrap `run` form with `catch->error!`:
+      (trace! ::trace-id (catch->error! ::error-id ...)).
 
-  - Runtime of async or lazy code in `form` will intentionally NOT be included
-    in resulting signal's `:run-nsecs` value. If you want to measure such
-    runtimes, make sure that your form wraps where the relevant costs are
+    This way you have independent filtering for `run` forms that throw,
+    allowing you to use a higher min level and/or reduced sampling, etc.
+
+    In this case you'll create:
+      0 or 1 `:trace` signals (depending on filtering), AND
+      0 or 1 `:error` signals (depending on filtering).
+
+    Note that the `:error` signal will contain tracing info (e.g. `:parent` key)
+    iff the enclosing `trace!` is allowed.
+
+  - Runtime of async or lazy code in `run` form will intentionally NOT be
+    included in resulting signal's `:run-nsecs` value. If you want to measure
+    such runtimes, make sure that your form wraps where the relevant costs are
     actually realized. Compare:
       (spy!  (delay (my-slow-code))) ; Doesn't measure slow code
       (spy! @(delay (my-slow-code))) ; Does    measure slow code
@@ -964,9 +939,9 @@ handler's `:drain-msecs` value (see `help:handler-dispatch-options`).
 
 NB you should always call `stop-handlers!` somewhere appropriate - usually
 near the end of your `-main` or shutdown procedure, AFTER all other code has
-completed that could create signals.
trace!
macro
clj
cljs
(trace! form)(trace! id form)(trace! {:as opts, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error run & kvs]} form)
"Trace" signal creator, emphasizing form + id.
+completed that could create signals.
trace!
macro
clj
cljs
(trace! opts-or-run)(trace! id run)(trace! {:as opts-map, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error run & kvs]} run)
"Trace" signal creator, emphasizing (optional id) + form to run.
+ALWAYS (unconditionally) returns run value, or rethrows run error.
 
-API: [form] [id-or-opts form] => form's result (value/throw) (unconditional)
 Default  kind: `:trace`
 Default level: `:info` (intentionally NOT `:trace`!)
 
@@ -974,14 +949,14 @@ When filtering conditions are met [4], creates a Telemere signal [3] and
 dispatches it to registered handlers for processing (e.g. writing to
 console/file/queue/db, etc.).
 
-Enables tracing of given `form` arg:
+Enables tracing of given `run` form:
 
   - Resulting signal  will include {:keys [run-form run-val run-nsecs]}.
   - Nested    signals will include this signal's id and uid under `:parent`.
 
 Limitations:
 
-  1. Traced code (`form` arg) is usually expected to be synchronous and eager.
+  1. Traced `run` form is usually expected to be synchronous and eager.
      So no lazy seqs, async calls, or inversion of flow control (IoC) macros like
      core.async `go` blocks, etc.
 
@@ -1003,7 +978,8 @@ Examples:
   (trace! ::my-id (+ 1 2)) ; %> {... :id ::my-id ...}
   (trace!
     {:let  [x "x"] ; Available to `:data` and `:msg`
-     :data {:x x}}
+     :data {:x x}
+     :msg  ["My message:" x]}
 
     (+ 1 2)) ; %> {... :data {x "x"}, :msg_ "My msg: x" ...}
 
@@ -1012,22 +988,32 @@ Tips:
   - Test using `with-signal`: (with-signal (trace! ...)).
   - Supports the same options [2] as other signals [1].
 
-  - Identical to `spy!`, but emphasizes form + id rather than form + level.
+  - Like `spy!`, but takes optional id rather than optional level.
 
   - Useful for debugging/monitoring forms, and tracing (nested) execution flow.
-  - Execution of `form` arg may create additional (nested) signals.
+  - Execution of `run` form may create additional (nested) signals.
     Each signal's `:parent` key will indicate its immediate parent.
 
-  - Can be useful to wrap with `catch->error!`:
-      (catch->error! ::error-id (trace! ...)).
+  - It's often useful to wrap `run` form with `catch->error!`:
+      (trace! ::trace-id (catch->error! ::error-id ...)).
+
+    This way you have independent filtering for `run` forms that throw,
+    allowing you to use a higher min level and/or reduced sampling, etc.
+
+    In this case you'll create:
+      0 or 1 `:trace` signals (depending on filtering), AND
+      0 or 1 `:error` signals (depending on filtering).
+
+    Note that the `:error` signal will contain tracing info (e.g. `:parent` key)
+    iff the enclosing `trace!` is allowed.
 
   - Default level is `:info`, not `:trace`! The name "trace" in "trace signal"
     refers to the general action of tracing program flow rather than to the
     common logging level of the same name.
 
-  - Runtime of async or lazy code in `form` will intentionally NOT be included
-    in resulting signal's `:run-nsecs` value. If you want to measure such
-    runtimes, make sure that your form wraps where the relevant costs are
+  - Runtime of async or lazy code in `run` form will intentionally NOT be
+    included in resulting signal's `:run-nsecs` value. If you want to measure
+    such runtimes, make sure that your form wraps where the relevant costs are
     actually realized. Compare:
       (trace!  (delay (my-slow-code))) ; Doesn't measure slow code
       (trace! @(delay (my-slow-code))) ; Does    measure slow code
@@ -1040,7 +1026,7 @@ Tips:
 [1] See `help:signal-creators` - (`signal!`, `log!`, `event!`, ...)
 [2] See `help:signal-options`  - {:keys [kind level id data ...]}
 [3] See `help:signal-content`  - {:keys [kind level id data ...]}
-[4] See `help:signal-filters`  - (by ns/kind/id/level, sampling, etc.)
uncaught->error!
macro
clj
cljs
(uncaught->error!)(uncaught->error! id)(uncaught->error! {:as opts, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]})
Uses `uncaught->handler!` so that `error!` will be called for
+[4] See `help:signal-filters`  - (by ns/kind/id/level, sampling, etc.)
uncaught->error!
macro
clj
cljs
(uncaught->error!)(uncaught->error! opts-or-id)(uncaught->error! {:as opts-map, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]})
Uses `uncaught->handler!` so that `error!` will be called for
 uncaught JVM errors.
 
 See `uncaught->handler!` and `error!` for details.
update-var-root!
macro
clj
cljs
added in Encore v3.68.0 (2023-09-25)
(update-var-root! var-sym update-fn)
Updates root binding (value) of the var identified by given symbol, and returns
@@ -1085,8 +1071,12 @@ Options:
     Should delayed `:msg_` in returned signal be retained as-is?
     Delay is otherwise replaced by realized string.
 
-See also `with-signals`.
with-signals
macro
clj
cljs
(with-signals form)(with-signals trap-signals? form)(with-signals raw-msgs? trap-signals? form)
Experimental, subject to change.
-Like `with-signal` but returns [[<form-value> <form-error>] [<signal1> ...]].
-Useful for tests/debugging.
with-streams->telemere
macro
clj
cljs
(with-streams->telemere form)(with-streams->telemere {:keys [out err], :or {out default-out-opts, err default-err-opts}} form)
Executes form with `*out*` and/or `*err*` bound to flush to Telemere signals
+See also `with-signals` for more advanced options.
with-signals
macro
clj
cljs
(with-signals form)(with-signals trap-signals? form)(with-signals raw-msgs? trap-signals? form)
Experimental, subject to change.
+Like `with-signal` but returns {:keys [value error signals]}.
+Useful for more advanced tests/debugging.
+
+Destructuring example:
+  (let [{:keys [value error] [sig1 sig2] :signals} (with-signals ...)]
+    ...)
with-streams->telemere
macro
clj
cljs
(with-streams->telemere form)(with-streams->telemere {:keys [out err], :or {out default-out-opts, err default-err-opts}} form)
Executes form with `*out*` and/or `*err*` bound to flush to Telemere signals
 with given opts.
without-filters
macro
clj
cljs
(without-filters form)
Executes form without any runtime signal filters.
 

\ No newline at end of file
diff --git a/taoensso.telemere.html b/taoensso.telemere.html
index 10d7f0d..d0d7903 100644
--- a/taoensso.telemere.html
+++ b/taoensso.telemere.html
@@ -1,6 +1,6 @@
 
-taoensso.telemere documentation
Namespaces
Public Vars
taoensso.telemere
Structured telemetry for Clojure/Script applications.
+taoensso.telemere documentation
Namespaces
Public Vars
taoensso.telemere
Structured telemetry for Clojure/Script applications.
 
 See the GitHub page (esp. Wiki) for info on motivation and design:
   <https://www.taoensso.com/telemere>
*ctx*
dynamic
clj
cljs
Optional context (state) attached to all signals.
@@ -47,7 +47,13 @@ Examples:
 
 Tips:
   - Compose multiple middleware fns together with `comp-middleware`.
-  - Use `get-env` to set default (root) value based on environmental config.
*otel-tracer*
dynamic
clj
*uid-fn*
dynamic
clj
cljs
Experimental, subject to change. Feedback welcome!
+  - Use `get-env` to set default (root) value based on environmental config.
*otel-tracer*
dynamic
clj
Experimental, subject to change. Feedback welcome!
+
+OpenTelemetry `Tracer` to use for Telemere's tracing signal creators
+(`trace!`, `span!`, etc.), ∈ #{nil io.opentelemetry.api.trace.Tracer Delay}.
+
+Defaults to the provider in `otel-default-providers_`.
+See also `otel-tracing?`.
*uid-fn*
dynamic
clj
cljs
Experimental, subject to change. Feedback welcome!
 (fn [root?]) used to generate signal `:uid` values (unique instance ids)
 when tracing.
 
@@ -69,47 +75,32 @@ Override default by setting one of the following:
     `:nano/secure`   - nano-style string (21/10 chars) w/ strong RNG
     `:nano/insecure` - nano-style string (21/10 chars) w/ fast   RNG (default)
     `:hex/insecure`  - hex-style  string (32/16 chars) w/ strong RNG
-    `:hex/secure`    - hex-style  string (32/16 chars) w/ fast   RNG
add-handler!
clj
cljs
call-on-shutdown!
clj
added in Encore v3.114.0 (2024-08-07)
(call-on-shutdown! f)
Registers given nullary fn as a JVM shutdown hook.
+    `:hex/secure`    - hex-style  string (32/16 chars) w/ fast   RNG
add-handler!
clj
cljs
(add-handler! handler-id handler-fn)(add-handler! handler-id handler-fn dispatch-opts)
Registers given signal handler and returns
+{<handler-id> {:keys [dispatch-opts handler-fn]}} for all handlers
+now registered. If an old handler already existed under the same id, stop it.
+
+`handler-fn` should be a fn of exactly 2 arities:
+
+  [signal] ; Single argument
+    Called asynchronously or synchronously (depending on dispatch options)
+    to do something useful with the given signal.
+
+    Example actions:
+      Save data to disk or db, `tap>`, log, `put!` to an appropriate
+      `core.async` channel, filter, aggregate, use for a realtime analytics
+      dashboard, examine for outliers or unexpected data, etc.
+
+  [] ; No arguments
+    Called exactly once when stopping handler to provide an opportunity
+    for handler to flush buffers, close files, etc. May just noop.
+
+NB you should always call `stop-handlers!` somewhere appropriate - usually
+near the end of your `-main` or shutdown procedure, AFTER all other code has
+completed that could create signals.
+
+See `help:handler-dispatch-options` for handler filters, etc.
call-on-shutdown!
clj
added in Encore v3.114.0 (2024-08-07)
(call-on-shutdown! f)
Registers given nullary fn as a JVM shutdown hook.
 (f) will be called sometime during shutdown. While running, it will
-attempt to block shutdown.
catch->error!
macro
clj
cljs
(catch->error! form)(catch->error! id form)(catch->error! {:as opts, :keys [rethrow? catch-val elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]} form)
Unconditionally executes given form and-
-  If form succeeds: return the form's result.
-  If form   throws:
-    Call `error!` with the thrown error and the given signal options [2],
-    then return (:catch-val opts) if it exists, or rethrow the error.
-
-API: [form] [id-or-opts form] => form's result (value/throw) (unconditional), or (:catch-val opts)
-Default  kind: `:error`
-Default level: `:error`
-
-Examples:
-
-  (catch->error! (/ 1 0))         ; %> {:kind :error, :level :error, :error <caught> ...}
-  (catch->error! ::my-id (/ 1 0)) ; %> {... :id ::my-id ...}
-  (catch->error!
-    {:let  [x "x"] ; Available to `:data` and `:msg`
-     :data {:x x}
-     :msg  ["My msg:" x my-error]
-     :catch-val "Return value when form throws"
-     :catch-sym my-error ; Sym of caught error, available to `:data` and `:msg`
-     }
-
-     (/ 1 0)) ; %> {... :data {x "x"}, :msg_ "My msg: x <caught>" ...}
-
-Tips:
-
-  - Test using `with-signal`: (with-signal (catch->error! ...)).
-  - Supports the same options [2] as other signals [1].
-
-  - Useful for preventing errors from going unnoticed in futures, callbacks,
-    agent actions, etc.!: (future (catch->error ::my-future (do-something)))
-
-See also `error!`.
-
-----------------------------------------------------------------------
-[1] See `help:signal-creators` - (`signal!`, `log!`, `event!`, ...)
-[2] See `help:signal-options`  - {:keys [kind level id data ...]}
-[3] See `help:signal-content`  - {:keys [kind level id data ...]}
-[4] See `help:signal-filters`  - (by ns/kind/id/level, sampling, etc.)
chance
clj
cljs
(chance prob)
Returns true with given probability ∈ ℝ[0,1].
+attempt to block shutdown.
catch->error!
macro
clj
cljs
(catch->error! opts-or-run)(catch->error! id run)(catch->error! {:as opts-map, :keys [catch-val elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]} run)
chance
clj
cljs
(chance prob)
Returns true with given probability ∈ ℝ[0,1].
 
check-interop
clj
(check-interop)
Experimental, subject to change.
 Runs Telemere's registered interop checks and returns info useful
 for tests/debugging, e.g.:
@@ -149,9 +140,10 @@ custom/modified signals, etc.:
 
   (let [original-signal (with-signal :trap (event! ::my-id1))
         modified-signal (assoc original-signal :id ::my-id2)]
-    (dispatch-signal! modified-signal))
error!
macro
clj
cljs
(error! error)(error! id error)(error! {:as opts, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]} error)
"Error" signal creator, emphasizing error + id.
+    (dispatch-signal! modified-signal))
error!
macro
clj
cljs
(error! opts-or-error)(error! id error)(error! {:as opts-map, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]} error)
"Error" signal creator, emphasizing (optional id) + error (Exception, etc.).
+ALWAYS (unconditionally) returns the given error, so can conveniently be wrapped
+by `throw`: (throw (error! (ex-info ...)), etc.
 
-API: [error] [id-or-opts error] => given error (unconditional)
 Default  kind: `:error`
 Default level: `:error`
 
@@ -173,7 +165,6 @@ Tips:
   - Supports the same options [2] as other signals [1].
 
   - `error` arg is a platform error (`java.lang.Throwable` or `js/Error`).
-  - Can conveniently be wrapped by `throw`: (throw (error! ...)).
 
 ----------------------------------------------------------------------
 [1] See `help:signal-creators` - (`signal!`, `log!`, `event!`, ...)
@@ -181,9 +172,9 @@ Tips:
 [3] See `help:signal-content`  - {:keys [kind level id data ...]}
 [4] See `help:signal-filters`  - (by ns/kind/id/level, sampling, etc.)
error-signal?
clj
cljs
(error-signal? signal)
Experimental, subject to change.
 Returns true iff given signal has an `:error` value, or a `:kind` or `:level`
-that indicates that it's an error.
event!
macro
clj
cljs
(event! id)(event! id level)(event! id {:as opts, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]})
"Event" signal creator, emphasizing id + level.
+that indicates that it's an error.
event!
macro
clj
cljs
(event! opts-or-id)(event! id level)(event! id {:as opts-map, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]})
"Event" signal creator, emphasizing id + (optional level).
+Returns true iff signal was created (allowed by filtering).
 
-API: [id] [id level-or-opts] => true iff signal was allowed
 Default  kind: `:event`
 Default level: `:info`
 
@@ -313,18 +304,18 @@ Stats include:
     `:back-pressure` - Handler calls that experienced (async) back-pressure
                        (possible noop, depending on back-pressure mode)
 
-     `:sampled`      - Noop  handler calls due to sample rate
-     `:filtered`     - Noop  handler calls due to kind/ns/id/level/when filtering
-     `:rate-limited` - Noop  handler calls due to rate limit
-     `:disallowed`   - Noop  handler calls due to sampling/filtering/rate-limiting
-     `:allowed`      - Other handler calls    (no sampling/filtering/rate-limiting)
+    `:sampled`      - Noop  handler calls due to sample rate
+    `:filtered`     - Noop  handler calls due to kind/ns/id/level/when filtering
+    `:rate-limited` - Noop  handler calls due to rate limit
+    `:disallowed`   - Noop  handler calls due to sampling/filtering/rate-limiting
+    `:allowed`      - Other handler calls    (no sampling/filtering/rate-limiting)
 
-     `:suppressed`   - Noop handler calls due to nil middleware result
-     `:handled`      - Handler calls that completed successfully
-     `:errors`       - Handler calls that threw an error
+    `:suppressed`   - Noop handler calls due to nil middleware result
+    `:handled`      - Handler calls that completed successfully
+    `:errors`       - Handler calls that threw an error
 
-     Note that for performance reasons returned counts are not mutually atomic,
-     e.g. `:sampled` count may be incremented before `:disallowed` count is.
+    Note that for performance reasons returned counts are not mutually atomic,
+    e.g. `:sampled` count may be incremented before `:disallowed` count is.
 
 Useful for understanding/debugging how your handlers behave in practice,
 especially when they're under stress (high-volumes, etc.).
@@ -506,7 +497,7 @@ defaults specified by `default-handler-dispatch-opts`.
 
 All handlers support the same dispatch options, including:
 
-  `:async` (Clj only) options include:
+  `:async` (Clj only) - may be `nil` (synchronous) or map with options:
 
     `:buffer-size` (default 1024)
       Size of request buffer, and the max number of pending requests before
@@ -656,13 +647,13 @@ various keys:
 Creators vary only in in their default options and call APIs (expected args
 and return values), making them more/less convenient for certain use cases:
 
-  `event!` -------- [id   ] or [id   opts/level] => true iff signal was created (allowed)
-  `log!` ---------- [msg  ] or [opts/level  msg] => true iff signal was created (allowed)
-  `error!` -------- [error] or [opts/id   error] => given error (unconditional)
-  `trace!` -------- [form ] or [opts/id    form] => form result (value/throw) (unconditional)
-  `spy!` ---------- [form ] or [opts/level form] => form result (value/throw) (unconditional)
-  `catch->error!` - [form ] or [opts/id    form] => form value, or given fallback
-  `signal!` ------- [opts ]                      => depends on options
+  `signal!` ------- opts            => allowed? / unconditional run result (value or throw)
+  `event!` -------- id     + ?level => allowed?
+  `log!` ---------- ?level + msg    => allowed?
+  `trace!` -------- ?id    + run    => unconditional run result (value or throw)
+  `spy!` ---------- ?level + run    => unconditional run result (value or throw)
+  `error!` -------- ?id    + error  => unconditional given error
+  `catch->error!` - ?id    + run    => unconditional run value or ?catch-val
 
 - `log!` and `event!` are both good default/general-purpose signal creators.
 - `log!` emphasizes messages, while `event!` emphasizes ids.
@@ -671,7 +662,8 @@ and return values), making them more/less convenient for certain use cases:
 ----------------------------------------------------------------------
 [2] See `help:signal-options` - {:keys [kind level id data ...]}
 [3] See `help:signal-content` - {:keys [kind level id data ...]}
-[4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.)
help:signal-options
clj
cljs
Signal options (shared by all signal creators):
+[4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.)
help:signal-options
clj
cljs
Signal options are provided as a map with COMPILE-TIME keys.
+All options are available for all signal creators:
 
 `:inst` -------- Platform instant [1] when signal was created, ∈ #{nil :auto <[1]>}
 `:level` ------- Signal level ∈ #{<int> :trace :debug :info :warn :error :fatal :report ...}
@@ -680,11 +672,11 @@ and return values), making them more/less convenient for certain use cases:
 `:uid` --------- ?id of signal instance (unique to each signal  created at callsite, contrast with  `:id`)
                  Defaults to `:auto` for tracing signals, and nil otherwise
 
-`:msg` --------- Arb app-level ?message to incl. in signal: str or vec of strs to join (with `\space`)
+`:msg` --------- Arb app-level ?message to incl. in signal: str or vec of strs to join (with `\space`), may be a delay
 `:data` -------- Arb app-level ?data    to incl. in signal: usu. a map
 `:error` ------- Arb app-level ?error   to incl. in signal: platform error [2]
 
-`:run` --------- ?form     to execute UNCONDITIONALLY; will incl. `:run-value` in signal
+`:run` --------- ?form     to execute UNCONDITIONALLY; will incl. `:run-val` in signal
 `:do` ---------- ?form     to execute   conditionally (iff signal allowed), before establishing `:let` ?binding
 `:let` --------- ?bindings to establish conditionally (iff signal allowed), BEFORE evaluating `:data` and `:msg` (useful!)
 
@@ -711,9 +703,9 @@ If anything is unclear, please ping me (@ptaoussanis) so that I can improve thes
 
 [1] `java.time.Instant`   or `js/Date`
 [2] `java.lang.Throwable` or `js/Error`
level-aliases
clj
cljs
Map of {<level-keyword> <level-integer>} aliases.
-
log!
macro
clj
cljs
(log! msg)(log! level msg)(log! {:as opts, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]} msg)
"Log" signal creator, emphasizing message + level.
+
log!
macro
clj
cljs
(log! opts-or-msg)(log! level msg)(log! {:as opts-map, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]} msg)
"Log" signal creator, emphasizing (optional level) + message.
+Returns true iff signal was created (allowed by filtering).
 
-API: [msg] [level-or-opts msg] => true iff signal was allowed.
 Default  kind: `:log`
 Default level: `:info`
 
@@ -761,7 +753,21 @@ Useful for conditionally splicing in extra message content, etc.:
   (log!          [(when <cond> (msg-splice ["Username:" "Steve"]))])
 
     %> {:msg_ "Username: Steve"}
newline
clj
cljs
added in Encore v3.68.0 (2023-09-25)
Single system newline
-
otel-default-providers_
clj
otel-tracing?
clj
Experimental, subject to change. Feedback welcome!
+
otel-default-providers_
clj
Experimental, subject to change. Feedback welcome!
+
+When OpenTelemetry Java API [1] is present, value will be a delayed map
+with keys:
+  :logger-provider     - default `io.opentelemetry.api.logs.LoggerProvider`
+  :tracer-provider     - default `io.opentelemetry.api.trace.TracerProvider`
+  :via                 - ∈ #{:sdk-extension-autoconfigure :global}
+  :auto-configured-sdk - `io.opentelemetry.sdk.OpenTelemetrySdk` or nil
+
+Uses `AutoConfiguredOpenTelemetrySdk` when possible, or
+`GlobalOpenTelemetry` otherwise.
+
+See the relevant OpenTelemetry Java docs for details.
+
+[1] Ref. <https://github.com/open-telemetry/opentelemetry-java>
otel-tracing?
clj
Experimental, subject to change. Feedback welcome!
 
 Should Telemere's tracing signal creators (`trace!`, `spy!`, etc.)
 interop with OpenTelemetry Java [1]? This will affect relevant
@@ -887,19 +893,20 @@ Examples:
   - A map, {:allow <spec> :disallow <spec>} with specs as above:
     If present, `:allow`    spec MUST     match, AND
     If present, `:disallow` spec MUST NOT match.
set-var-root!
macro
clj
cljs
added in Encore v3.75.0 (2024-01-29)
(set-var-root! var-sym root-val)
Sets root binding (value) of the var identified by given symbol, and returns
-the new value. Cross-platform. See also `update-var-root!`.
signal!
macro
clj
cljs
(signal! {:as opts, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error run & kvs]})
Low-level generic signal creator.
+the new value. Cross-platform. See also `update-var-root!`.
signal!
macro
clj
cljs
(signal! & opts-kvs)(signal! {:as opts-map, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error run & kvs]})
Low-level "generic" signal creator for creating signals of any "kind".
+Takes a single map of options [2] with compile-time keys.
 
-API: [opts] => depends on options [2]
-Default  kind: none (optional)
-Default level: none (must be provided)
+Return value depends on options:
+  - If given `:run` form: unconditionally returns run value, or rethrows run error.
+  - Otherwise: returns true iff signal was created (allowed by filtering).
+
+Default  kind: `:generic` (feel free to change!)
+Default level: `:info`
 
 When filtering conditions are met [4], creates a Telemere signal [3] and
 dispatches it to registered handlers for processing (e.g. writing to
 console/file/queue/db, etc.).
 
-If `:run` option is provided: returns value of given run form, or throws.
-                   Otherwise: returns true iff signal was created (allowed).
-
 Generic signals are fairly low-level and useful mostly for library authors or
 advanced users writing their own wrapper macros. Regular users will typically
 prefer one of the higher-level signal creators optimized for ease-of-use in
@@ -914,7 +921,7 @@ Tips:
 [1] See `help:signal-creators` - (`signal!`, `log!`, `event!`, ...)
 [2] See `help:signal-options`  - {:keys [kind level id data ...]}
 [3] See `help:signal-content`  - {:keys [kind level id data ...]}
-[4] See `help:signal-filters`  - (by ns/kind/id/level, sampling, etc.)
signal-allowed?
macro
clj
cljs
(signal-allowed? {:as opts, :keys [elidable? location sample-rate kind ns id level when rate-limit rate-limit-by]})
Returns true iff signal with given opts would meet filtering conditions:
+[4] See `help:signal-filters`  - (by ns/kind/id/level, sampling, etc.)
signal-allowed?
macro
clj
cljs
(signal-allowed? & opts-kvs)(signal-allowed? {:as opts-map, :keys [elidable? location sample-rate kind ns id level when rate-limit rate-limit-by]})
Returns true iff signal with given opts would meet filtering conditions:
  (when (signal-allowed? {:level :warn, <...>}) (my-custom-code))
 
 Allows you to use Telemere's rich filtering system for conditionally
@@ -924,9 +931,9 @@ under a single set of conditions (incl. rate-limiting, sampling, etc.):
   ;; Logs exactly 2 or 0 messages (never 1):
   (when (signal-allowed? {:level :info, :sample-rate 0.5})
     (log! {:allow? true} "Message 1")
-    (log! {:allow? true} "Message 2"))
spy!
macro
clj
cljs
(spy! form)(spy! level form)(spy! {:as opts, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error run & kvs]} form)
"Spy" signal creator, emphasizing form + level.
+    (log! {:allow? true} "Message 2"))
spy!
macro
clj
cljs
(spy! opts-or-run)(spy! level run)(spy! {:as opts-map, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error run & kvs]} run)
"Spy" signal creator, emphasizing (optional level) + form to run.
+ALWAYS (unconditionally) returns run value, or rethrows run error.
 
-API: [form] [level-or-opts form] => form's result (value/throw) (unconditional)
 Default kind:  `:spy`
 Default level: `:info`
 
@@ -934,14 +941,14 @@ When filtering conditions are met [4], creates a Telemere signal [3] and
 dispatches it to registered handlers for processing (e.g. writing to
 console/file/queue/db, etc.).
 
-Enables tracing of given `form` arg:
+Enables tracing of given `run` form:
 
   - Resulting signal  will include {:keys [run-form run-val run-nsecs]}.
   - Nested    signals will include this signal's id and uid under `:parent`.
 
 Limitations:
 
-  1. Traced code (`form` arg) is usually expected to be synchronous and eager.
+  1. Traced `run` form is usually expected to be synchronous and eager.
      So no lazy seqs, async calls, or inversion of flow control (IoC) macros like
      core.async `go` blocks, etc.
 
@@ -963,7 +970,8 @@ Examples:
   (spy! ::my-id (+ 1 2)) ; %> {... :id ::my-id ...}
   (spy!
     {:let  [x "x"] ; Available to `:data` and `:msg`
-     :data {:x x}}
+     :data {:x x}
+     :msg  ["My message:" x]}
 
     (+ 1 2)) ; %> {... :data {x "x"}, :msg_ "My msg: x" ...}
 
@@ -972,18 +980,28 @@ Tips:
   - Test using `with-signal`: (with-signal (spy! ...)).
   - Supports the same options [2] as other signals [1].
 
-  - Identical to `trace!`, but emphasizes form + level rather than form + id.
+  - Like `trace!`, but takes optional level rather than optional id.
 
   - Useful for debugging/monitoring forms, and tracing (nested) execution flow.
-  - Execution of `form` arg may create additional (nested) signals.
+  - Execution of `run` form may create additional (nested) signals.
     Each signal's `:parent` key will indicate its immediate parent.
 
-  - Can be useful to wrap with `catch->error!`:
-      (catch->error! ::error-id (spy! ...)).
+  - It's often useful to wrap `run` form with `catch->error!`:
+      (trace! ::trace-id (catch->error! ::error-id ...)).
 
-  - Runtime of async or lazy code in `form` will intentionally NOT be included
-    in resulting signal's `:run-nsecs` value. If you want to measure such
-    runtimes, make sure that your form wraps where the relevant costs are
+    This way you have independent filtering for `run` forms that throw,
+    allowing you to use a higher min level and/or reduced sampling, etc.
+
+    In this case you'll create:
+      0 or 1 `:trace` signals (depending on filtering), AND
+      0 or 1 `:error` signals (depending on filtering).
+
+    Note that the `:error` signal will contain tracing info (e.g. `:parent` key)
+    iff the enclosing `trace!` is allowed.
+
+  - Runtime of async or lazy code in `run` form will intentionally NOT be
+    included in resulting signal's `:run-nsecs` value. If you want to measure
+    such runtimes, make sure that your form wraps where the relevant costs are
     actually realized. Compare:
       (spy!  (delay (my-slow-code))) ; Doesn't measure slow code
       (spy! @(delay (my-slow-code))) ; Does    measure slow code
@@ -1020,9 +1038,9 @@ and       setting `System/err` won't necessarily affect Clojure's `*err*`.
 See also:
   `with-out->telemere`,
   `with-err->telemere`,
-  `with-streams->telemere`.
trace!
macro
clj
cljs
(trace! form)(trace! id form)(trace! {:as opts, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error run & kvs]} form)
"Trace" signal creator, emphasizing form + id.
+  `with-streams->telemere`.
trace!
macro
clj
cljs
(trace! opts-or-run)(trace! id run)(trace! {:as opts-map, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error run & kvs]} run)
"Trace" signal creator, emphasizing (optional id) + form to run.
+ALWAYS (unconditionally) returns run value, or rethrows run error.
 
-API: [form] [id-or-opts form] => form's result (value/throw) (unconditional)
 Default  kind: `:trace`
 Default level: `:info` (intentionally NOT `:trace`!)
 
@@ -1030,14 +1048,14 @@ When filtering conditions are met [4], creates a Telemere signal [3] and
 dispatches it to registered handlers for processing (e.g. writing to
 console/file/queue/db, etc.).
 
-Enables tracing of given `form` arg:
+Enables tracing of given `run` form:
 
   - Resulting signal  will include {:keys [run-form run-val run-nsecs]}.
   - Nested    signals will include this signal's id and uid under `:parent`.
 
 Limitations:
 
-  1. Traced code (`form` arg) is usually expected to be synchronous and eager.
+  1. Traced `run` form is usually expected to be synchronous and eager.
      So no lazy seqs, async calls, or inversion of flow control (IoC) macros like
      core.async `go` blocks, etc.
 
@@ -1059,7 +1077,8 @@ Examples:
   (trace! ::my-id (+ 1 2)) ; %> {... :id ::my-id ...}
   (trace!
     {:let  [x "x"] ; Available to `:data` and `:msg`
-     :data {:x x}}
+     :data {:x x}
+     :msg  ["My message:" x]}
 
     (+ 1 2)) ; %> {... :data {x "x"}, :msg_ "My msg: x" ...}
 
@@ -1068,22 +1087,32 @@ Tips:
   - Test using `with-signal`: (with-signal (trace! ...)).
   - Supports the same options [2] as other signals [1].
 
-  - Identical to `spy!`, but emphasizes form + id rather than form + level.
+  - Like `spy!`, but takes optional id rather than optional level.
 
   - Useful for debugging/monitoring forms, and tracing (nested) execution flow.
-  - Execution of `form` arg may create additional (nested) signals.
+  - Execution of `run` form may create additional (nested) signals.
     Each signal's `:parent` key will indicate its immediate parent.
 
-  - Can be useful to wrap with `catch->error!`:
-      (catch->error! ::error-id (trace! ...)).
+  - It's often useful to wrap `run` form with `catch->error!`:
+      (trace! ::trace-id (catch->error! ::error-id ...)).
+
+    This way you have independent filtering for `run` forms that throw,
+    allowing you to use a higher min level and/or reduced sampling, etc.
+
+    In this case you'll create:
+      0 or 1 `:trace` signals (depending on filtering), AND
+      0 or 1 `:error` signals (depending on filtering).
+
+    Note that the `:error` signal will contain tracing info (e.g. `:parent` key)
+    iff the enclosing `trace!` is allowed.
 
   - Default level is `:info`, not `:trace`! The name "trace" in "trace signal"
     refers to the general action of tracing program flow rather than to the
     common logging level of the same name.
 
-  - Runtime of async or lazy code in `form` will intentionally NOT be included
-    in resulting signal's `:run-nsecs` value. If you want to measure such
-    runtimes, make sure that your form wraps where the relevant costs are
+  - Runtime of async or lazy code in `run` form will intentionally NOT be
+    included in resulting signal's `:run-nsecs` value. If you want to measure
+    such runtimes, make sure that your form wraps where the relevant costs are
     actually realized. Compare:
       (trace!  (delay (my-slow-code))) ; Doesn't measure slow code
       (trace! @(delay (my-slow-code))) ; Does    measure slow code
@@ -1096,7 +1125,7 @@ Tips:
 [1] See `help:signal-creators` - (`signal!`, `log!`, `event!`, ...)
 [2] See `help:signal-options`  - {:keys [kind level id data ...]}
 [3] See `help:signal-content`  - {:keys [kind level id data ...]}
-[4] See `help:signal-filters`  - (by ns/kind/id/level, sampling, etc.)
uncaught->error!
macro
clj
cljs
(uncaught->error!)(uncaught->error! id)(uncaught->error! {:as opts, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]})
Uses `uncaught->handler!` so that `error!` will be called for
+[4] See `help:signal-filters`  - (by ns/kind/id/level, sampling, etc.)
uncaught->error!
macro
clj
cljs
(uncaught->error!)(uncaught->error! opts-or-id)(uncaught->error! {:as opts-map, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]})
Uses `uncaught->handler!` so that `error!` will be called for
 uncaught JVM errors.
 
 See `uncaught->handler!` and `error!` for details.
uncaught->handler!
clj
(uncaught->handler! handler)
Sets JVM's global `DefaultUncaughtExceptionHandler` to given
@@ -1144,8 +1173,12 @@ Options:
     Should delayed `:msg_` in returned signal be retained as-is?
     Delay is otherwise replaced by realized string.
 
-See also `with-signals`.
with-signals
macro
clj
cljs
(with-signals form)(with-signals trap-signals? form)(with-signals raw-msgs? trap-signals? form)
Experimental, subject to change.
-Like `with-signal` but returns [[<form-value> <form-error>] [<signal1> ...]].
-Useful for tests/debugging.
with-streams->telemere
macro
clj
cljs
(with-streams->telemere form)(with-streams->telemere {:keys [out err], :or {out default-out-opts, err default-err-opts}} form)
Executes form with `*out*` and/or `*err*` bound to flush to Telemere signals
+See also `with-signals` for more advanced options.
with-signals
macro
clj
cljs
(with-signals form)(with-signals trap-signals? form)(with-signals raw-msgs? trap-signals? form)
Experimental, subject to change.
+Like `with-signal` but returns {:keys [value error signals]}.
+Useful for more advanced tests/debugging.
+
+Destructuring example:
+  (let [{:keys [value error] [sig1 sig2] :signals} (with-signals ...)]
+    ...)
with-streams->telemere
macro
clj
cljs
(with-streams->telemere form)(with-streams->telemere {:keys [out err], :or {out default-out-opts, err default-err-opts}} form)
Executes form with `*out*` and/or `*err*` bound to flush to Telemere signals
 with given opts.
without-filters
macro
clj
cljs
(without-filters form)
Executes form without any runtime signal filters.
 

\ No newline at end of file
diff --git a/taoensso.telemere.open-telemetry.html b/taoensso.telemere.open-telemetry.html
index f76841a..c6c2578 100644
--- a/taoensso.telemere.open-telemetry.html
+++ b/taoensso.telemere.open-telemetry.html
@@ -1,6 +1,6 @@
 
-taoensso.telemere.open-telemetry documentation
Namespaces
Public Vars
taoensso.telemere.open-telemetry
OpenTelemetry handler using `opentelemetry-java`,
+taoensso.telemere.open-telemetry documentation
Namespaces
Public Vars
taoensso.telemere.open-telemetry
OpenTelemetry handler using `opentelemetry-java`,
 Ref. <https://github.com/open-telemetry/opentelemetry-java>,
      <https://javadoc.io/doc/io.opentelemetry/opentelemetry-api/latest/index.html>
check-interop
clj
(check-interop)
Returns interop debug info map.
 
handler:open-telemetry
clj
(handler:open-telemetry)(handler:open-telemetry {:keys [emit-tracing? logger-provider], :or {emit-tracing? true}})
Highly experimental, possibly buggy, and subject to change!!
diff --git a/taoensso.telemere.postal.html b/taoensso.telemere.postal.html
index 15d6875..a81debf 100644
--- a/taoensso.telemere.postal.html
+++ b/taoensso.telemere.postal.html
@@ -1,7 +1,7 @@
 
-taoensso.telemere.postal documentation
Namespaces
Public Vars
taoensso.telemere.postal
Email handler using `postal`,
-Ref. <https://github.com/drewr/postal>.
default-dispatch-opts
clj
handler:postal
clj
(handler:postal {:keys [conn-opts msg-opts subject-fn body-fn], :or {subject-fn (signal-subject-fn), body-fn (utils/format-signal-fn)}})
Experimental, subject to change.
+taoensso.telemere.postal documentation
Namespaces
Public Vars
taoensso.telemere.postal
Email handler using `postal`,
+Ref. <https://github.com/drewr/postal>.
default-dispatch-opts
clj
handler:postal
clj
(handler:postal {:keys [conn-opts msg-opts subject-fn subject-max-len body-fn], :or {body-fn (utils/format-signal-fn), subject-fn (utils/signal-preamble-fn {:format-inst-fn nil}), subject-max-len 128}})
Experimental, subject to change.
 
 Needs `postal`, Ref. <https://github.com/drewr/postal>.
 
@@ -37,15 +37,13 @@ Options:
        :cc "engineering@example.com"
        :X-MyHeader "A custom header"}
 
-  `:subject-fn` - (fn [signal]) => email subject string
-  `:body-fn`    - (fn [signal]) => email body content string,
-                    see `format-signal-fn` or `pr-signal-fn`
+  `:subject-fn`      - (fn [signal]) => email subject string
+  `:subject-max-len` - Truncate subjects beyond this length (default 90)
+
+  `:body-fn` - (fn [signal]) => email body content string,
+                 see `format-signal-fn` or `pr-signal-fn`
 
 Tips:
   - Ref. <https://github.com/drewr/postal> for more info on `postal` options.
   - Sending emails can be slow, and can incur financial costs!
-    Use appropriate handler dispatch options for async handling and rate limiting, etc.
signal-subject-fn
clj
(signal-subject-fn)(signal-subject-fn {:keys [max-len subject-signal-key], :or {max-len 128, subject-signal-key :postal/subject}})
Experimental, subject to change.
-Returns a (fn format [signal]) that:
-  - Takes a Telemere signal (map).
-  - Returns an email subject string like:
-    "INFO EVENT :taoensso.telemere.postal/ev-id1 - msg"

\ No newline at end of file
+    Use appropriate handler dispatch options for async handling and rate limiting, etc.

\ No newline at end of file
diff --git a/taoensso.telemere.slack.html b/taoensso.telemere.slack.html
index 11d4a13..f4900f3 100644
--- a/taoensso.telemere.slack.html
+++ b/taoensso.telemere.slack.html
@@ -1,6 +1,6 @@
 
-taoensso.telemere.slack documentation
Namespaces
Public Vars
taoensso.telemere.slack
Slack handler using `clj-slack`,
+taoensso.telemere.slack documentation
Namespaces
Public Vars
taoensso.telemere.slack
Slack handler using `clj-slack`,
 Ref. <https://github.com/julienXX/clj-slack>
default-dispatch-opts
clj
handler:slack
clj
(handler:slack {:keys [conn-opts post-opts output-fn], :or {conn-opts {:api-url "https://slack.com/api", :token nil}, post-opts {:channel-id nil, :username nil}, output-fn (utils/format-signal-fn)}})
Experimental, subject to change.
 
 Needs `clj-slack`, Ref. <https://github.com/julienXX/clj-slack>.
diff --git a/taoensso.telemere.sockets.html b/taoensso.telemere.sockets.html
index 6ac7a22..5fea77f 100644
--- a/taoensso.telemere.sockets.html
+++ b/taoensso.telemere.sockets.html
@@ -1,6 +1,6 @@
 
-taoensso.telemere.sockets documentation
Namespaces
Public Vars
taoensso.telemere.sockets
Basic TCP/UDP socket handlers.
+taoensso.telemere.sockets documentation
Namespaces
Public Vars
taoensso.telemere.sockets
Basic TCP/UDP socket handlers.
 
handler:tcp-socket
clj
(handler:tcp-socket {:keys [socket-opts output-fn], :or {output-fn (utils/format-signal-fn)}})
Experimental, subject to change.
 
 Returns a signal handler that:
diff --git a/taoensso.telemere.streams.html b/taoensso.telemere.streams.html
index b61403c..eba2454 100644
--- a/taoensso.telemere.streams.html
+++ b/taoensso.telemere.streams.html
@@ -1,6 +1,6 @@
 
-taoensso.telemere.streams documentation
Namespaces
Public Vars
taoensso.telemere.streams
Interop support for standard stream/s -> Telemere.
+taoensso.telemere.streams documentation
Namespaces
Public Vars
taoensso.telemere.streams
Interop support for standard stream/s -> Telemere.
 
check-err-interop
clj
(check-err-interop)
Returns interop debug info map.
 
check-out-interop
clj
(check-out-interop)
Returns interop debug info map.
 
streams->reset!
clj
(streams->reset!)
Experimental, subject to change.
diff --git a/taoensso.telemere.timbre.cljs.html b/taoensso.telemere.timbre.cljs.html
index 86fa59c..2cd8299 100644
--- a/taoensso.telemere.timbre.cljs.html
+++ b/taoensso.telemere.timbre.cljs.html
@@ -1,6 +1,7 @@
 
-taoensso.telemere.timbre documentation
Namespaces
Public Vars
taoensso.telemere.timbre
Main Timbre macros, reimplemented on top of Telemere.
+taoensso.telemere.timbre documentation
Namespaces
Public Vars
taoensso.telemere.timbre
Main Timbre macros, reimplemented on top of Telemere.
 Intended to help ease migration from Timbre to Telemere.
set-min-level!
clj
cljs
(set-min-level! min-level)
Prefer `telemere/set-min-level!`.
 
shutdown-appenders!
clj
cljs
(shutdown-appenders!)
Prefer `telemere/stop-handlers!`.
+
timbre->telemere-appender
clj
cljs
(timbre->telemere-appender)
Returns a simple Timbre appender that'll redirect logs to Telemere.
 

\ No newline at end of file
diff --git a/taoensso.telemere.timbre.html b/taoensso.telemere.timbre.html
index 6603bb5..ea2d3ac 100644
--- a/taoensso.telemere.timbre.html
+++ b/taoensso.telemere.timbre.html
@@ -1,6 +1,6 @@
 
-taoensso.telemere.timbre documentation
Namespaces
Public Vars
taoensso.telemere.timbre
Main Timbre macros, reimplemented on top of Telemere.
+taoensso.telemere.timbre documentation
Namespaces
Public Vars
taoensso.telemere.timbre
Main Timbre macros, reimplemented on top of Telemere.
 Intended to help ease migration from Timbre to Telemere.
debug
macro
clj
(debug & args)
Prefer `telemere/log!`, etc.
 
debugf
macro
clj
(debugf & args)
Prefer `telemere/log!`, etc.
 
error
macro
clj
(error & args)
Prefer `telemere/log!`, etc.
@@ -24,6 +24,7 @@ Intended to help ease migration from Timbre to Telemere.
set-ns-min-level!
macro
clj
(set-ns-min-level! ?min-level)(set-ns-min-level! ns ?min-level)
Prefer `telemere/set-min-level!`.
 
shutdown-appenders!
clj
cljs
(shutdown-appenders!)
Prefer `telemere/stop-handlers!`.
 
spy!
macro
clj
(spy! form)(spy! level form)(spy! level form-name form)
Prefer `telemere/spy!`.
+
timbre->telemere-appender
clj
cljs
(timbre->telemere-appender)
Returns a simple Timbre appender that'll redirect logs to Telemere.
 
trace
macro
clj
(trace & args)
Prefer `telemere/log!`, etc.
 
tracef
macro
clj
(tracef & args)
Prefer `telemere/log!`, etc.
 
warn
macro
clj
(warn & args)
Prefer `telemere/log!`, etc.
diff --git a/taoensso.telemere.tools-logging.html b/taoensso.telemere.tools-logging.html
index 1439b6f..85f5b19 100644
--- a/taoensso.telemere.tools-logging.html
+++ b/taoensso.telemere.tools-logging.html
@@ -1,6 +1,6 @@
 
-taoensso.telemere.tools-logging documentation
Namespaces
Public Vars
taoensso.telemere.tools-logging
Interop support for tools.logging -> Telemere.
+taoensso.telemere.tools-logging documentation
Namespaces
Public Vars
taoensso.telemere.tools-logging
Interop support for tools.logging -> Telemere.
 Telemere will attempt to load this ns automatically when possible.
 
 Naming conventions:
diff --git a/taoensso.telemere.utils.cljs.html b/taoensso.telemere.utils.cljs.html
index 4a05945..e196a57 100644
--- a/taoensso.telemere.utils.cljs.html
+++ b/taoensso.telemere.utils.cljs.html
@@ -1,6 +1,6 @@
 
-taoensso.telemere.utils documentation
Namespaces
Public Vars
taoensso.telemere.utils
Misc utils useful for Telemere handlers, middleware, etc.
+taoensso.telemere.utils documentation
Namespaces
Public Vars
taoensso.telemere.utils
Misc utils useful for Telemere handlers, middleware, etc.
 
clean-signal-fn
clj
cljs
(clean-signal-fn)(clean-signal-fn {:keys [incl-kvs? incl-nils? incl-keys], :as opts})
Experimental, subject to change.
 Returns a (fn clean [signal]) that:
   - Takes a Telemere  signal (map).
@@ -21,7 +21,8 @@ Returns true iff given signal has an `:error` value, or a `:kind` or `:level`
 that indicates that it's an error.
format-error-fn
clj
cljs
(format-error-fn)(format-error-fn {:as _opts})
Experimental, subject to change.
 Returns a (fn format [error]) that:
   - Takes a platform error (`Throwable` or `js/Error`).
-  - Returns a human-readable error string.
format-inst-fn
clj
cljs
added in Encore v3.98.0 (2024-04-08)
(format-inst-fn)(format-inst-fn {:keys [formatter]})
Experimental, subject to change without notice.
+  - Returns a human-readable error string.
format-id
clj
cljs
(format-id ns x)
`:foo.bar/baz` -> "::baz", etc.
+
format-inst-fn
clj
cljs
added in Encore v3.98.0 (2024-04-08)
(format-inst-fn)(format-inst-fn {:keys [formatter]})
Experimental, subject to change without notice.
 
 Returns a (fn format [instant]) that:
   - Takes a platform instant (`java.time.Instant` or `js/Date`).
@@ -37,7 +38,9 @@ Options:
 
   `:zone` (Clj only) `java.time.ZoneOffset` (defaults to UTC).
    Note that zone may be ignored by some `DateTimeFormatter`s,
-   including the default (`DateTimeFormatter/ISO_INSTANT`)!
format-nsecs-fn
clj
cljs
(format-nsecs-fn)(format-nsecs-fn {:as _opts})
Experimental, subject to change.
+   including the default (`DateTimeFormatter/ISO_INSTANT`)!
format-level
clj
cljs
(format-level x)
`:info` -> "INFO",
+`5` -> "LEVEL:5", etc.
format-location
clj
cljs
(format-location ns line column file)(format-location signal)
Returns "<ns/file>(<line>,<column>)", etc.
+
format-nsecs-fn
clj
cljs
(format-nsecs-fn)(format-nsecs-fn {:as _opts})
Experimental, subject to change.
 Returns a (fn format [nanosecs]) that:
   - Takes a long nanoseconds (e.g. runtime).
   - Returns a human-readable string like:
@@ -98,19 +101,21 @@ See also `format-signal-fn` for an alternative to `pr-signal-fn`
 that produces human-readable output.
signal-content-fn
clj
cljs
(signal-content-fn)(signal-content-fn {:keys [raw-error? incl-keys format-nsecs-fn format-error-fn], :or {format-nsecs-fn (format-nsecs-fn), format-error-fn (format-error-fn)}})
Experimental, subject to change.
 Returns a (fn content [signal]) that:
   - Takes a Telemere signal (map).
-  - Returns a signal content ?string (incl. data, ctx, etc.).
+  - Returns a human-readable signal content ?string (incl. data, ctx, etc.).
 
 Options:
   `:raw-error?`      - Retain unformatted error? (default false)
   `:incl-keys`       - Subset of signal keys to retain from those
                        otherwise excluded by default: #{:kvs :host :thread}
   `:format-nsecs-fn` - (fn [nanosecs]) => string.
-  `:format-error-fn` - (fn [error])    => string.
signal-preamble-fn
clj
cljs
(signal-preamble-fn)(signal-preamble-fn {:keys [format-inst-fn], :or {format-inst-fn (format-inst-fn)}})
Experimental, subject to change.
+  `:format-error-fn` - (fn [error])    => string.
signal-preamble-fn
clj
cljs
(signal-preamble-fn)(signal-preamble-fn {:keys [format-inst-fn format-id-fn format-msg-fn], :or {format-inst-fn (format-inst-fn), format-id-fn format-id, format-msg-fn identity}})
Experimental, subject to change.
 Returns a (fn preamble [signal]) that:
   - Takes a Telemere signal (map).
   - Returns a signal preamble ?string like:
-    "2024-03-26T11:14:51.806Z INFO EVENT Hostname taoensso.telemere(2,21) ::ev-id - msg"
+    "2024-03-26T11:14:51.806Z INFO EVENT Hostname taoensso.telemere(2,21) ::ev-id msg"
 
 Options:
-  `:format-inst-fn` - (fn format [instant]) => string.
uuid-str
clj
cljs
(uuid-str max-len)(uuid-str)
Returns a random UUID string of given length (max 36).
+  `:format-inst-fn` - (fn format [instant]) => string.
+  `:format-id-fn`   - (fn format [ns id])   => string.
+  `:format-msg-fn`  - (fn format [msg])     => string.
uuid-str
clj
cljs
(uuid-str max-len)(uuid-str)
Returns a random UUID string of given length (max 36).
 Uses strong randomness when possible. See also `uuid`, `nanoid`, `rand-id-fn`.

\ No newline at end of file
diff --git a/taoensso.telemere.utils.html b/taoensso.telemere.utils.html
index e5dfc83..3de41e2 100644
--- a/taoensso.telemere.utils.html
+++ b/taoensso.telemere.utils.html
@@ -1,6 +1,6 @@
 
-taoensso.telemere.utils documentation
Namespaces
Public Vars
taoensso.telemere.utils
Misc utils useful for Telemere handlers, middleware, etc.
+taoensso.telemere.utils documentation
Namespaces
Public Vars
taoensso.telemere.utils
Misc utils useful for Telemere handlers, middleware, etc.
 
clean-signal-fn
clj
cljs
(clean-signal-fn)(clean-signal-fn {:keys [incl-kvs? incl-nils? incl-keys], :as opts})
Experimental, subject to change.
 Returns a (fn clean [signal]) that:
   - Takes a Telemere  signal (map).
@@ -32,7 +32,8 @@ Notes:
   - Thread safe, locks on single file stream.
format-error-fn
clj
cljs
(format-error-fn)(format-error-fn {:as _opts})
Experimental, subject to change.
 Returns a (fn format [error]) that:
   - Takes a platform error (`Throwable` or `js/Error`).
-  - Returns a human-readable error string.
format-inst-fn
clj
cljs
added in Encore v3.98.0 (2024-04-08)
(format-inst-fn)(format-inst-fn {:keys [formatter zone], :or {formatter java.time.format.DateTimeFormatter/ISO_INSTANT, zone java.time.ZoneOffset/UTC}})
Experimental, subject to change without notice.
+  - Returns a human-readable error string.
format-id
clj
cljs
(format-id ns x)
`:foo.bar/baz` -> "::baz", etc.
+
format-inst-fn
clj
cljs
added in Encore v3.98.0 (2024-04-08)
(format-inst-fn)(format-inst-fn {:keys [formatter zone], :or {formatter java.time.format.DateTimeFormatter/ISO_INSTANT, zone java.time.ZoneOffset/UTC}})
Experimental, subject to change without notice.
 
 Returns a (fn format [instant]) that:
   - Takes a platform instant (`java.time.Instant` or `js/Date`).
@@ -48,7 +49,9 @@ Options:
 
   `:zone` (Clj only) `java.time.ZoneOffset` (defaults to UTC).
    Note that zone may be ignored by some `DateTimeFormatter`s,
-   including the default (`DateTimeFormatter/ISO_INSTANT`)!
format-nsecs-fn
clj
cljs
(format-nsecs-fn)(format-nsecs-fn {:as _opts})
Experimental, subject to change.
+   including the default (`DateTimeFormatter/ISO_INSTANT`)!
format-level
clj
cljs
(format-level x)
`:info` -> "INFO",
+`5` -> "LEVEL:5", etc.
format-location
clj
cljs
(format-location ns line column file)(format-location signal)
Returns "<ns/file>(<line>,<column>)", etc.
+
format-nsecs-fn
clj
cljs
(format-nsecs-fn)(format-nsecs-fn {:as _opts})
Experimental, subject to change.
 Returns a (fn format [nanosecs]) that:
   - Takes a long nanoseconds (e.g. runtime).
   - Returns a human-readable string like:
@@ -109,21 +112,23 @@ See also `format-signal-fn` for an alternative to `pr-signal-fn`
 that produces human-readable output.
signal-content-fn
clj
cljs
(signal-content-fn)(signal-content-fn {:keys [raw-error? incl-keys format-nsecs-fn format-error-fn], :or {format-nsecs-fn (format-nsecs-fn), format-error-fn (format-error-fn)}})
Experimental, subject to change.
 Returns a (fn content [signal]) that:
   - Takes a Telemere signal (map).
-  - Returns a signal content ?string (incl. data, ctx, etc.).
+  - Returns a human-readable signal content ?string (incl. data, ctx, etc.).
 
 Options:
   `:raw-error?`      - Retain unformatted error? (default false)
   `:incl-keys`       - Subset of signal keys to retain from those
                        otherwise excluded by default: #{:kvs :host :thread}
   `:format-nsecs-fn` - (fn [nanosecs]) => string.
-  `:format-error-fn` - (fn [error])    => string.
signal-preamble-fn
clj
cljs
(signal-preamble-fn)(signal-preamble-fn {:keys [format-inst-fn], :or {format-inst-fn (format-inst-fn)}})
Experimental, subject to change.
+  `:format-error-fn` - (fn [error])    => string.
signal-preamble-fn
clj
cljs
(signal-preamble-fn)(signal-preamble-fn {:keys [format-inst-fn format-id-fn format-msg-fn], :or {format-inst-fn (format-inst-fn), format-id-fn format-id, format-msg-fn identity}})
Experimental, subject to change.
 Returns a (fn preamble [signal]) that:
   - Takes a Telemere signal (map).
   - Returns a signal preamble ?string like:
-    "2024-03-26T11:14:51.806Z INFO EVENT Hostname taoensso.telemere(2,21) ::ev-id - msg"
+    "2024-03-26T11:14:51.806Z INFO EVENT Hostname taoensso.telemere(2,21) ::ev-id msg"
 
 Options:
-  `:format-inst-fn` - (fn format [instant]) => string.
tcp-socket-writer
clj
(tcp-socket-writer {:keys [host port ssl? connect-timeout-msecs socket-fn ssl-socket-fn], :as opts, :or {connect-timeout-msecs 3000, socket-fn default-socket-fn, ssl-socket-fn default-ssl-socket-fn}})
Experimental, subject to change.
+  `:format-inst-fn` - (fn format [instant]) => string.
+  `:format-id-fn`   - (fn format [ns id])   => string.
+  `:format-msg-fn`  - (fn format [msg])     => string.
tcp-socket-writer
clj
(tcp-socket-writer {:keys [host port ssl? connect-timeout-msecs socket-fn ssl-socket-fn], :as opts, :or {connect-timeout-msecs 3000, socket-fn default-socket-fn, ssl-socket-fn default-ssl-socket-fn}})
Experimental, subject to change.
 Connects to specified TCP socket and returns a stateful fn of 2 arities:
   [content] => Writes given content to socket, or noops if closed.
   []        => Closes the writer.