mirror of
https://github.com/taoensso/telemere.git
synced 2026-02-15 07:45:17 +00:00
7cccf672f5
Users caught by this change should receive a clear compile-time error.
Apologies for the nuissance!! This change is part of a final review
of names before the release of v1 final.
Motivations:
- "xfn" is a lot shorter than "middleware", making it more
convenient to use at signal calls, compare:
(log! {:middleware my-fn} "msg")
(log! {:xfn my-fn} "msg"}
- "middleware" was originally chosen to match Timbre's terminology,
but actually carries some misleading connotations that in hindsight
are probably better avoided while we still have the chance to change
this.
44 lines
2.9 KiB
Text
44 lines
2.9 KiB
Text
Signal options are provided as a map with COMPILE-TIME keys.
|
|
All options are available for all signal creator calls:
|
|
|
|
`:inst` -------- Platform instant [1] when signal was created, ∈ #{nil :auto <[1]>}
|
|
`:level` ------- Signal level ∈ #{<int> :trace :debug :info :warn :error :fatal :report ...}
|
|
`:kind` -------- Signal ?kind ∈ #{nil :event :error :log :trace :spy <app-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`)
|
|
Defaults to `:auto` for tracing signals, and nil otherwise
|
|
|
|
`:msg` --------- Arb app-level ?message to incl. in signal: str or vec of strs to join (with `\space`), may be a delay
|
|
`:data` -------- Arb app-level ?data to incl. in signal: usu. a map
|
|
`:error` ------- Arb app-level ?error to incl. in signal: platform error [2]
|
|
|
|
`:run` --------- ?form to execute UNCONDITIONALLY; will incl. `:run-val` 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!)
|
|
|
|
`:parent` ------ Custom ?{:keys [id uid]} to override auto (dynamic) parent signal tracing info
|
|
`:root` -------- Custom ?{:keys [id uid]} to override auto (dynamic) root signal tracing info
|
|
`: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 callsite info
|
|
`:coords` ------ Custom ?[line column] to override auto signal callsite info
|
|
|
|
`:elidable?` --- Should signal be subject to compile-time elision? (Default: true)
|
|
`:trace?` ------ Should tracing be enabled for `:run` form?
|
|
|
|
`: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
|
|
`:rate-limit-by` When present, rate limits will be enforced independently for each id (any Clojure value!)
|
|
`:xfn` --------- Optional transform (fn [signal]) => ?modified-signal to apply when signal is created, as per `with-xfn`
|
|
`:xfn+` -------- Optional extra transform (fn [signal]) => ?modified-signal to apply when signal is created, as per `with-xfn+`
|
|
|
|
<kvs> ---------- Other arb app-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 transforms/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`
|