\ 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
\ 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
\ 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
Structured telemetry for Clojure/Script applications.
See the GitHub page (esp. Wiki) for info on motivation and design:
<https://www.taoensso.com/telemere>
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! 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.)
(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.)
(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! 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.)
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`
(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.
(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? & 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! 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! 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! 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.)
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`.
\ 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
Structured telemetry for Clojure/Script applications.
See the GitHub page (esp. Wiki) for info on motivation and design:
<https://www.taoensso.com/telemere>
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.
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?`.
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! 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.)
(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.)
(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! 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.)
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`
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.
(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? & 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! 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! 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! 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!)(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`.
\ 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
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
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
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
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.
Experimental, subject to change.
Returns a (fn format [error]) that:
- Takes a platform error (`Throwable` or `js/Error`).
- - Returns a human-readable error string.
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`)!
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.
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.
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
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.
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)(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`)!
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.
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.