From fb79ae509be29627d35761bfd1965757bca2d957 Mon Sep 17 00:00:00 2001 From: Peter Taoussanis Date: Fri, 12 Apr 2024 18:01:09 +0200 Subject: [PATCH] v1.0.0-alpha5 (2024-04-12) --- index.clj.html | 2 +- index.cljs.html | 2 +- index.html | 2 +- taoensso.telemere.cljs.html | 247 +++++++++++++------------ taoensso.telemere.html | 285 ++++++++++++++++++----------- taoensso.telemere.timbre.cljs.html | 2 +- taoensso.telemere.timbre.html | 2 +- taoensso.telemere.utils.cljs.html | 4 +- taoensso.telemere.utils.html | 4 +- 9 files changed, 317 insertions(+), 233 deletions(-) diff --git a/index.clj.html b/index.clj.html index 809515d..3d81c81 100644 --- a/index.clj.html +++ b/index.clj.html @@ -1,4 +1,4 @@ -Telemere 1.0.0-alpha4

Namespaces

Telemere 1.0.0-alpha4

Released under the Eclipse Public License - v 1.0

Structured telemetry library for Clojure/Script.

Installation

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

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

Namespaces

taoensso.telemere

Structured telemetry for Clojure/Script applications.

Public variables and functions:

taoensso.telemere.timbre

Main Timbre macros, reimplemented on top of Telemere.
+Telemere 1.0.0-alpha5
Namespaces
Telemere 1.0.0-alpha5
Released under the Eclipse Public License - v 1.0
Structured telemetry library for Clojure/Script.
Installation
To install, add the following dependency to your project or build file:
[com.taoensso/telemere "1.0.0-alpha5"]
Namespaces
taoensso.telemere
Structured telemetry for Clojure/Script applications.
Public variables and functions:
taoensso.telemere.timbre
Main Timbre macros, reimplemented on top of Telemere.
 Intended to help ease migration from Timbre to Telemere.
Public variables and functions:
taoensso.telemere.utils
Misc utils useful for Telemere handlers, middleware, etc.
Public variables and functions:

\ No newline at end of file
diff --git a/index.cljs.html b/index.cljs.html
index ce61ce7..45d6f9f 100644
--- a/index.cljs.html
+++ b/index.cljs.html
@@ -1,4 +1,4 @@
 
-Telemere 1.0.0-alpha4
Namespaces
Telemere 1.0.0-alpha4
Released under the Eclipse Public License - v 1.0
Structured telemetry library for Clojure/Script.
Installation
To install, add the following dependency to your project or build file:
[com.taoensso/telemere "1.0.0-alpha4"]
Namespaces
taoensso.telemere
Structured telemetry for Clojure/Script applications.
Public variables and functions:
taoensso.telemere.timbre
Main Timbre macros, reimplemented on top of Telemere.
+Telemere 1.0.0-alpha5
Namespaces
Telemere 1.0.0-alpha5
Released under the Eclipse Public License - v 1.0
Structured telemetry library for Clojure/Script.
Installation
To install, add the following dependency to your project or build file:
[com.taoensso/telemere "1.0.0-alpha5"]
Namespaces
taoensso.telemere
Structured telemetry for Clojure/Script applications.
Public variables and functions:
taoensso.telemere.timbre
Main Timbre macros, reimplemented on top of Telemere.
 Intended to help ease migration from Timbre to Telemere.
Public variables and functions:
    taoensso.telemere.utils
    Misc utils useful for Telemere handlers, middleware, etc.
    Public variables and functions:
    
\ No newline at end of file
diff --git a/index.html b/index.html
index 3972a89..be7cc9f 100644
--- a/index.html
+++ b/index.html
@@ -1,3 +1,3 @@
 
-Telemere 1.0.0-alpha4
    Platforms
    Telemere 1.0.0-alpha4
    Released under the Eclipse Public License - v 1.0
    Structured telemetry library for Clojure/Script.
    Installation
    To install, add the following dependency to your project or build file:
    [com.taoensso/telemere "1.0.0-alpha4"]
    Platforms
    This project includes code for multiple platforms, please choose a platform to view its documentation:
    
\ No newline at end of file
+Telemere 1.0.0-alpha5
    Platforms
    Telemere 1.0.0-alpha5
    Released under the Eclipse Public License - v 1.0
    Structured telemetry library for Clojure/Script.
    Installation
    To install, add the following dependency to your project or build file:
    [com.taoensso/telemere "1.0.0-alpha5"]
    Platforms
    This project includes code for multiple platforms, please choose a platform to view its documentation:
    
\ No newline at end of file
diff --git a/taoensso.telemere.cljs.html b/taoensso.telemere.cljs.html
index 88dafc9..c2f27d9 100644
--- a/taoensso.telemere.cljs.html
+++ b/taoensso.telemere.cljs.html
@@ -1,6 +1,6 @@
 
-taoensso.telemere documentation
    Namespaces
    Public Vars
    taoensso.telemere
    Structured telemetry for Clojure/Script applications.
+taoensso.telemere documentation
    Namespaces
    Public Vars
    taoensso.telemere
    Structured telemetry for Clojure/Script applications.
 
 See the GitHub page (esp. Wiki) for info on motivation and design:
   <https://www.taoensso.com/telemere>
    *ctx*
    dynamic
    clj
    cljs
    Dynamic context: arbitrary user-level state attached as `:ctx` to all signals.
@@ -107,7 +107,7 @@ Flow sequence:
     e. Hander fn
 
   Note: call filters should generally be at least as permissive as handler filters,
-  otherwise calls will be suppressed before reaching handlers.
    catch->error!
    macro
    clj
    cljs
    (catch->error! form)(catch->error! id form)(catch->error! {:as opts, :keys [rethrow? catch-val elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & extra-kvs]} form)
    Unconditionally executes given form and-
+  otherwise calls will be suppressed before reaching handlers.
    catch->error!
    macro
    clj
    cljs
    (catch->error! form)(catch->error! id form)(catch->error! {:as opts, :keys [rethrow? catch-val elidable? location inst uid middleware 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],
@@ -140,6 +140,7 @@ Tips:
 
 See also `error!`.
 
+---------------------------------------
 [1] See `help:signal-options` docstring
    chance
    clj
    cljs
    (chance prob)
    Returns true with given probability ∈ ℝ[0,1].
 
    check-interop
    clj
    cljs
    (check-interop)
    Experimental, subject to change.
 Runs Telemere's registered interop checks and returns
@@ -148,7 +149,7 @@ Runs Telemere's registered interop checks and returns
 Useful for tests/debugging.
    default-ctx
    clj
    cljs
    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
    cljs
    (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 & extra-kvs]} error)
    "Error" signal call, focused on error + id.
+See `get-env` for details.
    error!
    macro
    clj
    cljs
    (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.
 
 API: [error] [id-or-opts error] => given error (unconditional)
 Default  kind: `:error`
@@ -174,16 +175,18 @@ Tips:
   - `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
    cljs
    (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 & extra-kvs]})
    "Event" signal call, focused on id + level.
+----------------------------------------
+[1] See `help:signal-flow`    docstring
+[2] See `help:signal-content` docstring
+[3] See `help:signal-options` docstring
    event!
    macro
    clj
    cljs
    (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.
 
-API: [id] [id level-or-opts] => true iff signal call was allowed
+API: [id] [id level-or-opts] => true iff signal 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.).
+When filtering conditions are met [1], creates a Telemere signal [2] and
+dispatches it to registered handlers for processing (e.g. writing to
+console/file/queue/db, etc.).
 
 Examples:
 
@@ -207,9 +210,9 @@ Tips:
     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
    get-env
    macro
    clj
    cljs
    added in Encore v3.75.0 (2024-01-29)
    (get-env {:keys [as default return]} spec)(get-env {:keys [as default return spec], :or {as :str, return :value}})
    Cross-platform util for embedding flexible environmental config during
+[1] See `help:signal-flow`    docstring
+[2] See `help:signal-content` docstring
+[3] See `help:signal-options` docstring
    get-env
    macro
    clj
    cljs
    added in Encore v3.75.0 (2024-01-29)
    (get-env {:keys [as default return]} spec)(get-env {:keys [as default return spec], :or {as :str, return :value}})
    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,
@@ -313,103 +316,112 @@ improve these docs!
    help:signal-content
    clj
    cljs
    Signals are initially maps with {:keys [inst id ns level data msg_ ...]},
-though they can be modified by call and/or handler middleware.
+improve these docs!
    help:signal-content
    clj
    cljs
    Signals are maps with {:keys [inst id ns level data msg_ ...]},
+though they can be modified by signal and/or handler middleware.
 
-Default keys:
+Default signal keys:
 
-`:schema` - Int version of signal schema (current: 1)
-`:inst`   - 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`)
+`:schema` ------ Int version of signal schema (current: 1)
+`:inst` -------- 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          (common to all  signals created at callsite, contrast with `:uid`)
+`:uid` --------- ?id of signal instance (unique to each signal  created at callsite, contrast with  `:id`)
 
-`:msg`   - Arb user-level message  ?str              given to signal call
-`:data`  - Arb user-level data     ?val (usu. a map) given to signal call
-`:error` - Arb user-level platform ?error [2]        given to signal call
+`:msg` --------- Arb user-level message  ?str              given to signal creator
+`:data` -------- Arb user-level data     ?val (usu. a map) given to signal creator
+`:error` ------- Arb user-level platform ?error [2]        given to signal creator
 
-`:run-form` - Unevaluated ?form given to signal call as `:run`
-`:run-val`  - Successful return ?val of  `:run` ?form
-`:run-nsecs`- ?int nanosecs runtime of   `:run` ?form
-`:end-inst` - Platform ?instant [1] when `:run` ?form completed
+`:run-form` ---- Unevaluated ?form given to signal creator as `:run`
+`:run-val` ----- Successful return ?val of  `:run` ?form
+`:run-nsecs` --- ?int nanosecs runtime of   `:run` ?form
+`:end-inst` ---- Platform ?instant [1] when `:run` ?form completed
 
-`: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)
-`:line`     - ?int line      of signal call, same as (:line   location)
-`:column`   - ?int column    of signal call, same as (:column location)
-`:file`     - ?str filename  of signal call, same as (:file   location)
+`: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 creator callsite
+`:ns` ---------- ?str namespace of signal creator callsite, same as (:ns     location)
+`:line` -------- ?int line      of signal creator callsite, same as (:line   location)
+`:column` ------ ?int column    of signal creator callsite, same as (:column location)
+`:file` -------- ?str filename  of signal creator callsite, same as (:file   location)
+`:sample-rate` - ?rate ∈ℝ[0,1] for combined signal AND handler sampling (0.75 => allow 75% of signals, nil => allow all)
 
-`:sample-rate` - ?rate ∈ℝ[0,1] for combined call AND handler sampling (0.75 => allow 75% of signals, nil => allow all)
-
-<extra-kvs> - Arb user-level ?kvs given to signal call
+<kvs> ---------- Arb other user-level ?kvs given to signal creator
 
 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`
    help:signal-formatters
    clj
    cljs
    Common signal formatters include:
+[2] `java.lang.Throwable` or `js/Error`
    help:signal-filters
    clj
    cljs
    help:signal-flow
    clj
    cljs
    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
+
+  4. Signal  middleware does not suppress the signal (return nil)
+  5. Handler middleware does not suppress the signal (return nil)
+
+For 1-3, filtering may depend on (in order):
+  Sample rate → namespace → kind → id → level → when form/fn → rate limit
+
+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
+  `: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
+
+If anything is unclear, please ping me (@ptaoussanis) so that I can
+improve these docs!
    help:signal-formatters
    clj
    cljs
    Common signal formatters include:
   (utils/format-signal-str->fn) {<opts>}) ; For human-readable string output (default)
   (utils/format-signal->edn-fn) {<opts>}) ; For edn  output
   (utils/format-signal->json-fn {<opts>}) ; For JSON output
 
-See relevant docstrings for details.
    help:signal-handling
    clj
    cljs
    A signal will be provided to a handler iff ALL of the following are true:
+See relevant docstrings for details.
    help:signal-handlers
    clj
    cljs
    help:signal-options
    clj
    cljs
    Signal options (shared by all signal creators):
 
-  1. Signal call is allowed by compile-time filters
-  2. Signal call is allowed by runtime      filters
-  3. Handler     is allowed by runtime      filters
+`:inst` -------- 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          (common to all  signals created at callsite, contrast with `:uid`)
+`:uid` --------- ?id of signal instance (unique to each signal  created at callsite, contrast with  `:id`)
 
-  4. Signal call middleware does not suppress the signal (return nil)
-  5. Handler     middleware does not suppress the signal (return nil)
+`:msg` --------- Arb user-level ?message to incl. in signal: str or vec of strs to join (with `\space`)
+`:data` -------- Arb user-level ?data    to incl. in signal: usu. a map
+`:error` ------- Arb user-level ?error   to incl. in signal: platform error [2]
 
-For more info:
+`:run` --------- ?form     to execute UNCONDITIONALLY; will incl. `:run-value` 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!)
 
-  - 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>
+`: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
 
-If anything is unclear, please ping me (@ptaoussanis) so that I can
-improve these docs!
    help:signal-options
    clj
    cljs
    Signal options (shared by `signal!`, `event!`, ...):
-
-`:inst`  - 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`)
-
-`:msg`   - Arb user-level ?message to incl. in signal: str or vec of strs to join (with `\space`)
-`:data`  - Arb user-level ?data    to incl. in signal: usu. a map
-`: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)
+`:elidable?` --- Should signal 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?
+`:when` -------- Arb ?form; when present, form must return truthy to allow signal
+`:rate-limit` -- ?spec as given to `taoensso.telemere/rate-limiter`, see its docstring for details
+`:middleware` -- ?[(fn [signal])=>modified-signal ...] signal middleware
+`:trace?` ------ Should tracing be enabled for `:run` form?
 
-<extra-kvs> - Arb user-level ?kvs to incl. in signal
+<kvs> ---------- Arb other user-level ?kvs to incl. in signal
 
 If anything is unclear, please ping me (@ptaoussanis) so that I can improve these docs!
 
 [1] `java.time.Instant`   or `js/Date`
-[2] `java.lang.Throwable` or `js/Error`
    level-aliases
    clj
    cljs
    log!
    macro
    clj
    cljs
    (log! msg)(log! level msg)(log! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & extra-kvs]} msg)
    "Log" signal call, focused on message + level.
+[2] `java.lang.Throwable` or `js/Error`
    level-aliases
    clj
    cljs
    log!
    macro
    clj
    cljs
    (log! msg)(log! level msg)(log! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & kvs]} msg)
    "Log" signal creator, focused on message + level.
 
-API: [msg] [level-or-opts msg] => true iff signal call was allowed.
+API: [msg] [level-or-opts msg] => true iff signal 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.).
+When filtering conditions are met [1], creates a Telemere signal [2] and
+dispatches it to registered handlers for processing (e.g. writing to
+console/file/queue/db, etc.).
 
 Examples:
 
@@ -433,9 +445,9 @@ Tips:
   - 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
    msg-skip
    clj
    cljs
    msg-splice
    clj
    cljs
    (msg-splice args)
    For use within signal message vectors.
+[1] See `help:signal-flow`    docstring
+[2] See `help:signal-content` docstring
+[3] See `help:signal-options` docstring
    msg-skip
    clj
    cljs
    msg-splice
    clj
    cljs
    (msg-splice args)
    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.:
 
@@ -475,13 +487,17 @@ still registered.
    set-kind-filter!
    clj
    cljs
    (set-kind-filter! kind-filter)
    Sets signal call kind filter based on given `kind-filter` spec.
+  - {:allow <spec> :deny <spec>} with specs as above.
+    If present, `:allow` spec MUST     match, AND
+    If present, `:deny`  spec MUST NOT match.
    set-kind-filter!
    clj
    cljs
    (set-kind-filter! kind-filter)
    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
    cljs
    (set-middleware! root-val)
    Set `*middleware*` var's root (base) value. See `*middleware*` for details.
+  - {:allow <spec> :deny <spec>} with specs as above.
+    If present, `:allow` spec MUST     match, AND
+    If present, `:deny`  spec MUST NOT match.
    set-middleware!
    macro
    clj
    cljs
    (set-middleware! root-val)
    Set `*middleware*` var's root (base) value. See `*middleware*` for details.
 
    set-min-level!
    clj
    cljs
    (set-min-level! min-level)(set-min-level! kind min-level)(set-min-level! kind ns-filter min-level)
    Sets minimum signal call level based on given `min-level` spec.
 `min-level` may be:
 
@@ -499,33 +515,36 @@ will apply only for that signal kind.
    set-var-root!
    macro
    clj
    cljs
    added in Encore v3.75.0 (2024-01-29)
    (set-var-root! var-sym root-val)
    Sets root binding (value) of the var identified by given symbol, and returns
+  - {:allow <spec> :deny <spec>} with specs as above.
+    If present, `:allow` spec MUST     match, AND
+    If present, `:deny`  spec MUST NOT match.
    set-var-root!
    macro
    clj
    cljs
    added in Encore v3.75.0 (2024-01-29)
    (set-var-root! var-sym root-val)
    Sets root binding (value) of the var identified by given symbol, and returns
 the new value. Cross-platform. See also `update-var-root!`.
    shut-down-handlers!
    clj
    cljs
    (shut-down-handlers!)
    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!
    macro
    clj
    cljs
    (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 & extra-kvs]})
    Low-level generic signal call.
+Clj only: `shut-down-handlers!` is called automatically on JVM shutdown.
    signal!
    macro
    clj
    cljs
    (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]
 Default  kind: none (optional)
 Default level: none (must be provided)
 
-When conditions are met [1], creates a Telemere signal [2] and dispatches it to
-registered handlers for processing (writing to console/disk/db, etc.).
+When filtering conditions are met [1], creates a Telemere signal [2] 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 call conditions were met.
+                   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 provided wrapper macros optimized for ease-of-use in
+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 call was allowed
-  `log!`   - (message + opts/level) => true iff signal call was allowed
+  `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)
@@ -535,17 +554,18 @@ Tips:
   - Test using `with-signal`: (with-signal (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
    cljs
    (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 & extra-kvs]} form)
    "Spy" signal call, focused on form + level.
+---------------------------------------
+[1] See `help:signal-flow`    docstring
+[2] See `help:signal-content` docstring
+[3] See `help:signal-options` docstring
    spy!
    macro
    clj
    cljs
    (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.
 
 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.).
+When filtering conditions are met [1], creates a Telemere signal [2] and
+dispatches it to registered handlers for processing (e.g. writing to
+console/file/queue/db, etc.).
 
 Examples:
 
@@ -567,23 +587,24 @@ Tips:
   - 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.
+  - Execution of `form` arg 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! ...)).
 
-----------------------------------------
-[1] See `help:signal-handling` docstring
-[2] See `help:signal-content`  docstring
-[3] See `help:signal-options`  docstring
    trace!
    macro
    clj
    cljs
    (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 & extra-kvs]} form)
    "Trace" signal call, focused on form + id.
+---------------------------------------
+[1] See `help:signal-flow`    docstring
+[2] See `help:signal-content` docstring
+[3] See `help:signal-options` docstring
    trace!
    macro
    clj
    cljs
    (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.
 
 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.).
+When filtering conditions are met [1], creates a Telemere signal [2] and
+dispatches it to registered handlers for processing (e.g. writing to
+console/file/queue/db, etc.).
 
 Examples:
 
@@ -605,7 +626,7 @@ Tips:
   - 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.
+  - Execution of `form` arg may create additional (nested) signals.
     Each signal's `:parent` key will indicate its immediate parent.
 
   - Can be useful to wrap with `catch->error!`:
@@ -615,10 +636,10 @@ 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-handling` docstring
-[2] See `help:signal-content`  docstring
-[3] See `help:signal-options`  docstring
    uncaught->error!
    macro
    clj
    cljs
    (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 & extra-kvs]})
    Uses `uncaught->handler!` so that `error!` will be called for
+---------------------------------------
+[1] See `help:signal-flow`    docstring
+[2] See `help:signal-content` docstring
+[3] See `help:signal-options` docstring
    uncaught->error!
    macro
    clj
    cljs
    (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
 uncaught JVM errors.
 
 See `uncaught->handler!` and `error!` for details.
    update-var-root!
    macro
    clj
    cljs
    added in Encore v3.68.0 (2023-09-25)
    (update-var-root! var-sym update-fn)
    Updates root binding (value) of the var identified by given symbol, and returns
@@ -643,12 +664,12 @@ See `*middleware*` for details.
    with-ns-filter
    macro
    clj
    cljs
    (with-ns-filter ns-filter form)
    Executes form with given signal call namespace filter in effect.
 See `set-ns-filter!` for details.
    with-out->telemere
    macro
    clj
    cljs
    (with-out->telemere form)(with-out->telemere opts form)
    Executes form with `*out*` bound to flush to Telemere signals with given opts.
 
    with-signal
    macro
    clj
    cljs
    (with-signal form)(with-signal trap-signals? form)(with-signal raw-msg? trap-signals? form)
    Experimental.
-Executes given form, trapping errors. Returns the LAST signal triggered by form.
+Executes given form, trapping errors. Returns the LAST signal created by form.
 Useful for tests/debugging.
 
 Options:
   `trap-signals?` (default: false)
-    Should ALL signals triggered by form be trapped to prevent normal dispatch
+    Should ALL signals created by form be trapped to prevent normal dispatch
     to registered handlers?
 
   `raw-msg?` (default: false)
diff --git a/taoensso.telemere.html b/taoensso.telemere.html
index 95057fb..abf174a 100644
--- a/taoensso.telemere.html
+++ b/taoensso.telemere.html
@@ -1,6 +1,6 @@
 
-taoensso.telemere documentation
    Namespaces
    Public Vars
    taoensso.telemere
    Structured telemetry for Clojure/Script applications.
+taoensso.telemere documentation
    Namespaces
    Public Vars
    taoensso.telemere
    Structured telemetry for Clojure/Script applications.
 
 See the GitHub page (esp. Wiki) for info on motivation and design:
   <https://www.taoensso.com/telemere>
    *ctx*
    dynamic
    clj
    cljs
    Dynamic context: arbitrary user-level state attached as `:ctx` to all signals.
@@ -107,7 +107,7 @@ Flow sequence:
     e. Hander fn
 
   Note: call filters should generally be at least as permissive as handler filters,
-  otherwise calls will be suppressed before reaching handlers.
    catch->error!
    macro
    clj
    cljs
    (catch->error! form)(catch->error! id form)(catch->error! {:as opts, :keys [rethrow? catch-val elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & extra-kvs]} form)
    Unconditionally executes given form and-
+  otherwise calls will be suppressed before reaching handlers.
    catch->error!
    macro
    clj
    cljs
    (catch->error! form)(catch->error! id form)(catch->error! {:as opts, :keys [rethrow? catch-val elidable? location inst uid middleware 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],
@@ -140,6 +140,7 @@ Tips:
 
 See also `error!`.
 
+---------------------------------------
 [1] See `help:signal-options` docstring
    chance
    clj
    cljs
    (chance prob)
    Returns true with given probability ∈ ℝ[0,1].
 
    check-interop
    clj
    cljs
    (check-interop)
    Experimental, subject to change.
 Runs Telemere's registered interop checks and returns
@@ -148,7 +149,7 @@ Runs Telemere's registered interop checks and returns
 Useful for tests/debugging.
    default-ctx
    clj
    cljs
    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
    cljs
    (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 & extra-kvs]} error)
    "Error" signal call, focused on error + id.
+See `get-env` for details.
    error!
    macro
    clj
    cljs
    (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.
 
 API: [error] [id-or-opts error] => given error (unconditional)
 Default  kind: `:error`
@@ -174,16 +175,18 @@ Tips:
   - `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
    cljs
    (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 & extra-kvs]})
    "Event" signal call, focused on id + level.
+----------------------------------------
+[1] See `help:signal-flow`    docstring
+[2] See `help:signal-content` docstring
+[3] See `help:signal-options` docstring
    event!
    macro
    clj
    cljs
    (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.
 
-API: [id] [id level-or-opts] => true iff signal call was allowed
+API: [id] [id level-or-opts] => true iff signal 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.).
+When filtering conditions are met [1], creates a Telemere signal [2] and
+dispatches it to registered handlers for processing (e.g. writing to
+console/file/queue/db, etc.).
 
 Examples:
 
@@ -207,9 +210,9 @@ Tips:
     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
    get-env
    macro
    clj
    cljs
    added in Encore v3.75.0 (2024-01-29)
    (get-env {:keys [as default return]} spec)(get-env {:keys [as default return spec], :or {as :str, return :value}})
    Cross-platform util for embedding flexible environmental config during
+[1] See `help:signal-flow`    docstring
+[2] See `help:signal-content` docstring
+[3] See `help:signal-options` docstring
    get-env
    macro
    clj
    cljs
    added in Encore v3.75.0 (2024-01-29)
    (get-env {:keys [as default return]} spec)(get-env {:keys [as default return spec], :or {as :str, return :value}})
    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,
@@ -339,104 +342,150 @@ improve these docs!
    help:signal-content
    clj
    cljs
    Signals are initially maps with {:keys [inst id ns level data msg_ ...]},
-though they can be modified by call and/or handler middleware.
+improve these docs!
    help:signal-content
    clj
    cljs
    Signals are maps with {:keys [inst id ns level data msg_ ...]},
+though they can be modified by signal and/or handler middleware.
 
-Default keys:
+Default signal keys:
 
-`:schema` - Int version of signal schema (current: 1)
-`:inst`   - 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`)
+`:schema` ------ Int version of signal schema (current: 1)
+`:inst` -------- 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          (common to all  signals created at callsite, contrast with `:uid`)
+`:uid` --------- ?id of signal instance (unique to each signal  created at callsite, contrast with  `:id`)
 
-`:msg`   - Arb user-level message  ?str              given to signal call
-`:data`  - Arb user-level data     ?val (usu. a map) given to signal call
-`:error` - Arb user-level platform ?error [2]        given to signal call
+`:msg` --------- Arb user-level message  ?str              given to signal creator
+`:data` -------- Arb user-level data     ?val (usu. a map) given to signal creator
+`:error` ------- Arb user-level platform ?error [2]        given to signal creator
 
-`:run-form` - Unevaluated ?form given to signal call as `:run`
-`:run-val`  - Successful return ?val of  `:run` ?form
-`:run-nsecs`- ?int nanosecs runtime of   `:run` ?form
-`:end-inst` - Platform ?instant [1] when `:run` ?form completed
+`:run-form` ---- Unevaluated ?form given to signal creator as `:run`
+`:run-val` ----- Successful return ?val of  `:run` ?form
+`:run-nsecs` --- ?int nanosecs runtime of   `:run` ?form
+`:end-inst` ---- Platform ?instant [1] when `:run` ?form completed
 
-`: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)
-`:line`     - ?int line      of signal call, same as (:line   location)
-`:column`   - ?int column    of signal call, same as (:column location)
-`:file`     - ?str filename  of signal call, same as (:file   location)
+`: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 creator callsite
+`:ns` ---------- ?str namespace of signal creator callsite, same as (:ns     location)
+`:line` -------- ?int line      of signal creator callsite, same as (:line   location)
+`:column` ------ ?int column    of signal creator callsite, same as (:column location)
+`:file` -------- ?str filename  of signal creator callsite, same as (:file   location)
+`:sample-rate` - ?rate ∈ℝ[0,1] for combined signal AND handler sampling (0.75 => allow 75% of signals, nil => allow all)
 
-`:sample-rate` - ?rate ∈ℝ[0,1] for combined call AND handler sampling (0.75 => allow 75% of signals, nil => allow all)
-
-<extra-kvs> - Arb user-level ?kvs given to signal call
+<kvs> ---------- Arb other user-level ?kvs given to signal creator
 
 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`
    help:signal-formatters
    clj
    cljs
    Common signal formatters include:
+[2] `java.lang.Throwable` or `js/Error`
    help:signal-filters
    clj
    cljs
    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-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.
+
+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!
    help:signal-flow
    clj
    cljs
    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
+
+  4. Signal  middleware does not suppress the signal (return nil)
+  5. Handler middleware does not suppress the signal (return nil)
+
+For 1-3, filtering may depend on (in order):
+  Sample rate → namespace → kind → id → level → when form/fn → rate limit
+
+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
+  `: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
+
+If anything is unclear, please ping me (@ptaoussanis) so that I can
+improve these docs!
    help:signal-formatters
    clj
    cljs
    Common signal formatters include:
   (utils/format-signal-str->fn) {<opts>}) ; For human-readable string output (default)
   (utils/format-signal->edn-fn) {<opts>}) ; For edn  output
   (utils/format-signal->json-fn {<opts>}) ; For JSON output
 
-See relevant docstrings for details.
    help:signal-handling
    clj
    cljs
    A signal will be provided to a handler iff ALL of the following are true:
+See relevant docstrings for details.
    help:signal-handlers
    clj
    cljs
    The handler API consists of the following:
 
-  1. Signal call is allowed by compile-time filters
-  2. Signal call is allowed by runtime      filters
-  3. Handler     is allowed by runtime      filters
+  `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
 
-  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>
+See the relevant docstrings for details.
 
 If anything is unclear, please ping me (@ptaoussanis) so that I can
-improve these docs!
    help:signal-options
    clj
    cljs
    Signal options (shared by `signal!`, `event!`, ...):
+improve these docs!
    help:signal-options
    clj
    cljs
    Signal options (shared by all signal creators):
 
-`:inst`  - 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`)
+`:inst` -------- 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          (common to all  signals created at callsite, contrast with `:uid`)
+`:uid` --------- ?id of signal instance (unique to each signal  created at callsite, contrast with  `:id`)
 
-`:msg`   - Arb user-level ?message to incl. in signal: str or vec of strs to join (with `\space`)
-`:data`  - Arb user-level ?data    to incl. in signal: usu. a map
-`:error` - Arb user-level ?error   to incl. in signal: platform error [2]
+`:msg` --------- Arb user-level ?message to incl. in signal: str or vec of strs to join (with `\space`)
+`:data` -------- Arb user-level ?data    to incl. in signal: usu. a map
+`: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!)
+`:run` --------- ?form     to execute UNCONDITIONALLY; will incl. `:run-value` 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!)
 
-`: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
+`: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)
+`:elidable?` --- Should signal 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?
+`:when` -------- Arb ?form; when present, form must return truthy to allow signal
+`:rate-limit` -- ?spec as given to `taoensso.telemere/rate-limiter`, see its docstring for details
+`:middleware` -- ?[(fn [signal])=>modified-signal ...] signal middleware
+`:trace?` ------ Should tracing be enabled for `:run` form?
 
-<extra-kvs> - Arb user-level ?kvs to incl. in signal
+<kvs> ---------- Arb other user-level ?kvs to incl. in signal
 
 If anything is unclear, please ping me (@ptaoussanis) so that I can improve these docs!
 
 [1] `java.time.Instant`   or `js/Date`
 [2] `java.lang.Throwable` or `js/Error`
    level-aliases
    clj
    cljs
    Map of {<level-keyword> <level-integer>} aliases.
-
    log!
    macro
    clj
    cljs
    (log! msg)(log! level msg)(log! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & extra-kvs]} msg)
    "Log" signal call, focused on message + level.
+
    log!
    macro
    clj
    cljs
    (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, focused on message + level.
 
-API: [msg] [level-or-opts msg] => true iff signal call was allowed.
+API: [msg] [level-or-opts msg] => true iff signal 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.).
+When filtering conditions are met [1], creates a Telemere signal [2] and
+dispatches it to registered handlers for processing (e.g. writing to
+console/file/queue/db, etc.).
 
 Examples:
 
@@ -460,9 +509,9 @@ Tips:
   - 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
    msg-skip
    clj
    cljs
    For use within signal message vectors.
+[1] See `help:signal-flow`    docstring
+[2] See `help:signal-content` docstring
+[3] See `help:signal-options` docstring
    msg-skip
    clj
    cljs
    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.:
 
@@ -509,13 +558,17 @@ still registered.
    set-kind-filter!
    clj
    cljs
    (set-kind-filter! kind-filter)
    Sets signal call kind filter based on given `kind-filter` spec.
+  - {:allow <spec> :deny <spec>} with specs as above.
+    If present, `:allow` spec MUST     match, AND
+    If present, `:deny`  spec MUST NOT match.
    set-kind-filter!
    clj
    cljs
    (set-kind-filter! kind-filter)
    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
    cljs
    (set-middleware! root-val)
    Set `*middleware*` var's root (base) value. See `*middleware*` for details.
+  - {:allow <spec> :deny <spec>} with specs as above.
+    If present, `:allow` spec MUST     match, AND
+    If present, `:deny`  spec MUST NOT match.
    set-middleware!
    macro
    clj
    cljs
    (set-middleware! root-val)
    Set `*middleware*` var's root (base) value. See `*middleware*` for details.
 
    set-min-level!
    clj
    cljs
    (set-min-level! min-level)(set-min-level! kind min-level)(set-min-level! kind ns-filter min-level)
    Sets minimum signal call level based on given `min-level` spec.
 `min-level` may be:
 
@@ -533,33 +586,36 @@ will apply only for that signal kind.
    set-var-root!
    macro
    clj
    cljs
    added in Encore v3.75.0 (2024-01-29)
    (set-var-root! var-sym root-val)
    Sets root binding (value) of the var identified by given symbol, and returns
-the new value. Cross-platform. See also `update-var-root!`.
    shut-down-handlers!
    clj
    cljs
    (shut-down-handlers!)(shut-down-handlers! timeout-msecs__9291__auto__)
    Shuts down all registered signal handlers and returns
+  - {:allow <spec> :deny <spec>} with specs as above.
+    If present, `:allow` spec MUST     match, AND
+    If present, `:deny`  spec MUST NOT match.
    set-var-root!
    macro
    clj
    cljs
    added in Encore v3.75.0 (2024-01-29)
    (set-var-root! var-sym root-val)
    Sets root binding (value) of the var identified by given symbol, and returns
+the new value. Cross-platform. See also `update-var-root!`.
    shut-down-handlers!
    clj
    cljs
    (shut-down-handlers!)(shut-down-handlers! timeout-msecs__9337__auto__)
    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!
    macro
    clj
    cljs
    (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 & extra-kvs]})
    Low-level generic signal call.
+Clj only: `shut-down-handlers!` is called automatically on JVM shutdown.
    signal!
    macro
    clj
    cljs
    (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]
 Default  kind: none (optional)
 Default level: none (must be provided)
 
-When conditions are met [1], creates a Telemere signal [2] and dispatches it to
-registered handlers for processing (writing to console/disk/db, etc.).
+When filtering conditions are met [1], creates a Telemere signal [2] 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 call conditions were met.
+                   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 provided wrapper macros optimized for ease-of-use in
+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 call was allowed
-  `log!`   - (message + opts/level) => true iff signal call was allowed
+  `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)
@@ -569,17 +625,18 @@ Tips:
   - Test using `with-signal`: (with-signal (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
    cljs
    (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 & extra-kvs]} form)
    "Spy" signal call, focused on form + level.
+---------------------------------------
+[1] See `help:signal-flow`    docstring
+[2] See `help:signal-content` docstring
+[3] See `help:signal-options` docstring
    spy!
    macro
    clj
    cljs
    (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.
 
 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.).
+When filtering conditions are met [1], creates a Telemere signal [2] and
+dispatches it to registered handlers for processing (e.g. writing to
+console/file/queue/db, etc.).
 
 Examples:
 
@@ -601,16 +658,16 @@ Tips:
   - 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.
+  - Execution of `form` arg 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! ...)).
 
-----------------------------------------
-[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!
+---------------------------------------
+[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!
 Resets `System/out` and `System/err` to their original value (prior to any
 `streams->telemere!` call).
    streams->telemere!
    clj
    (streams->telemere!)(streams->telemere! {:keys [out err], :or {out default-out-opts, err default-err-opts}})
    Experimental, subject to change without notice!
 
@@ -624,14 +681,20 @@ See also:
   `with-out->telemere`,
   `with-err->telemere`,
   `with-streams->telemere`.
    tools-logging->telemere!
    clj
    (tools-logging->telemere!)
    Configures `clojure.tools.logging` to use Telemere as its logging implementation.
-
    trace!
    macro
    clj
    cljs
    (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 & extra-kvs]} form)
    "Trace" signal call, focused on form + id.
+
+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!
    macro
    clj
    cljs
    (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.
 
 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.).
+When filtering conditions are met [1], creates a Telemere signal [2] and
+dispatches it to registered handlers for processing (e.g. writing to
+console/file/queue/db, etc.).
 
 Examples:
 
@@ -653,7 +716,7 @@ Tips:
   - 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.
+  - Execution of `form` arg may create additional (nested) signals.
     Each signal's `:parent` key will indicate its immediate parent.
 
   - Can be useful to wrap with `catch->error!`:
@@ -663,10 +726,10 @@ 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-handling` docstring
-[2] See `help:signal-content`  docstring
-[3] See `help:signal-options`  docstring
    uncaught->error!
    macro
    clj
    cljs
    (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 & extra-kvs]})
    Uses `uncaught->handler!` so that `error!` will be called for
+---------------------------------------
+[1] See `help:signal-flow`    docstring
+[2] See `help:signal-content` docstring
+[3] See `help:signal-options` docstring
    uncaught->error!
    macro
    clj
    cljs
    (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
 uncaught JVM errors.
 
 See `uncaught->handler!` and `error!` for details.
    uncaught->handler!
    clj
    (uncaught->handler! handler)
    Sets JVM's global `DefaultUncaughtExceptionHandler` to given
@@ -694,12 +757,12 @@ See `*middleware*` for details.
    with-ns-filter
    macro
    clj
    cljs
    (with-ns-filter ns-filter form)
    Executes form with given signal call namespace filter in effect.
 See `set-ns-filter!` for details.
    with-out->telemere
    macro
    clj
    cljs
    (with-out->telemere form)(with-out->telemere opts form)
    Executes form with `*out*` bound to flush to Telemere signals with given opts.
 
    with-signal
    macro
    clj
    cljs
    (with-signal form)(with-signal trap-signals? form)(with-signal raw-msg? trap-signals? form)
    Experimental.
-Executes given form, trapping errors. Returns the LAST signal triggered by form.
+Executes given form, trapping errors. Returns the LAST signal created by form.
 Useful for tests/debugging.
 
 Options:
   `trap-signals?` (default: false)
-    Should ALL signals triggered by form be trapped to prevent normal dispatch
+    Should ALL signals created by form be trapped to prevent normal dispatch
     to registered handlers?
 
   `raw-msg?` (default: false)
diff --git a/taoensso.telemere.timbre.cljs.html b/taoensso.telemere.timbre.cljs.html
index 5b2496f..c83903f 100644
--- a/taoensso.telemere.timbre.cljs.html
+++ b/taoensso.telemere.timbre.cljs.html
@@ -1,4 +1,4 @@
 
-taoensso.telemere.timbre documentation
    Namespaces
    Public Vars
      taoensso.telemere.timbre
      Main Timbre macros, reimplemented on top of Telemere.
+taoensso.telemere.timbre documentation
      Namespaces
      Public Vars
        taoensso.telemere.timbre
        Main Timbre macros, reimplemented on top of Telemere.
 Intended to help ease migration from Timbre to Telemere.
        
\ No newline at end of file
diff --git a/taoensso.telemere.timbre.html b/taoensso.telemere.timbre.html
index baf1cc0..b0477b5 100644
--- a/taoensso.telemere.timbre.html
+++ b/taoensso.telemere.timbre.html
@@ -1,6 +1,6 @@
 
-taoensso.telemere.timbre documentation
        Namespaces
        Public Vars
        taoensso.telemere.timbre
        Main Timbre macros, reimplemented on top of Telemere.
+taoensso.telemere.timbre documentation
        Namespaces
        Public Vars
        taoensso.telemere.timbre
        Main Timbre macros, reimplemented on top of Telemere.
 Intended to help ease migration from Timbre to Telemere.
        debug
        macro
        clj
        (debug & args)
        Prefer `telemere/log!`, etc.
 
        debugf
        macro
        clj
        (debugf & args)
        Prefer `telemere/log!`, etc.
 
        error
        macro
        clj
        (error & args)
        Prefer `telemere/log!`, etc.
diff --git a/taoensso.telemere.utils.cljs.html b/taoensso.telemere.utils.cljs.html
index 8b22089..c503921 100644
--- a/taoensso.telemere.utils.cljs.html
+++ b/taoensso.telemere.utils.cljs.html
@@ -1,6 +1,6 @@
 
-taoensso.telemere.utils documentation
        Namespaces
        Public Vars
        taoensso.telemere.utils
        Misc utils useful for Telemere handlers, middleware, etc.
+taoensso.telemere.utils documentation
        Namespaces
        Public Vars
        taoensso.telemere.utils
        Misc utils useful for Telemere handlers, middleware, etc.
 
        error-in-signal->maps
        clj
        cljs
        (error-in-signal->maps signal)
        Experimental, subject to change.
 Returns given signal with possible `:error` replaced by
 [{:keys [type msg data]} ...] cause chain.
@@ -50,7 +50,7 @@ Defaults to `js.console.log` for unmatched signal levels.
 NB: assumes that `js/console` exists, handler constructors should check first!
        minify-signal
        clj
        cljs
        (minify-signal signal)
        Experimental, subject to change.
 Returns minimal signal map, removing:
   - Keys with nil values, and
-  - Keys with redundant values (`:extra-kvs`, `:location`, `:file`).
+  - Keys with redundant values (`:kvs`, `:location`, `:file`).
 
 Useful when serializing signals to edn/JSON/etc.
        newline
        clj
        cljs
        added in Encore v3.68.0 (2023-09-25)
        Single system newline
 
        pr-edn
        clj
        cljs
        (pr-edn x)
        Prints given arg to an edn string readable with `read-edn`.
diff --git a/taoensso.telemere.utils.html b/taoensso.telemere.utils.html
index 7a8fa61..2389fb8 100644
--- a/taoensso.telemere.utils.html
+++ b/taoensso.telemere.utils.html
@@ -1,6 +1,6 @@
 
-taoensso.telemere.utils documentation
        Namespaces
        Public Vars
        taoensso.telemere.utils
        Misc utils useful for Telemere handlers, middleware, etc.
+taoensso.telemere.utils documentation
        Namespaces
        Public Vars
        taoensso.telemere.utils
        Misc utils useful for Telemere handlers, middleware, etc.
 
        error-in-signal->maps
        clj
        cljs
        (error-in-signal->maps signal)
        Experimental, subject to change.
 Returns given signal with possible `:error` replaced by
 [{:keys [type msg data]} ...] cause chain.
@@ -56,7 +56,7 @@ Returns a (fn format [signal]) that:
 
        minify-signal
        clj
        cljs
        (minify-signal signal)
        Experimental, subject to change.
 Returns minimal signal map, removing:
   - Keys with nil values, and
-  - Keys with redundant values (`:extra-kvs`, `:location`, `:file`).
+  - Keys with redundant values (`:kvs`, `:location`, `:file`).
 
 Useful when serializing signals to edn/JSON/etc.
        newline
        clj
        cljs
        added in Encore v3.68.0 (2023-09-25)
        Single system newline
 
        pr-edn
        clj
        cljs
        (pr-edn x)
        Prints given arg to an edn string readable with `read-edn`.