This is a BREAKING change for the small minority of users that:
1. Are using the `taoensso.telemere.slf4j` backend, AND
2. Are using the low-level `:slf4j/args` or `:slf4j/marker-names`
values in signal `:data`
BEFORE this commit:
SLF4J signals contain:
{:data {:slf4j/kvs {...},
:slf4j/args [...],
:slf4j/marker-names #{...}},
...}.
AFTER this commit:
SLF4J signals contain:
{:data {:slf4j/kvs {...}},
:kvs {:slf4j/args <Object[]>,
:slf4j/markers #{...}},
...}
So:
- [:data :slf4j/marker-names] has moved to [:kvs :slf4j/markers].
- [:data :slf4j/args] has moved to [:kvs :slf4j/args],
and is now an Object[] rather than vector.
Motivation for the change:
The new behaviour is a more sensible default.
Basically: anything in `:data` is included by default in output.
But :slf4j/args are generally anyway already in the signal's formatted
message, so this ends up just creating duplicate output.
Likewise markers are generally used more for filtering/xfns than for
output labelling, so excluding them from default output is sensible.
This is a BREAKING change but only relevant for a TINY minority
of users that:
1. Are using the `taoensso.telemere.timbre` API shim, AND
2. Are using the low-level `:vargs` value in signal `:data`
BEFORE this commit:
The taoensso.telemere.timbre shim API produces signals with
{:data {:vargs [...]}, ...} with `:vargs` a vector of raw args
provided by Timbre.
AFTER this commit:
The taoensso.telemere.timbre shim API produces signals with
{:kvs {:timbre/vargs [...]}, ...} with `:vargs` a vector of raw
args provided by Timbre.
I.e. [:data :vargs] has been moved to [:kvs :timbre/vargs].
Motivation for the change:
The new behaviour is a more sensible default.
Basically: anything in `:data` is included by default in output.
But vargs are generally anyway already in the signal's formatted
message, so this ends up just creating duplicate output.
Before commit: {:run nil} didn't register as a tracing signal
After commit: {:run nil} correctly registers as a tracing signal with `nil` form
nil forms aren't typically useful or used, but can come up by accident
so it's important to handle these correctly.
The `trace!` docstring also promises that the return value will always be
equal to the given input. This didn't hold before.
Users caught by this change should receive a clear compile-time error.
Apologies for the nuissance!! This change is part of a final review
of names before the release of v1 final.
Users caught by this change should receive a clear compile-time error.
Apologies for the nuissance!! This change is part of a final review
of names before the release of v1 final.
Motivations:
- "xfn" is a lot shorter than "middleware", making it more
convenient to use at signal calls, compare:
(log! {:middleware my-fn} "msg")
(log! {:xfn my-fn} "msg"}
- "middleware" was originally chosen to match Timbre's terminology,
but actually carries some misleading connotations that in hindsight
are probably better avoided while we still have the chance to change
this.
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!
This is the input-side change related to [1], and only
affects folks who've been providing custom callsite info to
Telemere signals (usually in the context of wrapper macros).
To provide custom callsite info BEFORE this commit:
(tel/signal! {:location {:ns "my-ns", :line 10, :column 20}})
To provide custom callsite info AFTER this commit:
(tel/signal! {:ns "my-ns", :coords [10 20]})
Motivation for the new override API:
- It's shorter and cleaner.
- It's less likely to cause confusion since it avoids the
redundant signal keys (signals previously contained callsite
info in 2 duplicate places).
- The underlying implementation is simpler.
- The util for manually getting coords is easier to use and doesn't
require macro-time environment info, making it easier for folks
to write wrapper macros that include line + column info.
- When embedded, the new callsite info is shorter and easier for
Cljs advanced compilation to de-duplicate (so helps reduce .js
build size).
[1] Commit 1f99f7186b
This is a BREAKING change to get in before v1 final.
Signal keys BEFORE this commit:
`:location` ---- ?{:keys [ns file line column]} signal creator callsite
`:ns` ---------- ?str namespace of signal creator callsite, same as (:ns location)
`:line` -------- ?int line of signal creator callsite, same as (:line location)
`:column` ------ ?int column of signal creator callsite, same as (:column location)
`:file` -------- ?str filename of signal creator callsite, same as (:file location)
Signal keys AFTER this commit:
`:ns` ---------- ?str namespace of signal creator callsite
`:coords` ------ ?[line column] of signal creator callsite
Motivation for the breaking change:
The new callsite schema is simpler to use/override, reduces noise, and can reduce
code expansion size (and so Cljs build size).
- `:file` was rarely useful, but often added large embedded strings.
- `:location` was redundant, and often difficult for Closure's
advanced build to properly de-duplicate.
This schema will be shared by Truss v2 and Tufte v3.
