\ No newline at end of file
diff --git a/index.cljs.html b/index.cljs.html
index e1c7ab3..3b2e4d9 100644
--- a/index.cljs.html
+++ b/index.cljs.html
@@ -1,3 +1,3 @@
-Telemere 1.0.0-SNAPSHOT
\ No newline at end of file
diff --git a/taoensso.telemere.cljs.html b/taoensso.telemere.cljs.html
index 01536ed..195e1b9 100644
--- a/taoensso.telemere.cljs.html
+++ b/taoensso.telemere.cljs.html
@@ -1,9 +1,9 @@
-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>
Dynamic context: arbitrary user-level state attached as `:ctx` to all signals.
Value may be any type, but is usually nil or a map.
Re/bind dynamic value using `with-ctx`, `with-ctx+`, or `binding`.
@@ -27,6 +27,7 @@ Modify root (base) value using `set-middleware!`.
Advanced feature. Default root (base) value of `*ctx*` var, controlled by:
(get-env {:as :edn} :taoensso.telemere/default-ctx<.platform><.edn>)
-See `get-env` for details.
Your filter config determines which signal calls will be allowed.
Filtering can occur at compile-time (=> elision), or runtime.
Both compile-time and runtime config can be specified via:
@@ -116,6 +124,7 @@ Both compile-time and runtime config can be specified via:
classpath resources). See library docs for details.
2. The filter API consting of the following:
+
`set-ns-filter!`, `with-ns-filter` - for filtering calls by namespace
`set-minimum-level!`, `with-minimum-level!` - for filtering calls by signal level
`set-id-filter!`, `with-id-filter` - for filtering calls by signal id (when relevant)
@@ -127,17 +136,14 @@ Additional filtering can also be applied on a per-handler basis, see
`add-handler!` for details.
See also:
+
`get-filters` - to see current filter config
`get-min-level` - to see current minimum level
`without-filters` - to disable all runtime filtering
If anything is unclear, please ping me (@ptaoussanis) so that I can
-improve these docs!
The handler API consists of the following:
+
`get-handlers` - Returns info on currently registered handlers
`add-handler!` - Used to register handlers
`remove-handler!` - Used to unregister handlers
@@ -148,20 +154,20 @@ If anything is unclear, please ping me (@ptaoussanis) so that I can
improve these docs!
Sets signal call id filter based on given `id-filter` spec.
-
`id-filter` may be:
+
- A regex pattern of id/s to allow.
- A str/kw/sym, in which "*"s act as wildcards.
- A vector or set of regex patterns or strs/kws/syms.
- {:allow <spec> :deny <spec>} with specs as above.
Sets signal call kind filter based on given `kind-filter` spec.
-
`kind-filter` may be:
+
- A regex pattern of kind/s to allow.
- A str/kw/sym, in which "*"s act as wildcards.
- A vector or set of regex patterns or strs/kws/syms.
- {:allow <spec> :deny <spec>} with specs as above.
Sets minimum signal call level based on given `min-level` spec.
-
`min-level` may be:
+
- An integer.
- A level keyword (see `level-aliases` var for details).
@@ -171,8 +177,8 @@ See `set-ns-filter!` for details.
If non-nil `kind` is provided, then the given minimum level
will apply only for that signal kind.
Sets signal call namespace filter based on given `ns-filter` spec.
-
`ns-filter` may be:
+
- A regex pattern of namespace/s to allow.
- A str/kw/sym, in which "*"s act as wildcards.
- A vector or set of regex patterns or strs/kws/syms.
diff --git a/taoensso.telemere.html b/taoensso.telemere.html
index 3a2fed2..0ec85f7 100644
--- a/taoensso.telemere.html
+++ b/taoensso.telemere.html
@@ -1,9 +1,9 @@
-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>
Dynamic context: arbitrary user-level state attached as `:ctx` to all signals.
Value may be any type, but is usually nil or a map.
Re/bind dynamic value using `with-ctx`, `with-ctx+`, or `binding`.
@@ -27,6 +27,7 @@ Modify root (base) value using `set-middleware!`.
catch->error!
macro
clj
(catch->error! form)(catch->error! level form)(catch->error! {:as opts, :keys [rethrow? catch-val elidable? location instant uid middleware sample-rate ns kind id level filter when rate-limit ctx parent trace? let data msg error & user-opts]} form)
TODO Docstring [form] [id-or-opts form] => run value or ?catch-val
-
Returns true with given probability ∈ ℝ[0,1].
+ otherwise calls will be suppressed before reaching handlers.
catch->error!
macro
clj
(catch->error! form)(catch->error! id form)(catch->error! {:as opts, :keys [rethrow? catch-val elidable? location instant uid middleware sample-rate ns kind id level when rate-limit ctx parent trace? do let data msg error & user-opts]} 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 [1],
+ 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! {:id ::my-id, :catch-val "threw"} (/ 1 0)) ; %> {... :id ::my-id ...}
+ (catch->error!
+ {:let [x "x"] ; Available to `:data` and `:msg`
+ :data {:x x}
+ :msg_ ["My msg:" x]}
+ (/ 1 0)) ; %> {... :data {x "x"}, :msg_ "My msg: x" ...}
+
+Tips:
+
+ - Test using `with-signals`: (with-signals (catch->error! ...)).
+ - Supports the same options as other signals [1].
+
+ - Useful for recording errors in forms, futures, callbacks, etc.
+
+See also `error!`.
+
+[1] See `help:signal-options` docstring
Advanced feature. Default root (base) value of `*ctx*` var, controlled by:
(get-env {:as :edn} :taoensso.telemere/default-ctx<.platform><.edn>)
-See `get-env` for details.
error!
macro
clj
(error! error)(error! id error)(error! {:as opts, :keys [elidable? location instant uid middleware sample-rate ns kind id level filter when rate-limit ctx parent trace? let data msg error & user-opts]} error)
Your filter config determines which signal calls will be enabled.
+See `get-env` for details.
error!
macro
clj
(error! error)(error! id error)(error! {:as opts, :keys [elidable? location instant uid middleware sample-rate ns kind id level when rate-limit ctx parent trace? do let data msg error & user-opts]} error)
"Error" signal call, focused on error + id.
-Filtering can occur at compile-time (=> elision), or runtime.
-Both compile-time and runtime config can be specified via:
+API: [error] [id-or-opts error] => given error (unconditional)
+Default kind: `:error`
+Default level: `:error`
- 1. System values (JVM properties, environment variables, or
- classpath resources). See library docs for details.
+Examples:
- 2. The filter API consting of the following:
- `set-ns-filter!`, `with-ns-filter` - for filtering calls by namespace
- `set-minimum-level!`, `with-minimum-level!` - for filtering calls by signal level
- `set-id-filter!`, `with-id-filter` - for filtering calls by signal id (when relevant)
- `set-kind-filter!`, `with-kind-filter` - for filtering calls by signal kind (when relevant)
+ (throw (error! (ex-info "MyEx" {}))) ; %> {:kind :error, :level :error, :error <MyEx> ...}
+ (throw (error! ::my-id (ex-info "MyEx" {}))) ; %> {... :id ::my-id ...}
+ (throw
+ (error!
+ {:let [x "x"] ; Available to `:data` and `:msg`
+ :data {:x x}
+ :msg ["My message:" x]}
- See the relevant docstrings for details.
+ (ex-info "MyEx" {}))) ; %> {... :data {x "x"}, :msg_ "My msg: x" ...}
-Additional filtering can also be applied on a per-handler basis, see
-`add-handler!` for details.
+Tips:
-See also:
- `get-filters` - to see current filter config
- `get-min-level` - to see current minimum level
- `without-filters` - to disable all runtime filtering
+ - Test using `with-signals`: (with-signals (error! ...)).
+ - Supports the same options as other signals [3].
-If anything is unclear, please ping me (@ptaoussanis) so that I can
-improve these docs!
TODO Docstring
+ - `error` arg is a platform error (`java.lang.Throwable` or `js/Error`).
+ - Can conveniently be wrapped by `throw`: (throw (error! ...)).
+
+[1] See `help:signal-handling` docstring
+[2] See `help:signal-content` docstring
+[3] See `help:signal-options` docstring
event!
macro
clj
(event! id)(event! id level)(event! id {:as opts, :keys [elidable? location instant uid middleware sample-rate ns kind id level when rate-limit ctx parent trace? do let data msg error & user-opts]})
"Event" signal call, focused on id + level.
+
+API: [id] [id level-or-opts] => true iff signal call was allowed
+Default kind: `:event`
+Default level: `:info`
+
+When conditions are met [1], creates a Telemere signal [2] and dispatches it to
+registered handlers for processing (writing to console/disk/db, etc.).
+
+Examples:
+
+ (event! ::my-id) ; %> {:kind :event, :level :info, :id ::my-id ...}
+ (event! ::my-id :warn) ; %> {... :level :warn ...}
+ (event! ::my-id
+ {:let [x "x"] ; Available to `:data` and `:msg`
+ :data {:x x}
+ :msg ["My msg:" x]}) ; %> {... :data {x "x"}, :msg_ "My msg: x" ...}
+
+Tips:
+
+ - Test using `with-signals`: (with-signals (error! ...)).
+ - Supports the same options as other signals [3].
+
+ - A good general-purpose signal, prefer to `log!` by default, since it
+ better encourages structured data over unstructured messages.
+
+ - Has a different 2-arity arg order to all other signals!
+ Mnemonic: the arg that's typically larger is *always* in the rightmost
+ position, and for `event!` that's the `level-or-opts` arg.
+
+----------------------------------------
+[1] See `help:signal-handling` docstring
+[2] See `help:signal-content` docstring
+[3] See `help:signal-options` docstring
Cross-platform util for embedding flexible environmental config during
macro expansion. Used by other Taoensso libraries.
@@ -195,7 +260,35 @@ Result must be something that can be safely embedded in code during
macro-expansion. Symbols in edn will be evaluated during expansion.
Your filter config determines which signal calls will be allowed.
+
+Filtering can occur at compile-time (=> elision), or runtime.
+Both compile-time and runtime config can be specified via:
+
+ 1. System values (JVM properties, environment variables, or
+ classpath resources). See library docs for details.
+
+ 2. The filter API consting of the following:
+
+ `set-ns-filter!`, `with-ns-filter` - for filtering calls by namespace
+ `set-minimum-level!`, `with-minimum-level!` - for filtering calls by signal level
+ `set-id-filter!`, `with-id-filter` - for filtering calls by signal id (when relevant)
+ `set-kind-filter!`, `with-kind-filter` - for filtering calls by signal kind (when relevant)
+
+ See the relevant docstrings for details.
+
+Additional filtering can also be applied on a per-handler basis, see
+`add-handler!` for details.
+
+See also:
+
+ `get-filters` - to see current filter config
+ `get-min-level` - to see current minimum level
+ `without-filters` - to disable all runtime filtering
+
+If anything is unclear, please ping me (@ptaoussanis) so that I can
+improve these docs!
The handler API consists of the following:
+
`get-handlers` - Returns info on currently registered handlers
`add-handler!` - Used to register handlers
`remove-handler!` - Used to unregister handlers
@@ -203,12 +296,139 @@ registered signal handlers.
hostname
clj
(hostname)(hostname timeout-msecs timeout-val)
Returns local cached hostname string, or `timeout-val` (default "UnknownHost").
+improve these docs!
help:signal-content
clj
Signals are initially maps with {:keys [instant id ns level data msg_ ...]},
+though they can be modified by call and/or handler middleware.
+
+Default keys:
+
+`:schema-version` - Int version of signal schema (current: 1)
+
+`:instant` - Platform instant [1] when signal was created
+`:level` - Signal level ∈ #{<int> :trace :debug :info :warn :error :fatal :report ...}
+`:kind` - Signal ?kind ∈ #{nil :event :error :log :trace :spy <user-val> ...}
+`:id` - ?id of signal call (common to all signals created by signal call, contrast with `:uid`)
+`:uid` - ?id of signal instance (unique to each signal created by signal call, contrast with `:id`)
+
+`:data` - Arb user-level data ?val (usu. a map) given to signal call
+`:msg` - Arb user-level message ?str given to signal call
+`:error` - Arb user-level platform ?error [2] given to signal call
+
+`:run-form` - Unevaluated ?form given to signal macro as `:run`
+`:run-value` - Successful return ?val of `:run` ?form
+`:end-instant` - Platform ?instant [1] when `:run` ?form completed
+`:runtime-nsecs`- ?int nanosecs runtime of `:run` ?form
+
+`:ctx` - ?val of `*ctx*` (arb user-level state) when signal was created
+`:parent` - ?{:keys [id uid]} of parent signal, present in nested signals when tracing
+`:location` - ?{:keys [ns file line column]} signal call location
+`:ns` - ?str namespace of signal call, same as (:ns location)
+`:file` - ?str filename of signal call, same as (:file location)
+`:line` - ?int line of signal call, same as (:line location)
+`:column` - ?int column of signal call, same as (:column location)
+
+`:sample-rate` - ?rate ∈ℝ[0,1] for combined call AND handler sampling (0.75 => allow 75% of signals, nil => allow all)
+
+If anything is unclear, please ping me (@ptaoussanis) so that I can improve these docs!
+
+[1] Clj: `java.time.Instant`, Cljs: `js/Date`
+[2] Clj: `java.lang.Throwable`, Cljs: `js/Error`
help:signal-handling
clj
A signal will be provided to a handler iff ALL of the following are true:
+
+ 1. Signal call is allowed by compile-time filters
+ 2. Signal call is allowed by runtime filters
+ 3. Handler is allowed by runtime filters
+
+ 4. Signal call middleware does not suppress the signal (return nil)
+ 5. Handler middleware does not suppress the signal (return nil)
+
+For more info:
+
+ - On call filters, see: `help:filters` docstring
+ - On handler filters, see: `help:handlers` docstring
+ - On signal flow, see: Ref. <https://tinyurl.com/telemere-signal-flowchart>
+
+If anything is unclear, please ping me (@ptaoussanis) so that I can
+improve these docs!
help:signal-options
clj
Signal options (shared by `signal!`, `event!`, ...):
+
+`:instant` - Platform instant [1] when signal was created, ∈ #{nil :auto <user-val>}
+`:level` - Signal level ∈ #{<int> :trace :debug :info :warn :error :fatal :report ...}
+`:kind` - Signal ?kind ∈ #{nil :event :error :log :trace :spy <user-val> ...}
+`:id` - ?id of signal call (common to all signals created by signal call, contrast with `:uid`)
+`:uid` - ?id of signal instance (unique to each signal created by signal call, contrast with `:id`)
+
+`:data` - Arb user-level ?data to incl. in signal: usu. a map
+`:msg` - Arb user-level ?message to incl. in signal: str or vec of strs to join (with `\space`)
+`:error` - Arb user-level ?error to incl. in signal: platform error [2]
+
+`:run` - ?form to execute UNCONDITIONALLY; will incl. `:run-value` in signal
+`:do` - ?form to execute conditionally (iff signal allowed), before establishing `:let` ?binding
+`:let` - ?binding to establish conditionally (iff signal allowed), BEFORE evaluating `:data` and `:msg` (useful!)
+
+`:ctx` - Custom ?val to override auto (dynamic `*ctx*`) in signal
+`:parent` - Custom ?{:keys [id uid]} to override auto (dynamic) parent signal info in signal
+`:location` - Custom ?{:keys [ns line column file]} to override auto signal call location
+
+`:elidable?` - Should signal call be subject to compile-time elision? (Default: true)
+`:sample-rate` - ?rate ∈ℝ[0,1] for call sampling (0.75 => allow 75% of signals, nil => allow all)
+`:when` - Arb ?form; when present, form must return truthy to allow signal
+`:rate-limit` - ?spec as given to `telemere/rate-limiter`, see its docstring for details
+`:middleware` - ?[(fn [signal])=>modified-signal ...] call middleware
+`:trace?` - Should tracing be enabled for `:run` form?
+
+<user-opts> - Arb user-level ?kvs to incl. in signal
+
+If anything is unclear, please ping me (@ptaoussanis) so that I can improve these docs!
+
+[1] Clj: `java.time.Instant`, Cljs: `js/Date`
+[2] Clj: `java.lang.Throwable`, Cljs: `js/Error`
hostname
clj
(hostname)(hostname timeout-msecs timeout-val)
Returns local cached hostname string, or `timeout-val` (default "UnknownHost").
(log! msg)(log! level msg)(log! {:as opts, :keys [elidable? location instant uid middleware sample-rate ns kind id level when rate-limit ctx parent trace? do let data msg error & user-opts]} msg)
"Log" signal call, focused on message + level.
+
+API: [msg] [level-or-opts msg] => true iff signal call was allowed.
+Default kind: `:log`
+Default level: `:info`
+
+When conditions are met [1], creates a Telemere signal [2] and dispatches it to
+registered handlers for processing (writing to console/disk/db, etc.).
+
+Examples:
+
+ (log! "My msg") ; %> {:kind :log, :level :info, :id ::my-id ...}
+ (log! :warn "My msg") ; %> {... :level :warn ...}
+ (log!
+ {:let [x "x"] ; Available to `:data` and `:msg`
+ :data {:x x}}
+
+ ["My msg:" x]) ; %> {... :data {x "x"}, :msg_ "My msg: x" ...}
+
+Tips:
+
+ - Test using `with-signals`: (with-signals (log! ...)).
+ - Supports the same options as other signals [3].
+
+ - Prefer `event!` to `log!` by default, since it better encourages structured
+ data over unstructured messages.
+
+ - `msg` arg may be a string, or vector of strings to join with `\space`.
+ - See also `msg-splice`, `msg-skip` utils.
+
+----------------------------------------
+[1] See `help:signal-handling` docstring
+[2] See `help:signal-content` docstring
+[3] See `help:signal-options` docstring
For use within signal message vectors.
+Special value that will be ignored (no-op) when creating message.
+Useful for conditionally skipping parts of message content, etc.:
+
+ (signal! {:msg ["Hello" (if <cond> <then> msg-skip) "world"] <...>}) or
+ (log! ["Hello" (if <cond> <then> msg-skip) "world"]), etc.
+
+ %> {:msg_ "Hello world" <...>}
For use within signal message vectors.
+Wraps given arguments so that they're spliced when creating message.
+Useful for conditionally splicing in extra message content, etc.:
+
+ (signal! {:msg [(when <cond> (msg-splice ["Username:" "Steve"])) <...>]}) or
+ (log! [(when <cond> (msg-splice ["Username:" "Steve"]))])
+
+ %> {:msg_ "Username: Steve"}
Takes a map spec of form {<limit-id> [<n-max-reqs> <msecs-window>]},
and returns a basic stateful (fn rate-limiter [req-id] [command req-id]).
@@ -236,21 +456,21 @@ Example:
?{<handler-id> {:keys [dispatch-opts handler-fn]}} for all signal handlers
still registered.
set-ctx!
macro
clj
(set-ctx! root-val)
Set `*ctx*` var's root (base) value. See `*ctx*` for details.
Sets signal call id filter based on given `id-filter` spec.
-
`id-filter` may be:
+
- A regex pattern of id/s to allow.
- A str/kw/sym, in which "*"s act as wildcards.
- A vector or set of regex patterns or strs/kws/syms.
- {:allow <spec> :deny <spec>} with specs as above.
Sets signal call kind filter based on given `kind-filter` spec.
-
`kind-filter` may be:
+
- A regex pattern of kind/s to allow.
- A str/kw/sym, in which "*"s act as wildcards.
- A vector or set of regex patterns or strs/kws/syms.
- {:allow <spec> :deny <spec>} with specs as above.
set-middleware!
macro
clj
(set-middleware! root-val)
Set `*middleware*` var's root (base) value. See `*middleware*` for details.
Sets minimum signal call level based on given `min-level` spec.
-
`min-level` may be:
+
- An integer.
- A level keyword (see `level-aliases` var for details).
@@ -260,26 +480,82 @@ See `set-ns-filter!` for details.
If non-nil `kind` is provided, then the given minimum level
will apply only for that signal kind.
Sets signal call namespace filter based on given `ns-filter` spec.
-
`ns-filter` may be:
+
- A regex pattern of namespace/s to allow.
- A str/kw/sym, in which "*"s act as wildcards.
- A vector or set of regex patterns or strs/kws/syms.
- {:allow <spec> :deny <spec>} with specs as above.
set-var-root!
macro
clj
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
(signal! {:as opts, :keys [elidable? location instant uid middleware sample-rate ns kind id level filter when rate-limit ctx parent trace? let data msg error run & user-opts]})
Expands to a low-level signal call.
+the new value. Cross-platform. See also `update-var-root!`.
signal!
macro
clj
(signal! {:as opts, :keys [elidable? location instant uid middleware sample-rate ns kind id level when rate-limit ctx parent trace? do let data msg error run & user-opts]})
Low-level generic signal call.
-TODO Docstring
- - How low-level is this? Should location, ctx, etc. be in public arglists?
- - Describe
- - Reference diagram link [1]
- - Mention ability to delay-wrap :data
- - Mention combo `:sample-rate` stuff (call * handler)
+API: [opts] => depends on options [3]
+Default kind: none (optional)
+Default level: none (must be provided)
-- If :run => returns body run-result (re-throwing)
- Otherwise returns true iff call allowed
+When conditions are met [1], creates a Telemere signal [2] and dispatches it to
+registered handlers for processing (writing to console/disk/db, etc.).
-[1] Ref. <https://github.com/taoensso/telemere/blob/master/signal-flow.svg>
spy!
macro
clj
(spy! form)(spy! id form)(spy! {:as opts, :keys [elidable? location instant uid middleware sample-rate ns kind id level filter when rate-limit ctx parent trace? let data msg error run & user-opts]} form)
TODO Docstring [form] [level-or-opts form] => run result (value or throw)
-
streams->reset!
clj
(streams->reset!)
Experimental, subject to change without notice!
+If `:run` option is provided: returns value of given run form, or throws.
+ Otherwise: returns true iff call conditions were met.
+
+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 provided wrapper macros optimized for ease-of-use in
+common cases.
+
+These all use `signal!` underneath and offer the same options, but vary in
+their defaults and the focus of their call APIs (args and return values):
+
+ `event!` - (id + opts/level) => true iff signal call was allowed
+ `log!` - (message + opts/level) => true iff signal call was allowed
+ `error!` - (error + opts/id) => given error (unconditional)
+ `trace!` - (form + opts/id) => form's result (value/throw) (unconditional)
+ `spy!` - (form + opts/level) => form's result (value/throw) (unconditional)
+
+Tips:
+
+ - Test using `with-signals`: (with-signals (signal! ...)).
+ - Supports the same options as other signals [3].
+
+----------------------------------------
+[1] See `help:signal-handling` docstring
+[2] See `help:signal-content` docstring
+[3] See `help:signal-options` docstring
spy!
macro
clj
(spy! form)(spy! id form)(spy! {:as opts, :keys [elidable? location instant uid middleware sample-rate ns kind id level when rate-limit ctx parent trace? do let data msg error run & user-opts]} form)
"Spy" signal call, focused on form + level.
+
+API: [form] [level-or-opts form] => form's result (value/throw) (unconditional)
+Default kind: `:spy`
+Default level: `:info`
+
+When conditions are met [1], creates a Telemere signal [2] and dispatches it to
+registered handlers for processing (writing to console/disk/db, etc.).
+
+Examples:
+
+ (spy! (+ 1 2)) ; %> {:kind :trace, :level :info, :run-form '(+ 1 2),
+ ; :run-value 3, :parent {:keys [id uid]}
+ ; :msg "(+ 1 2) => 3" ...}
+ (spy! ::my-id (+ 1 2)) ; %> {... :id ::my-id ...}
+ (spy!
+ {:let [x "x"] ; Available to `:data` and `:msg`
+ :data {:x x}}
+
+ (+ 1 2)) ; %> {... :data {x "x"}, :msg_ "My msg: x" ...}
+
+Tips:
+
+ - Test using `with-signals`: (with-signals (spy! ...)).
+ - Supports the same options as other signals [3].
+
+ - Identical to `trace!`, but focused on form + level rather than form + id.
+
+ - Useful for debugging/monitoring forms, and tracing (nested) execution flow.
+ - Execution of `form` arg may trigger additional (nested) signals.
+ Each signal's `:parent` key will indicate its immediate parent.
+
+----------------------------------------
+[1] See `help:signal-handling` docstring
+[2] See `help:signal-content` docstring
+[3] See `help:signal-options` docstring
streams->reset!
clj
(streams->reset!)
Experimental, subject to change without notice!
Resets `System/out` and `System/err` to their original value (prior to any
`streams->telemere!` call).
Experimental, subject to change without notice!
@@ -293,10 +569,51 @@ See also:
`with-out->telemere`,
`with-err->telemere`,
`with-streams->telemere`.
thread-id
clj
(thread-id)
thread-name
clj
(thread-name)
tools-logging->telemere!
clj
(tools-logging->telemere!)
Configures `clojure.tools.logging` to use Telemere as its logging implementation.
-
trace!
macro
clj
(trace! form)(trace! id form)(trace! {:as opts, :keys [elidable? location instant uid middleware sample-rate ns kind id level filter when rate-limit ctx parent trace? let data msg error run & user-opts]} form)
TODO Docstring [form] [id-or-opts form] => run result (value or throw)
-
uncaught->error!
macro
clj
(uncaught->error!)(uncaught->error! id)(uncaught->error! {:as opts, :keys [elidable? location instant uid middleware sample-rate ns kind id level filter when rate-limit ctx parent trace? let data msg error & user-opts]})
TODO Docstring
-See also `uncaught->handler!`.
uncaught->handler!
clj
(uncaught->handler! handler)
Sets JVM's global `DefaultUncaughtExceptionHandler` to given
+
trace!
macro
clj
(trace! form)(trace! id form)(trace! {:as opts, :keys [elidable? location instant uid middleware sample-rate ns kind id level when rate-limit ctx parent trace? do let data msg error run & user-opts]} form)
"Trace" signal call, focused on form + id.
+
+API: [form] [id-or-opts form] => form's result (value/throw) (unconditional)
+Default kind: `:trace`
+Default level: `:info` (intentionally NOT `:trace`!)
+
+When conditions are met [1], creates a Telemere signal [2] and dispatches it to
+registered handlers for processing (writing to console/disk/db, etc.).
+
+Examples:
+
+ (trace! (+ 1 2)) ; %> {:kind :trace, :level :info, :run-form '(+ 1 2),
+ ; :run-value 3, :parent {:keys [id uid]} ...
+ ; :msg "(+ 1 2) => 3" ...}
+ (trace! ::my-id (+ 1 2)) ; %> {... :id ::my-id ...}
+ (trace!
+ {:let [x "x"] ; Available to `:data` and `:msg`
+ :data {:x x}}
+
+ (+ 1 2)) ; %> {... :data {x "x"}, :msg_ "My msg: x" ...}
+
+Tips:
+
+ - Test using `with-signals`: (with-signals (trace! ...)).
+ - Supports the same options as other signals [3].
+
+ - Identical to `spy!`, but focused on form + id rather than form + level.
+
+ - Useful for debugging/monitoring forms, and tracing (nested) execution flow.
+ - Execution of `form` arg may trigger additional (nested) signals.
+ Each signal's `:parent` key will indicate its immediate parent.
+
+ - 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.
+
+----------------------------------------
+[1] See `help:signal-handling` docstring
+[2] See `help:signal-content` docstring
+[3] See `help:signal-options` docstring
uncaught->error!
macro
clj
(uncaught->error!)(uncaught->error! id)(uncaught->error! {:as opts, :keys [elidable? location instant uid middleware sample-rate ns kind id level when rate-limit ctx parent trace? do let data msg error & user-opts]})
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
(fn handler [`<java.lang.Thread>` `<java.lang.Throwable>`]).
+
See also `uncaught->error!`.
update-var-root!
macro
clj
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
the new value:
(update-var-root! my-var (fn [old-root-val] <new-root-val>)) => <new-root-val>
@@ -318,8 +635,34 @@ See `set-kind-filter!` for details.
Util for tests/debugging.
-Executes given form and returns [<form-result> <last-signal-dispatched-by-form>].
-If `trap-errors?` is true, form result will be wrapped by {:keys [okay error]}.
Executes form with `*out*` and/or `*err*` bound to flush to Telemere signals
+
with-signal
macro
clj
(with-signal form)
Experimental
+Minimal version of `with-signals`.
+Executes given form and returns the last signal triggered by it.
+Useful for tests/debugging.
+
+- Always allows registered handlers to receive signals as usual.
+- Always traps form errors.
+- Never forces `:msg_` key.
+
+See also `with-signals` for more options.
Experimental.
+Executes given form and records any signals triggered by it.
+Return value depends on given options. Useful for tests/debugging.
+
+Options:
+
+ `handle?`
+ Should registered handlers receive signals triggered by form, as usual?
+ Default: true.
+
+ `trap-errors?`
+ If true: returns [[form-value form-error] signals], trapping any form error.
+ If false: returns [ form-value signals], throwing on form error.
+ Default: false.
+
+ `force-msg?`
+ Should delayed `:msg_` keys in signals be replaced with realized strings?
+ Default: false.
+
+See also `with-signal` for a simpler API.
