telemere/main/resources/docs/signal-options.txt

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, LAZY! [3]
`: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) and LAZILY [3], before establishing `:let` ?binding
`:let` --------- ?bindings to establish conditionally (iff signal allowed) and LAZILY [3], 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)
`: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)
`:when` -------- Arb ?form; when present, form must return truthy to allow signal
`:limit` ------- Rate limit ?spec given to `taoensso.telemere/rate-limiter`, see its docstring for details
`:limit-by` ---- When present, rate limits will be enforced independently for each value (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. LAZY! [3]

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`
[3] Most Telemere signal content is evaluated CONDITIONALLY (iff signal allowed),
    LAZILY (when signal is created), and on the HANDLING THREAD (not logging thread).
    This allows efficient filtering, better control+monitoring of back pressure,
    conditional effects, etc. Ref. <https://www.taoensso.com/telemere/flow> for visual!