BEFORE this commit:
Telemere captured OpenTelemetry context only when generating
tracing signals (`trace!`, `spy!`, etc.).
AFTER this commit:
Telemere always captures OpenTelemetry context when present.
Motivation for the change:
Telemere users may have spans automatically created by the
OpenTelemetry Java Agent, or manually created by other libs
like clj-otel.
By always capturing the OpenTelemetry context when present,
this lets even non-tracing Telemere signals (like `log!`)
include the relevant trace and span IDs for external tooling.
Thanks to @devurandom for suggesting this, and for helping
debug/identify the necessary changes 🙏
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 this commit:
The Timbre->Telemere appender produced duplicate preamble output
(timestamp, namespace, etc.). Both Timbre AND Telemere were adding
preamble info.
AFTER this commit:
Now ONLY Telemere adds preamble info.
Timbre's `:output-fn` is ignored.
There was unfortunately a bug in the Timbre->Telemere appender that
was producing signals with {:line <num> :column <num> ...} keys instead
of the expected {:coords [<line-num> <column-num>] ...} key.
This commit fixes the mistake, which should help fix issues with
any downstream middleware or handlers that expect a `:coords` key.
Unfortunately this fix could break a small minority of users that
have come to expect `:line` and `:column` keys on their Timbre signals
(none of the built-in middleware or handlers do).
Apologies for the trouble!
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.
Motivation:
These vars aren't used often, are are supplementary rather than
a key part of Telemere's API.
Having them listed in the API docs adds to the noise there and makes
the API seem more overwhelming than necessary.
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.
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.
