\ No newline at end of file
diff --git a/index.cljs.html b/index.cljs.html
index 45d6f9f..fd0c30c 100644
--- a/index.cljs.html
+++ b/index.cljs.html
@@ -1,4 +1,4 @@
-Telemere 1.0.0-alpha5
\ No newline at end of file
diff --git a/index.html b/index.html
index be7cc9f..edf82e5 100644
--- a/index.html
+++ b/index.html
@@ -1,3 +1,3 @@
-Telemere 1.0.0-alpha5
\ No newline at end of file
diff --git a/taoensso.telemere.cljs.html b/taoensso.telemere.cljs.html
index c2f27d9..321383b 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>
Dynamic context: arbitrary user-level state attached as `:ctx` to all signals.
@@ -47,9 +47,18 @@ Dispatch options include:
Options for running handler asynchronously via `taoensso.encore/runner`,
{:keys [mode buffer-size n-threads daemon-threads? ...]}
- Supports `:blocking`, `:dropping`, and `:sliding` back pressure modes.
+ Supports `:blocking`, `:dropping`, and `:sliding` back-pressure modes.
NB handling order may be non-sequential when `n-threads` > 1.
+ Default:
+ {:mode :dropping, :buffer-size 4096, :n-threads 1, :daemon-threads? false}
+
+ Options:
+ `mode` - Mode of operation, ∈ #{:sync :blocking :dropping :sliding}.
+ `buffer-size` - Size of buffer before back-pressure mechanism is engaged.
+ `n-threads` - Number of threads for asynchronously executing fns.
+ NB execution order may be non-sequential when n > 1.
+
`priority`
Optional handler priority ∈ℤ (default 100). Handlers will be called in
descending priority order.
@@ -89,7 +98,7 @@ Dispatch options include:
Useful for transforming `handler-arg` before handling.
`error-fn` - (fn [{:keys [handler-id handler-arg error]}]) to call on handler error.
- `backp-fn` - (fn [{:keys [handler-id ]}]) to call on handler back pressure.
+ `backp-fn` - (fn [{:keys [handler-id ]}]) to call on handler back-pressure.
Flow sequence:
@@ -110,7 +119,7 @@ Flow sequence:
otherwise calls will be suppressed before reaching handlers.
(catch->error! form)(catch->error! id form)(catch->error! {:as opts, :keys [rethrow? catch-val elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent 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 [1],
+ 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)
@@ -134,22 +143,22 @@ Examples:
Tips:
- Test using `with-signal`: (with-signal (catch->error! ...)).
- - Supports the same options as other signals [1].
+ - Supports the same options [2] 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:
+-------------------------------------------------------------------
+[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-flow` - (filters, handling, etc.)
Default root (base) value of `*ctx*` var.
+Defaults to `nil`, controlled by:
(get-env {:as :edn} :taoensso.telemere/default-ctx<.platform><.edn>)
-See `get-env` for details.
(error! error)(error! id error)(error! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & kvs]} error)
"Error" signal creator, focused on error + id.
+See `get-env` for details.
(error! error)(error! id error)(error! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & kvs]} error)
"Error" signal creator, emphasizing error + id.
API: [error] [id-or-opts error] => given error (unconditional)
Default kind: `:error`
@@ -170,21 +179,24 @@ Examples:
Tips:
- Test using `with-signal`: (with-signal (error! ...)).
- - Supports the same options as other signals [3].
+ - 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-flow` docstring
-[2] See `help:signal-content` docstring
-[3] See `help:signal-options` docstring
(event! id)(event! id level)(event! id {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & kvs]})
"Event" signal creator, focused on id + level.
+-------------------------------------------------------------------
+[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-flow` - (filters, handling, etc.)
(event! id)(event! id level)(event! id {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & kvs]})
"Event" signal creator, emphasizing id + level.
API: [id] [id level-or-opts] => true iff signal was allowed
Default kind: `:event`
Default level: `:info`
-When filtering conditions are met [1], creates a Telemere signal [2] and
+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.).
@@ -200,19 +212,20 @@ Examples:
Tips:
- Test using `with-signal`: (with-signal (event! ...)).
- - Supports the same options as other signals [3].
+ - Supports the same options [2] as other signals [1].
- - A good general-purpose signal, prefer to `log!` by default, since it
- better encourages structured data over unstructured messages.
+ - `log!` and `event!` are both good default/general-purpose signal creators.
+ - `log!` emphasizes messages, while `event!` emphasizes ids.
- 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-flow` docstring
-[2] See `help:signal-content` docstring
-[3] See `help:signal-options` docstring
Cross-platform util for embedding flexible environmental config during
+-------------------------------------------------------------------
+[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-flow` - (filters, handling, etc.)
Cross-platform util for embedding flexible environmental config during
macro expansion. Used by other Taoensso libraries.
Given a const kw/string id or vector of desc-priority alternative ids,
@@ -282,22 +295,21 @@ Intended for use with browser formatting tools like `binaryage/devtools`,
Ref. <https://github.com/binaryage/cljs-devtools>.
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:
+Both compile-time and runtime config can be specified with:
- 1. System values (JVM properties, environment variables, or
- classpath resources). See library docs for details.
+ System values (JVM properties, environment variables, or
+ classpath resources) [1].
- 2. The filter API consting of the following:
+Runtime config can also be specified with:
- `set-kind-filter!`, `with-kind-filter` - for filtering calls by signal kind (when relevant)
- `set-ns-filter!`, `with-ns-filter` - for filtering calls by namespace
- `set-id-filter!`, `with-id-filter` - for filtering calls by signal id (when relevant)
- `set-minimum-level!`, `with-minimum-level!` - for filtering calls by signal level
+ `set-kind-filter!`, `with-kind-filter` - for filtering calls by signal kind (when relevant)
+ `set-ns-filter!`, `with-ns-filter` - for filtering calls by namespace
+ `set-id-filter!`, `with-id-filter` - for filtering calls by signal id (when relevant)
+ `set-minimum-level!`, `with-minimum-level!` - for filtering calls by signal level
- See the relevant docstrings for details.
+ See the relevant docstrings for details.
-Additional filtering can also be applied on a per-handler basis, see
-`add-handler!` for details.
+Filtering can also be applied per handler, see `add-handler!` for details.
See also:
@@ -306,14 +318,32 @@ See also:
`without-filters` - to disable all runtime filtering
If anything is unclear, please ping me (@ptaoussanis) so that I can
-improve these docs!
Manage handlers with:
+
+ `get-handlers` - Returns info on registered handlers
+ `shut-down-handlers!` - Shuts down registered handlers
+
+ `add-handler!` - Registers given handler
+ `remove-handler!` - Unregisters given handler
See the relevant docstrings for details.
+Clj only: `shut-down-handlers!` is called automatically on JVM shutdown.
If anything is unclear, please ping me (@ptaoussanis) so that I can
improve these docs!
Signals are maps with {:keys [inst id ns level data msg_ ...]},
@@ -351,7 +381,38 @@ Default signal keys:
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`
Call a Telemere signal creator to conditionally create a signal at that callsite.
+
+When filtering conditions are met [4], the call creates a Telemere signal [3]
+and dispatches it to registered handlers for processing (e.g. writing to
+console/file/queue/db, etc.).
+
+Telemere doesn't make a hard distinction between different kinds of signals
+(log, event, error, etc.) - they're all just plain Clojure/Script maps with
+various keys:
+
+ - All signal creators offer the same options [2], and
+ - All signal kinds can contain the same content [3]
+
+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:
+
+ `log!` ---------- [message + opts/level] => true iff signal was created (allowed)
+ `event!` -------- [id + opts/level] => true iff signal was created (allowed)
+ `error!` -------- [error + opts/id ] => given error (unconditional)
+ `trace!` -------- [form + opts/id ] => form result (value/throw) (unconditional)
+ `spy!` ---------- [form + opts/level] => form result (value/throw) (unconditional)
+ `catch->error!` - [error + opts/id ] => form value, or given fallback
+ `signal!` ------- [ opts ] => depends on options
+
+- `log!` and `event!` are both good default/general-purpose signal creators.
+- `log!` emphasizes messages, while `event!` emphasizes ids.
+- `signal!` is the generic creator, and is used by all the others.
+
+-------------------------------------------------------------------
+[2] See `help:signal-options` - {:keys [kind level id data ...]}
+[3] See `help:signal-content` - {:keys [kind level id data ...]}
+[4] See `help:signal-flow` - (filters, handling, etc.)
A signal will be provided to a handler iff ALL of the following are true:
1. Signal (creation) is allowed by compile-time filters
2. Signal (creation) is allowed by runtime filters
3. Signal (handling) is allowed by handler filters
@@ -366,14 +427,14 @@ Note that sample rates are multiplicative:
If a signal is created with 20% sampling and a handler handles 50%
of given signals, then 10% of possible signals will be handled.
- This multiplicative rate is helpfully reflected in the signal's final
+ This multiplicative rate is helpfully reflected in each signal's final
`:sample-rate` value.
For a visual flowchart, see: Ref. <https://www.taoensso.com/telemere/flow>
For more info:
- - On signal filters, see: `help:filters` docstring
- - On handler filters, see: `help:handlers` docstring
+ - On signal filters, see: `help:signal-filters` docstring
+ - On handler filters, see: `help:signal-handlers` docstring
If anything is unclear, please ping me (@ptaoussanis) so that I can
improve these docs!
(log! msg)(log! level msg)(log! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & kvs]} msg)
"Log" signal creator, emphasizing message + level.
API: [msg] [level-or-opts msg] => true iff signal was allowed.
Default kind: `:log`
Default level: `:info`
-When filtering conditions are met [1], creates a Telemere signal [2] and
+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.).
@@ -436,18 +497,19 @@ Examples:
Tips:
- Test using `with-signal`: (with-signal (log! ...)).
- - Supports the same options as other signals [3].
+ - Supports the same options [2] as other signals [1].
- - Prefer `event!` to `log!` by default, since it better encourages structured
- data over unstructured messages.
+ - `log!` and `event!` are both good default/general-purpose signal creators.
+ - `log!` emphasizes messages, while `event!` emphasizes ids.
- `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-flow` docstring
-[2] See `help:signal-content` docstring
-[3] See `help:signal-options` docstring
For use within signal message vectors.
+-------------------------------------------------------------------
+[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-flow` - (filters, handling, etc.)
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.:
@@ -524,11 +586,11 @@ the new value. Cross-platform. See also `update-var-root!`.
(signal! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & kvs]})
Low-level generic signal creator.
-API: [opts] => depends on options [3]
+API: [opts] => depends on options [2]
Default kind: none (optional)
Default level: none (must be provided)
-When filtering conditions are met [1], creates a Telemere signal [2] and
+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.).
@@ -538,32 +600,24 @@ If `:run` option is provided: returns value of given run form, or throws.
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
-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 was created (allowed)
- `log!` - (message + opts/level) => true iff signal was created (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)
+common cases [1].
Tips:
- Test using `with-signal`: (with-signal (signal! ...)).
- - Supports the same options as other signals [3].
+ - Supports the same options [2] as other signals [1].
----------------------------------------
-[1] See `help:signal-flow` docstring
-[2] See `help:signal-content` docstring
-[3] See `help:signal-options` docstring
(spy! form)(spy! id form)(spy! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & kvs]} form)
"Spy" signal creator, focused on form + level.
+-------------------------------------------------------------------
+[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-flow` - (filters, handling, etc.)
(spy! form)(spy! id form)(spy! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & kvs]} form)
"Spy" signal creator, emphasizing form + level.
API: [form] [level-or-opts form] => form's result (value/throw) (unconditional)
Default kind: `:spy`
Default level: `:info`
-When filtering conditions are met [1], creates a Telemere signal [2] and
+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.).
@@ -582,9 +636,9 @@ Examples:
Tips:
- Test using `with-signal`: (with-signal (spy! ...)).
- - Supports the same options as other signals [3].
+ - Supports the same options [2] as other signals [1].
- - Identical to `trace!`, but focused on form + level rather than form + id.
+ - Identical to `trace!`, but emphasizing form + level rather than form + id.
- Useful for debugging/monitoring forms, and tracing (nested) execution flow.
- Execution of `form` arg may create additional (nested) signals.
@@ -593,16 +647,17 @@ Tips:
- Can be useful to wrap with `catch->error!`:
(catch->error! ::error-id (spy! ...)).
----------------------------------------
-[1] See `help:signal-flow` docstring
-[2] See `help:signal-content` docstring
-[3] See `help:signal-options` docstring
(trace! form)(trace! id form)(trace! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & kvs]} form)
"Trace" signal creator, focused on form + id.
+-------------------------------------------------------------------
+[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-flow` - (filters, handling, etc.)
(trace! form)(trace! id form)(trace! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & kvs]} form)
"Trace" signal creator, emphasizing form + id.
API: [form] [id-or-opts form] => form's result (value/throw) (unconditional)
Default kind: `:trace`
Default level: `:info` (intentionally NOT `:trace`!)
-When filtering conditions are met [1], creates a Telemere signal [2] and
+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.).
@@ -621,9 +676,9 @@ Examples:
Tips:
- Test using `with-signal`: (with-signal (trace! ...)).
- - Supports the same options as other signals [3].
+ - Supports the same options [2] as other signals [1].
- - Identical to `spy!`, but focused on form + id rather than form + level.
+ - Identical to `spy!`, but emphasizing form + id rather than form + level.
- Useful for debugging/monitoring forms, and tracing (nested) execution flow.
- Execution of `form` arg may create additional (nested) signals.
@@ -636,10 +691,11 @@ Tips:
refers to the general action of tracing program flow rather than to the
common logging level of the same name.
----------------------------------------
-[1] See `help:signal-flow` docstring
-[2] See `help:signal-content` docstring
-[3] See `help:signal-options` docstring
(uncaught->error!)(uncaught->error! id)(uncaught->error! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & kvs]})
Uses `uncaught->handler!` so that `error!` will be called for
+-------------------------------------------------------------------
+[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-flow` - (filters, handling, etc.)
Updates root binding (value) of the var identified by given symbol, and returns
diff --git a/taoensso.telemere.html b/taoensso.telemere.html
index abf174a..b695a0b 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>
Dynamic context: arbitrary user-level state attached as `:ctx` to all signals.
@@ -47,9 +47,18 @@ Dispatch options include:
Options for running handler asynchronously via `taoensso.encore/runner`,
{:keys [mode buffer-size n-threads daemon-threads? ...]}
- Supports `:blocking`, `:dropping`, and `:sliding` back pressure modes.
+ Supports `:blocking`, `:dropping`, and `:sliding` back-pressure modes.
NB handling order may be non-sequential when `n-threads` > 1.
+ Default:
+ {:mode :dropping, :buffer-size 4096, :n-threads 1, :daemon-threads? false}
+
+ Options:
+ `mode` - Mode of operation, ∈ #{:sync :blocking :dropping :sliding}.
+ `buffer-size` - Size of buffer before back-pressure mechanism is engaged.
+ `n-threads` - Number of threads for asynchronously executing fns.
+ NB execution order may be non-sequential when n > 1.
+
`priority`
Optional handler priority ∈ℤ (default 100). Handlers will be called in
descending priority order.
@@ -89,7 +98,7 @@ Dispatch options include:
Useful for transforming `handler-arg` before handling.
`error-fn` - (fn [{:keys [handler-id handler-arg error]}]) to call on handler error.
- `backp-fn` - (fn [{:keys [handler-id ]}]) to call on handler back pressure.
+ `backp-fn` - (fn [{:keys [handler-id ]}]) to call on handler back-pressure.
Flow sequence:
@@ -110,7 +119,7 @@ Flow sequence:
otherwise calls will be suppressed before reaching handlers.
(catch->error! form)(catch->error! id form)(catch->error! {:as opts, :keys [rethrow? catch-val elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent 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 [1],
+ 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)
@@ -134,22 +143,26 @@ Examples:
Tips:
- Test using `with-signal`: (with-signal (catch->error! ...)).
- - Supports the same options as other signals [1].
+ - Supports the same options [2] as other signals [1].
- Useful for recording errors in forms, futures, callbacks, etc.
See also `error!`.
----------------------------------------
-[1] See `help:signal-options` docstring
Default root (base) value of `*ctx*` var.
+Defaults to `nil`, controlled by:
(get-env {:as :edn} :taoensso.telemere/default-ctx<.platform><.edn>)
-See `get-env` for details.
(error! error)(error! id error)(error! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & kvs]} error)
"Error" signal creator, focused on error + id.
+See `get-env` for details.
(error! error)(error! id error)(error! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & kvs]} error)
"Error" signal creator, emphasizing error + id.
API: [error] [id-or-opts error] => given error (unconditional)
Default kind: `:error`
@@ -170,21 +183,24 @@ Examples:
Tips:
- Test using `with-signal`: (with-signal (error! ...)).
- - Supports the same options as other signals [3].
+ - 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-flow` docstring
-[2] See `help:signal-content` docstring
-[3] See `help:signal-options` docstring
(event! id)(event! id level)(event! id {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & kvs]})
"Event" signal creator, focused on id + level.
+-------------------------------------------------------------------
+[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-flow` - (filters, handling, etc.)
(event! id)(event! id level)(event! id {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & kvs]})
"Event" signal creator, emphasizing id + level.
API: [id] [id level-or-opts] => true iff signal was allowed
Default kind: `:event`
Default level: `:info`
-When filtering conditions are met [1], creates a Telemere signal [2] and
+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.).
@@ -200,19 +216,20 @@ Examples:
Tips:
- Test using `with-signal`: (with-signal (event! ...)).
- - Supports the same options as other signals [3].
+ - Supports the same options [2] as other signals [1].
- - A good general-purpose signal, prefer to `log!` by default, since it
- better encourages structured data over unstructured messages.
+ - `log!` and `event!` are both good default/general-purpose signal creators.
+ - `log!` emphasizes messages, while `event!` emphasizes ids.
- 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-flow` docstring
-[2] See `help:signal-content` docstring
-[3] See `help:signal-options` docstring
Cross-platform util for embedding flexible environmental config during
+-------------------------------------------------------------------
+[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-flow` - (filters, handling, etc.)
Cross-platform util for embedding flexible environmental config during
macro expansion. Used by other Taoensso libraries.
Given a const kw/string id or vector of desc-priority alternative ids,
@@ -305,25 +322,29 @@ Options:
Maximum number of numbered archives to retain for any particular interval.
`:max-num-intervals` ∈ #{nil <pos-int>} (default 6)
- Maximum number of intervals (days/weeks/months) to retain.
Experimental, subject to change!! Feedback very welcome!
+
+Returns a (fn handler [signal]) that:
+ - Takes a Telemere signal.
+ - Emits signal content to the `io.opentelemetry.api.logs.Logger`
+ returned by given `io.opentelemetry.api.logs.LoggerProvider`.
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:
+Both compile-time and runtime config can be specified with:
- 1. System values (JVM properties, environment variables, or
- classpath resources). See library docs for details.
+ System values (JVM properties, environment variables, or
+ classpath resources) [1].
- 2. The filter API consting of the following:
+Runtime config can also be specified with:
- `set-kind-filter!`, `with-kind-filter` - for filtering calls by signal kind (when relevant)
- `set-ns-filter!`, `with-ns-filter` - for filtering calls by namespace
- `set-id-filter!`, `with-id-filter` - for filtering calls by signal id (when relevant)
- `set-minimum-level!`, `with-minimum-level!` - for filtering calls by signal level
+ `set-kind-filter!`, `with-kind-filter` - for filtering calls by signal kind (when relevant)
+ `set-ns-filter!`, `with-ns-filter` - for filtering calls by namespace
+ `set-id-filter!`, `with-id-filter` - for filtering calls by signal id (when relevant)
+ `set-minimum-level!`, `with-minimum-level!` - for filtering calls by signal level
- See the relevant docstrings for details.
+ See the relevant docstrings for details.
-Additional filtering can also be applied on a per-handler basis, see
-`add-handler!` for details.
+Filtering can also be applied per handler, see `add-handler!` for details.
See also:
@@ -332,14 +353,32 @@ See also:
`without-filters` - to disable all runtime filtering
If anything is unclear, please ping me (@ptaoussanis) so that I can
-improve these docs!
Manage handlers with:
+
+ `get-handlers` - Returns info on registered handlers
+ `shut-down-handlers!` - Shuts down registered handlers
+
+ `add-handler!` - Registers given handler
+ `remove-handler!` - Unregisters given handler
See the relevant docstrings for details.
+Clj only: `shut-down-handlers!` is called automatically on JVM shutdown.
If anything is unclear, please ping me (@ptaoussanis) so that I can
improve these docs!
Signals are maps with {:keys [inst id ns level data msg_ ...]},
@@ -377,25 +416,55 @@ Default signal keys:
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`
Call a Telemere signal creator to conditionally create a signal at that callsite.
+
+When filtering conditions are met [4], the call creates a Telemere signal [3]
+and dispatches it to registered handlers for processing (e.g. writing to
+console/file/queue/db, etc.).
+
+Telemere doesn't make a hard distinction between different kinds of signals
+(log, event, error, etc.) - they're all just plain Clojure/Script maps with
+various keys:
+
+ - All signal creators offer the same options [2], and
+ - All signal kinds can contain the same content [3]
+
+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:
+
+ `log!` ---------- [message + opts/level] => true iff signal was created (allowed)
+ `event!` -------- [id + opts/level] => true iff signal was created (allowed)
+ `error!` -------- [error + opts/id ] => given error (unconditional)
+ `trace!` -------- [form + opts/id ] => form result (value/throw) (unconditional)
+ `spy!` ---------- [form + opts/level] => form result (value/throw) (unconditional)
+ `catch->error!` - [error + opts/id ] => form value, or given fallback
+ `signal!` ------- [ opts ] => depends on options
+
+- `log!` and `event!` are both good default/general-purpose signal creators.
+- `log!` emphasizes messages, while `event!` emphasizes ids.
+- `signal!` is the generic creator, and is used by all the others.
+
+-------------------------------------------------------------------
+[2] See `help:signal-options` - {:keys [kind level id data ...]}
+[3] See `help:signal-content` - {:keys [kind level id data ...]}
+[4] See `help:signal-flow` - (filters, handling, etc.)
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:
+Both compile-time and runtime config can be specified with:
- 1. System values (JVM properties, environment variables, or
- classpath resources). See library docs for details.
+ System values (JVM properties, environment variables, or
+ classpath resources) [1].
- 2. The filter API consting of the following:
+Runtime config can also be specified with:
- `set-kind-filter!`, `with-kind-filter` - for filtering calls by signal kind (when relevant)
- `set-ns-filter!`, `with-ns-filter` - for filtering calls by namespace
- `set-id-filter!`, `with-id-filter` - for filtering calls by signal id (when relevant)
- `set-minimum-level!`, `with-minimum-level!` - for filtering calls by signal level
+ `set-kind-filter!`, `with-kind-filter` - for filtering calls by signal kind (when relevant)
+ `set-ns-filter!`, `with-ns-filter` - for filtering calls by namespace
+ `set-id-filter!`, `with-id-filter` - for filtering calls by signal id (when relevant)
+ `set-minimum-level!`, `with-minimum-level!` - for filtering calls by signal level
- See the relevant docstrings for details.
+ See the relevant docstrings for details.
-Additional filtering can also be applied on a per-handler basis, see
-`add-handler!` for details.
+Filtering can also be applied per handler, see `add-handler!` for details.
See also:
@@ -404,7 +473,23 @@ See also:
`without-filters` - to disable all runtime filtering
If anything is unclear, please ping me (@ptaoussanis) so that I can
-improve these docs!
A signal will be provided to a handler iff ALL of the following are true:
+improve these docs!
+
+[1] These include:
+
+ Compile-time:
+
+ ns-filter: (get-env {:as :edn} :taoensso.telemere/ct-ns-filter<.platform><.edn>)
+ id-filter: (get-env {:as :edn} :taoensso.telemere/ct-id-filter<.platform><.edn>)
+ min-level: (get-env {:as :edn} :taoensso.telemere/ct-min-level<.platform><.edn>)
+
+ Runtime:
+
+ ns-filter: (get-env {:as :edn} :taoensso.telemere/rt-ns-filter<.platform><.edn>)
+ id-filter: (get-env {:as :edn} :taoensso.telemere/rt-id-filter<.platform><.edn>)
+ min-level: (get-env {:as :edn, :default :info} :taoensso.telemere/rt-min-level<.platform><.edn>)
+
+ See `get-env` for details.
A signal will be provided to a handler iff ALL of the following are true:
1. Signal (creation) is allowed by compile-time filters
2. Signal (creation) is allowed by runtime filters
3. Signal (handling) is allowed by handler filters
@@ -419,14 +504,14 @@ Note that sample rates are multiplicative:
If a signal is created with 20% sampling and a handler handles 50%
of given signals, then 10% of possible signals will be handled.
- This multiplicative rate is helpfully reflected in the signal's final
+ This multiplicative rate is helpfully reflected in each signal's final
`:sample-rate` value.
For a visual flowchart, see: Ref. <https://www.taoensso.com/telemere/flow>
For more info:
- - On signal filters, see: `help:filters` docstring
- - On handler filters, see: `help:handlers` docstring
+ - On signal filters, see: `help:signal-filters` docstring
+ - On handler filters, see: `help:signal-handlers` docstring
If anything is unclear, please ping me (@ptaoussanis) so that I can
improve these docs!
Manage handlers with:
- `get-handlers` - Returns info on currently registered handlers
- `add-handler!` - Used to register handlers
- `remove-handler!` - Used to unregister handlers
- `shut-down-handlers!` - Used to shut down handlers
+ `get-handlers` - Returns info on registered handlers
+ `shut-down-handlers!` - Shuts down registered handlers
+
+ `add-handler!` - Registers given handler
+ `remove-handler!` - Unregisters given handler
See the relevant docstrings for details.
+Clj only: `shut-down-handlers!` is called automatically on JVM shutdown.
If anything is unclear, please ping me (@ptaoussanis) so that I can
improve these docs!
Signal options (shared by all signal creators):
@@ -477,13 +564,13 @@ 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`
(log! msg)(log! level msg)(log! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & kvs]} msg)
"Log" signal creator, emphasizing message + level.
API: [msg] [level-or-opts msg] => true iff signal was allowed.
Default kind: `:log`
Default level: `:info`
-When filtering conditions are met [1], creates a Telemere signal [2] and
+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.).
@@ -500,18 +587,19 @@ Examples:
Tips:
- Test using `with-signal`: (with-signal (log! ...)).
- - Supports the same options as other signals [3].
+ - Supports the same options [2] as other signals [1].
- - Prefer `event!` to `log!` by default, since it better encourages structured
- data over unstructured messages.
+ - `log!` and `event!` are both good default/general-purpose signal creators.
+ - `log!` emphasizes messages, while `event!` emphasizes ids.
- `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-flow` docstring
-[2] See `help:signal-content` docstring
-[3] See `help:signal-options` docstring
For use within signal message vectors.
+-------------------------------------------------------------------
+[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-flow` - (filters, handling, etc.)
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.:
@@ -589,17 +677,17 @@ will apply only for that signal kind.
Shuts down all registered signal handlers and returns
?{<handler-id> {:keys [okay error]}}.
Future calls to handlers will no-op.
Clj only: `shut-down-handlers!` is called automatically on JVM shutdown.
(signal! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & kvs]})
Low-level generic signal creator.
-API: [opts] => depends on options [3]
+API: [opts] => depends on options [2]
Default kind: none (optional)
Default level: none (must be provided)
-When filtering conditions are met [1], creates a Telemere signal [2] and
+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.).
@@ -609,32 +697,24 @@ If `:run` option is provided: returns value of given run form, or throws.
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
-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 was created (allowed)
- `log!` - (message + opts/level) => true iff signal was created (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)
+common cases [1].
Tips:
- Test using `with-signal`: (with-signal (signal! ...)).
- - Supports the same options as other signals [3].
+ - Supports the same options [2] as other signals [1].
----------------------------------------
-[1] See `help:signal-flow` docstring
-[2] See `help:signal-content` docstring
-[3] See `help:signal-options` docstring
(spy! form)(spy! id form)(spy! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & kvs]} form)
"Spy" signal creator, focused on form + level.
+-------------------------------------------------------------------
+[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-flow` - (filters, handling, etc.)
(spy! form)(spy! id form)(spy! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & kvs]} form)
"Spy" signal creator, emphasizing form + level.
API: [form] [level-or-opts form] => form's result (value/throw) (unconditional)
Default kind: `:spy`
Default level: `:info`
-When filtering conditions are met [1], creates a Telemere signal [2] and
+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.).
@@ -653,9 +733,9 @@ Examples:
Tips:
- Test using `with-signal`: (with-signal (spy! ...)).
- - Supports the same options as other signals [3].
+ - Supports the same options [2] as other signals [1].
- - Identical to `trace!`, but focused on form + level rather than form + id.
+ - Identical to `trace!`, but emphasizing form + level rather than form + id.
- Useful for debugging/monitoring forms, and tracing (nested) execution flow.
- Execution of `form` arg may create additional (nested) signals.
@@ -664,10 +744,11 @@ Tips:
- Can be useful to wrap with `catch->error!`:
(catch->error! ::error-id (spy! ...)).
----------------------------------------
-[1] See `help:signal-flow` docstring
-[2] See `help:signal-content` docstring
-[3] See `help:signal-options` docstring
streams->reset!
clj
(streams->reset!)
Experimental, subject to change without notice!
+-------------------------------------------------------------------
+[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-flow` - (filters, handling, etc.)
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!
@@ -682,17 +763,16 @@ See also:
`with-err->telemere`,
`with-streams->telemere`.
tools-logging->telemere!
clj
(tools-logging->telemere!)
Configures `clojure.tools.logging` to use Telemere as its logging implementation.
-Will be AUTOMATICALLY called if `clojure.tools.logging` is present and any of the
-following are "true":
- - `clojure.tools.logging->telemere?` JVM propety value
- - `CLOJURE_TOOLS_LOGGING_>TELEMERE?` Environment variable
- - `clojure.tools.logging->telemere?` Classpath resource content
(trace! form)(trace! id form)(trace! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & kvs]} form)
"Trace" signal creator, focused on form + id.
+Called automatically if the following is true:
+ (get-env {:as :bool} :clojure.tools.logging->telemere?)
+
+See `get-env` for details.
(trace! form)(trace! id form)(trace! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & kvs]} form)
"Trace" signal creator, emphasizing form + id.
API: [form] [id-or-opts form] => form's result (value/throw) (unconditional)
Default kind: `:trace`
Default level: `:info` (intentionally NOT `:trace`!)
-When filtering conditions are met [1], creates a Telemere signal [2] and
+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.).
@@ -711,9 +791,9 @@ Examples:
Tips:
- Test using `with-signal`: (with-signal (trace! ...)).
- - Supports the same options as other signals [3].
+ - Supports the same options [2] as other signals [1].
- - Identical to `spy!`, but focused on form + id rather than form + level.
+ - Identical to `spy!`, but emphasizing form + id rather than form + level.
- Useful for debugging/monitoring forms, and tracing (nested) execution flow.
- Execution of `form` arg may create additional (nested) signals.
@@ -726,10 +806,11 @@ Tips:
refers to the general action of tracing program flow rather than to the
common logging level of the same name.
----------------------------------------
-[1] See `help:signal-flow` docstring
-[2] See `help:signal-content` docstring
-[3] See `help:signal-options` docstring
(uncaught->error!)(uncaught->error! id)(uncaught->error! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & kvs]})
Uses `uncaught->handler!` so that `error!` will be called for
+-------------------------------------------------------------------
+[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-flow` - (filters, handling, etc.)
\ No newline at end of file
diff --git a/taoensso.telemere.timbre.html b/taoensso.telemere.timbre.html
index b0477b5..9aadd81 100644
--- a/taoensso.telemere.timbre.html
+++ b/taoensso.telemere.timbre.html
@@ -1,6 +1,6 @@
-taoensso.telemere.timbre documentation
\ No newline at end of file
diff --git a/taoensso.telemere.utils.cljs.html b/taoensso.telemere.utils.cljs.html
index c503921..ea047c9 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 given signal with possible `:error` replaced by
[{:keys [type msg data]} ...] cause chain.
diff --git a/taoensso.telemere.utils.html b/taoensso.telemere.utils.html
index 2389fb8..708e39b 100644
--- a/taoensso.telemere.utils.html
+++ b/taoensso.telemere.utils.html
@@ -1,6 +1,6 @@
-taoensso.telemere.utils documentation