luciano/telemere
1
0
Fork 0
mirror of https://github.com/taoensso/telemere.git synced 2025-12-16 17:41:12 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

[doc] Add extra docs re: debugging filtering

Browse source
This commit is contained in:
Peter Taoussanis 2025-05-14 10:17:46 +02:00
parent 2e0a2938b7
commit 1bdb667b6c
3 changed files with 21 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
main/resources/docs/signal-options.txt
View file

@ -25,6 +25,7 @@ All options are available for all signal creator calls:
`:coords` ------ Custom ?[line column] to override auto signal callsite info
`:elidable?` --- Should signal be subject to compile-time elision? (default true)
`:allow?` ------ Custom override for usual runtime filtering (true => ALWAYS create signal)
`:trace?` ------ Should tracing be enabled for `:run` form?
`:sample` ------ Sample ?rate ∈ℝ[0,1] for random signal sampling (0.75 => allow 75% of signals, nil => allow all)

6
wiki/1-Getting-started.md
View file

@ -165,7 +165,7 @@ Both have several options, see their docstrings (links above) for details.
## Filtering
A signal will be provided to a handler iff ALL of the following are true:
A signal will be provided to a handler iff **ALL** of the following are true:
- 1. Signal **call filters** pass:
- a. Compile time: sample rate, kind, ns, id, level, when form, rate limit
@ -178,7 +178,9 @@ A signal will be provided to a handler iff ALL of the following are true:
- 3. **Call transform** `(fn [signal]) => ?modified-signal` returns non-nil
- 4. **Handler transform** `(fn [signal]) => ?modified-signal` returns non-nil
> Transform fns provides a flexible way to modify and/or filter signals by arbitrary signal data/content conditions (return nil to skip handling).
> 👉 Transform fns provides a flexible way to modify and/or filter signals by arbitrary signal data/content conditions (return nil to skip handling).
> 👉 Call and handler filters are **additive** - so handlers can be *more* but not *less* restrictive than call filters allow. This makes sense: call filters decide if a signal can be created. Handler filters decide if a particular handler is allowed to handle a created signal.
Quick examples of some basic filtering:

18
wiki/3-Config.md
View file

@ -2,7 +2,7 @@ See below for config by topic-
# Filtering
A signal will be provided to a handler iff ALL of the following are true:
A signal will be provided to a handler iff **ALL** of the following are true:
- 1. Signal **call filters** pass:
- a. Compile time: sample rate, kind, ns, id, level, when form, rate limit
@ -15,10 +15,24 @@ A signal will be provided to a handler iff ALL of the following are true:
- 3. **Call transform** `(fn [signal]) => ?modified-signal` returns non-nil
- 4. **Handler transform** `(fn [signal]) => ?modified-signal` returns non-nil
> Transform fns provides a flexible way to modify and/or filter signals by arbitrary signal data/content conditions (return nil to skip handling).
> 👉 Transform fns provides a flexible way to modify and/or filter signals by arbitrary signal data/content conditions (return nil to skip handling).
> 👉 Call and handler filters are **additive** - so handlers can be *more* but not *less* restrictive than call filters allow. This makes sense: call filters decide if a signal can be created. Handler filters decide if a particular handler is allowed to handle a created signal.
See [`help:filters`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:filters) for more about filtering.
## Debugging filters
Telemere offers a *lot* of filtering control, so real systems can get quite complex. There's a lot of tools to help debug, including:
| Util | |
| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| [`with-signal`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#with-signal) | To see *last* signal created in body |
| [`with-signals`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#with-signals) | To see *all* signals created in body |
| [`get-filters`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#get-filters) | To see all call filters in current context |
| [`without-filters`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#without-filters) | To disable filters in body |
| [`get-handlers-stats`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#get-handlers-stats) | To see handler call stats |
# Signal handlers
See section [4-Handlers](./4-Handlers).