telemere/resources/signal-docstrings/trace!.txt

"Trace" signal creator, emphasizing form + id.

API: [form] [id-or-opts form] => form's result (value/throw) (unconditional)
Default  kind: `:trace`
Default level: `:info` (intentionally NOT `:trace`!)

When filtering conditions are met [4], creates a Telemere signal [3] and
dispatches it to registered handlers for processing (e.g. writing to
console/file/queue/db, etc.).

Examples:

  (trace! (+ 1 2))         ; %> {:kind :trace, :level :info, :run-form '(+ 1 2),
                           ;     :run-val 3, :run-nsecs <int>, :parent {:keys [id uid]} ...
                           ;     :msg "(+ 1 2) => 3" ...}
  (trace! ::my-id (+ 1 2)) ; %> {... :id ::my-id ...}
  (trace!
    {:let  [x "x"] ; Available to `:data` and `:msg`
     :data {:x x}}

    (+ 1 2)) ; %> {... :data {x "x"}, :msg_ "My msg: x" ...}

Tips:

  - Test using `with-signal`: (with-signal (trace! ...)).
  - Supports the same options [2] as other signals [1].

  - Identical to `spy!`, but emphasizing form + id rather than form + level.

  - Useful for debugging/monitoring forms, and tracing (nested) execution flow.
  - Execution of `form` arg may create additional (nested) signals.
    Each signal's `:parent` key will indicate its immediate parent.

  - Can be useful to wrap with `catch->error!`:
      (catch->error! ::error-id (trace! ...)).

  - Default level is `:info`, not `:trace`! The name "trace" in "trace signal"
    refers to the general action of tracing program flow rather than to the
    common logging level of the same name.

-------------------------------------------------------------------
[1] See `help:signal-creators` - (`signal!`, `log!`, `event!`, ...)
[2] See `help:signal-options`  - {:keys [kind level id data ...]}
[3] See `help:signal-content`  - {:keys [kind level id data ...]}
[4] See `help:signal-flow`     - (filters, handling, etc.)