mirror of
https://github.com/taoensso/telemere.git
synced 2026-01-20 22:09:00 +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!
38 lines
1.5 KiB
Text
38 lines
1.5 KiB
Text
"Event" signal creator, emphasizing id + (optional level).
|
|
|
|
Default kind: `:event`
|
|
Default level: `:info`
|
|
Returns:
|
|
- For `event!` variant: nil, unconditionally.
|
|
- For `event!?` variant: 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.).
|
|
|
|
Examples:
|
|
|
|
(event! ::my-id) ; %> {:kind :event, :level :info, :id ::my-id ...}
|
|
(event! ::my-id :warn) ; %> {... :level :warn ...}
|
|
(event! ::my-id
|
|
{:let [x "x"] ; Available to `:data` and `:msg`
|
|
:data {:x x}
|
|
:msg ["My msg:" x]}) ; %> {... :data {x "x"}, :msg_ "My msg: x" ...}
|
|
|
|
Tips:
|
|
|
|
- Test using `with-signal`: (with-signal (event! ...)).
|
|
- Supports the same options [2] as other signals [1].
|
|
|
|
- `log!` and `event!` are both good default/general-purpose signal creators.
|
|
- `log!` emphasizes messages, while `event!` emphasizes ids.
|
|
|
|
- Has a different 2-arity arg order to all other signals!
|
|
Mnemonic: the arg that's typically larger is *always* in the rightmost
|
|
position, and for `event!` that's the `level-or-opts` arg.
|
|
|
|
----------------------------------------------------------------------
|
|
[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.)
|