mirror of
https://github.com/taoensso/telemere.git
synced 2025-12-17 01:51:10 +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!
28 lines
1.2 KiB
Text
28 lines
1.2 KiB
Text
Low-level "generic" signal creator for creating signals of any "kind".
|
|
Takes a single map of options [2] with compile-time keys.
|
|
|
|
Default kind: `:generic` (feel free to change!)
|
|
Default level: `:info`
|
|
Returns:
|
|
- If given `:run` form: unconditionally returns run value, or rethrows run error.
|
|
- Otherwise: returns true iff signal was created (allowed by filtering).
|
|
|
|
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.).
|
|
|
|
Generic signals are fairly low-level and useful mostly for library authors or
|
|
advanced users writing their own wrapper macros. Regular users will typically
|
|
prefer one of the higher-level signal creators optimized for ease-of-use in
|
|
common cases [1].
|
|
|
|
Tips:
|
|
|
|
- Test using `with-signal`: (with-signal (signal! ...)).
|
|
- Supports the same options [2] as other signals [1].
|
|
|
|
----------------------------------------------------------------------
|
|
[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-filters` - (by ns/kind/id/level, sampling, etc.)
|