mirror of
https://github.com/taoensso/telemere.git
synced 2025-12-27 21:58:26 +00:00
839143167b
Previously:
It was possible to provide a vector of middleware fns when creating
signals or adding handlers, e.g.:
(event! ::ev-id1 {:middleware [fn1 fn2 ...]}),
(add-handler! ::handler-id1 <handler-fn> {:middleware [fn1 fn2 ...]})
After this commit:
Middleware is always expected to be a single fn, or nil.
A `comp-middleware` util has been added to make it easy to compose multiple
middleware fns into one.
Motivation:
The previous (auto-composition) behaviour was nice when adding handlers,
but incurred a (small but non-trivial) runtime cost when creating signals.
The actual benefit (convenience) of auto-composition is very small, so
I've decided to just remove this feature and add the `comp-middleware` util.
Note that I ruled out the option of doing auto-comp only when adding handlers
since that've meant an inconsistency and so complexity for little benefit.
37 lines
2.3 KiB
Text
37 lines
2.3 KiB
Text
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 (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]
|
|
|
|
`: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 creator callsite location
|
|
|
|
`: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)
|
|
`: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` -- Optional (fn [signal]) => ?modified-signal to apply when signal is created
|
|
`:trace?` ------ Should tracing be enabled for `:run` form?
|
|
|
|
<kvs> ---------- Other arb user-level ?kvs to incl. in signal. Typically NOT included in
|
|
handler output, so a great way to provide custom data/opts for use
|
|
(only) by custom middleware/handlers.
|
|
|
|
handler-specific data that can just be ignored by other handlers
|
|
|
|
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`
|