From 824f8e3d534fdba1aa26b017ba77ffaa425eebe6 Mon Sep 17 00:00:00 2001 From: Peter Taoussanis Date: Thu, 27 Feb 2025 10:00:05 +0100 Subject: [PATCH] [doc] Rename "signal filters" -> "call filters", etc. The new terminology hopefully makes the distinction clearer between call filters and handler filters, etc. --- .../resources/signal-docstrings/signal-content.txt | 6 +++--- .../resources/signal-docstrings/signal-options.txt | 6 +++--- wiki/1-Getting-started.md | 10 ++++++---- wiki/2-Architecture.md | 2 +- wiki/3-Config.md | 14 +++++++++----- wiki/7-Tips.md | 4 ++-- 6 files changed, 24 insertions(+), 18 deletions(-) diff --git a/main/resources/signal-docstrings/signal-content.txt b/main/resources/signal-docstrings/signal-content.txt index 382fd04..140ef04 100644 --- a/main/resources/signal-docstrings/signal-content.txt +++ b/main/resources/signal-docstrings/signal-content.txt @@ -19,12 +19,12 @@ Default signal keys: `:run-nsecs` --- ?int nanosecs runtime of `:run` ?form `:end-inst` ---- Platform ?instant [1] when `:run` ?form completed -`:ctx` --------- ?val of `*ctx*` (arb app-level state) when signal was created `:parent` ------ ?{:keys [id uid]} of parent signal, present in nested signals when tracing `:root` -------- ?{:keys [id uid]} of root signal, present in nested signals when tracing +`:ctx` --------- ?val of `*ctx*` (arb app-level state) when signal was created -`:ns` ---------- ?str namespace of signal creator callsite -`:coords` ------ ?[line column] of signal creator callsite +`:ns` ---------- ?str namespace of signal callsite +`:coords` ------ ?[line column] of signal callsite `:host` -------- (Clj only) {:keys [name ip]} info for network host `:thread` ------ (Clj only) {:keys [name id group]} info for thread that created signal diff --git a/main/resources/signal-docstrings/signal-options.txt b/main/resources/signal-docstrings/signal-options.txt index 816585a..c31f627 100644 --- a/main/resources/signal-docstrings/signal-options.txt +++ b/main/resources/signal-docstrings/signal-options.txt @@ -1,5 +1,5 @@ Signal options are provided as a map with COMPILE-TIME keys. -All options are available for all signal creators: +All options are available for all signal creator calls: `:inst` -------- Platform instant [1] when signal was created, ∈ #{nil :auto <[1]>} `:level` ------- Signal level ∈ #{ :trace :debug :info :warn :error :fatal :report ...} @@ -21,8 +21,8 @@ All options are available for all signal creators: `:ctx` --------- Custom ?val to override auto (dynamic `*ctx*`) in signal, as per `with-ctx` `:ctx+` -------- Custom ?val to update auto (dynamic `*ctx*`) in signal, as per `with-ctx+` -`:ns` ---------- Custom ?str namespace to override auto signal creator callsite -`:coords` ------ Custom ?[line column] to override auto signal creator callsite +`:ns` ---------- Custom ?str namespace to override auto signal callsite info +`:coords` ------ Custom ?[line column] to override auto signal callsite info `:elidable?` --- Should signal be subject to compile-time elision? (Default: true) `:sample-rate` - ?rate ∈ℝ[0,1] for signal sampling (0.75 => allow 75% of signals, nil => allow all) diff --git a/wiki/1-Getting-started.md b/wiki/1-Getting-started.md index 2ac7068..9f95a9e 100644 --- a/wiki/1-Getting-started.md +++ b/wiki/1-Getting-started.md @@ -167,16 +167,18 @@ Both have several options, see their docstrings (links above) for details. A signal will be provided to a handler iff ALL of the following are true: -- 1. Signal **creation** is allowed by **signal filters**: +- 1. Signal **call filters** pass: - a. Compile time: sample rate, kind, ns, id, level, when form, rate limit - b. Runtime: sample rate, kind, ns, id, level, when form, rate limit -- 2. Signal **handling** is allowed by **handler filters**: +- 2. Signal **handler filters** pass: - a. Compile time: not applicable - b. Runtime: sample rate, kind, ns, id, level, when fn, rate limit -- 3. **Signal middleware** `(fn [signal]) => ?modified-signal` does not return nil -- 4. **Handler middleware** `(fn [signal]) => ?modified-signal` does not return nil +- 3. **Call middleware** `(fn [signal]) => ?modified-signal` returns non-nil +- 4. **Handler middleware** `(fn [signal]) => ?modified-signal` returns non-nil + +> Middleware provides a flexible way to modify and/or filter signals by arbitrary signal data/content conditions (return nil to skip). Quick examples of some basic filtering: diff --git a/wiki/2-Architecture.md b/wiki/2-Architecture.md index c30528e..7419060 100644 --- a/wiki/2-Architecture.md +++ b/wiki/2-Architecture.md @@ -16,4 +16,4 @@ This flow is visualized below: Telemere signal flowchart - `A/sync queue` semantics are specified via [handler dispatch options](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:handler-dispatch-options). -- The shared **signal middleware cache** is super useful when doing signal transformations that are expensive and/or involve side effects (like syncing with another service/db to get a unique tx id, etc.). \ No newline at end of file +- The shared **call middleware cache** is super useful when doing signal transformations that are expensive and/or involve side effects (like syncing with another service/db to get a unique tx id, etc.). \ No newline at end of file diff --git a/wiki/3-Config.md b/wiki/3-Config.md index 24b2dac..4c71843 100644 --- a/wiki/3-Config.md +++ b/wiki/3-Config.md @@ -4,16 +4,18 @@ See below for config by topic- A signal will be provided to a handler iff ALL of the following are true: -- 1. Signal **creation** is allowed by **signal filters**: +- 1. Signal **call filters** pass: - a. Compile time: sample rate, kind, ns, id, level, when form, rate limit - b. Runtime: sample rate, kind, ns, id, level, when form, rate limit -- 2. Signal **handling** is allowed by **handler filters**: +- 2. Signal **handler filters** pass: - a. Compile time: not applicable - b. Runtime: sample rate, kind, ns, id, level, when fn, rate limit -- 3. **Signal middleware** `(fn [signal]) => ?modified-signal` does not return nil -- 4. **Handler middleware** `(fn [signal]) => ?modified-signal` does not return nil +- 3. **Call middleware** `(fn [signal]) => ?modified-signal` returns non-nil +- 4. **Handler middleware** `(fn [signal]) => ?modified-signal` returns non-nil + +> Middleware provides a flexible way to modify and/or filter signals by arbitrary signal data/content conditions (return nil to skip). See [`help:filters`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:filters) for more about filtering. @@ -126,7 +128,7 @@ Telemere and Tufte work great together: ## Truss -> [Truss](https://www.taoensso.com/truss) is an assertions micro-library for Clojure/Script by the author of Telemere. +> [Truss](https://www.taoensso.com/truss) is a micro toolkit for Clojure/Script errors by the author of Telemere. Telemere can easily incorporate Truss assertion failure information in its signals, just like any other (error) data. @@ -135,3 +137,5 @@ The [`catch->error!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/tao ```clojure (t/catch->error! ) ``` + +Telemere also uses [Truss contextual exceptions](https://cljdoc.org/d/com.taoensso/truss/CURRENT/api/taoensso.truss#ex-info) when relevant. \ No newline at end of file diff --git a/wiki/7-Tips.md b/wiki/7-Tips.md index a08373b..aaa568e 100644 --- a/wiki/7-Tips.md +++ b/wiki/7-Tips.md @@ -80,9 +80,9 @@ Consider the [differences](https://www.youtube.com/watch?v=oyLBGkS5ICk) between This way you can see all your ids in one place, and precise info on when ids were added/removed/changed. -- Use **signal middleware** to your advantage. +- Use **signal call middleware** to your advantage. - The result of signal middleware is cached and *shared between all handlers* making it an efficient place to transform signals. For this reason - prefer signal middleware to handler middleware when possible/convenient. + The result of call middleware is cached and *shared between all handlers* making it an efficient place to transform signals. For this reason - prefer signal middleware to handler middleware when possible/convenient. - Signal and handler **sampling is multiplicative**.