mirror of
https://github.com/taoensso/telemere.git
synced 2026-01-06 09:09:50 +00:00
fda22ce80c
This is the input-side change related to [1], and only
affects folks who've been providing custom callsite info to
Telemere signals (usually in the context of wrapper macros).
To provide custom callsite info BEFORE this commit:
(tel/signal! {:location {:ns "my-ns", :line 10, :column 20}})
To provide custom callsite info AFTER this commit:
(tel/signal! {:ns "my-ns", :coords [10 20]})
Motivation for the new override API:
- It's shorter and cleaner.
- It's less likely to cause confusion since it avoids the
redundant signal keys (signals previously contained callsite
info in 2 duplicate places).
- The underlying implementation is simpler.
- The util for manually getting coords is easier to use and doesn't
require macro-time environment info, making it easier for folks
to write wrapper macros that include line + column info.
- When embedded, the new callsite info is shorter and easier for
Cljs advanced compilation to de-duplicate (so helps reduce .js
build size).
[1] Commit 1f99f7186b
43 lines
2.9 KiB
Text
43 lines
2.9 KiB
Text
Signal options are provided as a map with COMPILE-TIME keys.
|
|
All options are available for all signal creators:
|
|
|
|
`: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 creator callsite
|
|
`:coords` ------ Custom ?[line column] to override auto signal creator callsite
|
|
|
|
`: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
|
|
`:rate-limit-by` When present, rate limits will be enforced independently for each id (any Clojure value!)
|
|
`:middleware` -- Optional (fn [signal]) => ?modified-signal to apply when signal is created, as per `with-middleware`
|
|
`:middleware+` - Optional (fn [signal]) => ?modified-signal to apply when signal is created, as per `with-middleware+`
|
|
`:trace?` ------ Should tracing be enabled for `:run` form?
|
|
|
|
<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 middleware/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`
|