mirror of
https://github.com/taoensso/telemere.git
synced 2026-01-06 17:19:49 +00:00
ac5feb4723
This change will only affect rare advanced users that depend on the return value of `log!` or `event!`. For all other users this will be a non-breaking change. Before this commit: `log!` and `event!` returned true iff signal was allowed. After this commit: `log!` and `event!` now ALWAYS return nil. `log!?` and `event!?` have been added that keep the old behaviour. Motivation: It's pretty rare to use the return value when generating log or event signals. I originally included the return value since it CAN be handy, and I figured it could just be ignored by those that don't need it. But #53 showed that there's a downside I hadn't anticipated - some users may actually depend on / prefer a nil return to prevent accidentally affecting program flow. I think that's a legitimate enough concern to still make a change now before v1 final. Apologies for the nuissance!
33 lines
1.6 KiB
Text
33 lines
1.6 KiB
Text
Call a Telemere signal creator to conditionally create a signal at that callsite.
|
|
|
|
When filtering conditions are met [4], the call creates a Telemere signal [3]
|
|
and dispatches it to registered handlers for processing (e.g. writing to
|
|
console/file/queue/db, etc.).
|
|
|
|
Telemere doesn't make a hard distinction between different kinds of signals
|
|
(log, event, error, etc.) - they're all just plain Clojure/Script maps with
|
|
various keys:
|
|
|
|
- All signal creators offer the same options [2], and
|
|
- All signal kinds can contain the same content [3]
|
|
|
|
Creators vary only in in their default options and call APIs (expected args
|
|
and return values), making them more/less convenient for certain use cases:
|
|
|
|
`log!` ------------- ?level + msg => nil
|
|
`event!` ----------- id + ?level => nil
|
|
`trace!` ----------- ?id + run => run result (value or throw)
|
|
`spy!` ------------- ?level + run => run result (value or throw)
|
|
`error!` ----------- ?id + error => given error
|
|
`catch->error!` ---- ?id + run => run value or ?catch-val
|
|
`uncaught->error!` - ?id => nil
|
|
`signal!` ---------- opts => allowed? / run result (value or throw)
|
|
|
|
- `log!` and `event!` are both good default/general-purpose signal creators.
|
|
- `log!` emphasizes messages, while `event!` emphasizes ids.
|
|
- `signal!` is the generic creator, and is used by all the others.
|
|
|
|
----------------------------------------------------------------------
|
|
[2] See `help:signal-options` - {:keys [kind level id data ...]}
|
|
[3] See `help:signal-content` - {:keys [kind level id data ...]}
|
|
[4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.)
|