📦 Dependencies
Available on Clojars:
- Telemere - main dependency.
- SLF4J provider - additional dependency for users that want their Java logging to go to Telemere.
This project uses Break Versioning.
Release notes
RC5 includes breaking changes (indicated by ➤), apologies!
Big thanks to everyone that's been helping test and give feedback. And as always, please report any unexpected problems on GitHub or the Slack channel 🙏
Thanks for the patience awaiting v1 final! I hope and believe that it'll have been worth the time + effort.
Recent CHANGES
Since v1.0.0-RC1
(2024-10-29)
➤ Changes to API since v1.0.0-RC1
Please read carefully in case you may be affected:
- ➤ [mod] Rename
:rate-limit
->:limit
[f37f54e] (RC5) - ➤ [mod] Rename
:sample-rate
->:sample
[1f4b49a] (RC5) - ➤ [mod] Rename
:middleware
->:xfn
[7cccf67] (RC5) - ➤ [mod]
log!
,event!
now always return nil [ac5feb4] (RC4) - ➤ [mod] Signal content: drop
:location
, add:coords
[fda22ce] (RC3) - ➤ [mod] Signal options: drop
:location
, add:coords
[1f99f71] (RC3) - ➤ [mod] OpenTelemetry: use standard attr names when possible [bb715fb] (RC3)
- [mod] [#39] Discontinued separate "shell" library [096c432] (RC2)
- [mod] Change return value of experimental
with-signals
[cb6a5d9] (RC2) - [mod] Remove rarely-used advanced options from
catch->error!
[0de5c09] (RC2)
Changes to default output since v1.0.0-RC1
- ➤ [mod] [#56]
utils/clean-signal-fn
exclude:schema
by default [c78eb07] (RC5) - ➤ [mod] [#52]
signal-preamble-fn
now ignores nil:kind
(@marksto) [634cc53] (RC4) - [mod] Remove "- " msg separator from default preamble output [d61f6c2] (RC2)
- [mod] Postal handler now uses default preamble fn for email subject [706a8b6] (RC2)
- [mod] Default
signal-content-fn
: omit redundant parent/root id namespaces [55323f1] (RC2) - [mod] Default
signal-content-fn
: swapctx
,kvs
position [b208532] (RC2) - [mod] Default
signal-content-fn
: omit:root
if it's same as parent [0464285] (RC2) - [mod] Omit empty
:data
,:ctx
from signal content output [d78663a] (RC2)
Other changes
- [mod] [#51] Make default console handler sync by default [78ed4d7] (RC4)
- [mod] Update
pr-signal-fn
to useclean-signal-fn
[f703630] (beta 23) - [mod] Rename
taoensso.telemere.api
->taoensso.telemere.shell
[a9005e7] (beta 23) - [mod] Move dep:
com.taoensso/slf4j-telemere
-> com.taoensso/telemere-slf4j [77ed27c] (beta 22) - [mod] Generalize "intake", rename -> "interop" [ef678bc] (beta 20)
- [mod] Make
:host
output opt-in for default signal handlers [88eb521] (beta 20) - [mod] OpenTelemetry handler: rename (generalize) [064ef32] (beta 19)
- [mod] OpenTelemetry handler: revert #10 [599236f] (beta 18)
- [mod] Decrease level of :on-init signals [4d2b5d4] (beta 18)
- [mod] Removed
*auto-stop-handlers?*
var (beta 15) - [mod] Removed
:needs-stopping?
handler dispatch opt (beta 15) - [mod] Cljs handlers MUST now include stop (0) arity (beta 15)
- [mod] Users MUST now manually call
stop-handlers!
(beta 15) - [mod] SLF4J and
tools.logging
signals now have a custom:kind
and no:id
(beta 14) - [mod] Renamed
get-min-level
->get-min-levels
(beta 13) - [mod] Renamed
shut-down-handlers!
->stop-handlers!
(beta 13) - [mod] Changed default handler back-pressure mechanism from
:dropping
to:blocking
(eaiser for most users to understand and detect; override when callingadd-handler!
) (beta 11) - [mod]
pr-signal-fn
now takes only a single opts map (beta 10) - [mod] User-level kvs are no longer included by default in handler output.
:incl-kvs?
option has been added toformat-signal-fn
andpr-signal-fn
(beta 7) - [mod] Middleware must now be a single fn, use
comp-middleware
to create one fn from many (beta 7) - [mod] OpenTelemetry handler is no longer auto added (beta 1)
- [mod] Various API improvements to included handlers and utils
Recent additions
Since v1.0.0-RC1
(2024-10-29)
Misc improvements
- [new] [#57] File handling: make file stream more robust [82f4c31] (RC5)
- [new] Add
log!?
,event!?
[ac5feb4] (RC4) - [new] Alias
keep-callsite
, mention insignal!
docs [bfea515] (RC4) - [new] Use Truss v2 and contextual exceptions when relevant (RC3)
- [new] [#44] Open Telemetry handler: add span kind option (@farcaller) [413cce8] (RC3)
- [new] Reduced Cljs build sizes in some cases (RC3)
- [new] Add
timbre->telemere
appender and update docs [ace6e2d] (RC2) - [new] All signal creators can now take single opts map [d2386d6] (RC2)
- [new] Add
& opts
support tosignal!
,signal-allowed?
[a04f255] (RC2) - [new] Give
signal!
a default kind and level [7532c2e] (RC2) - [new] Better error message when
signal!
given non-map arg [d563ac1] (RC2) - [new] Improve error info on worst-case handler errors [484b3df] (RC2)
- [new] Allow manual
:run-val
override [9dc883d] (RC2) - [new] [#34] Add new
signal-preamble-fn
opts (@Knotschi) [0822217] (RC2) - [new] Alias low-level formatters in utils ns [9dc9a46] (RC2)
Doc improvements
- [doc] [#50] Expand docs for
set-min-level!
(via Encore update) (RC4) - [doc] Mention
:inst
monotonicity [6b0e0b9] (RC4) - [doc] Timbre shim: document different
spy
error handling [1517f30] (RC3) - [doc] [#43] ns filters work for SLF4J logger names (@lvh) [db0498b] (RC3)
- [doc] [#33] Add community examples link to Bling Gist [8cd4ca9] (RC2)
- [doc] Better document pattern of using
trace!
/spy!
withcatch->error!
[5c977a3] (RC2) - [doc] [#35] Emphasize that signal opts must be a compile-time map [55720ac] (RC2)
- [doc] Add FAQ item re:
event!
arg order [822032d] (RC2) - [doc] Document that
:msg
may be a delay [13d9dbf] (RC2)
Earlier improvements
- [new] Add
:ctx+
,:middleware+
signal options [5a8c407] (RC1) - [new] OpenTelemetry handler: try print map vals as EDN [c1e1c1e] (RC1)
- [new] [#28] OpenTelemetry handler: support custom signal attrs [5ef4f12] (RC1)
- [new] Simplify default OpenTelemetry providers code, expose SDK [19548d3] (RC1)
- [new] Add
dispatch-signal!
util [5ac8725] (RC1) - [new]
writeable-file!
: resolve sym links, etc. [9965450] (RC1) - [new] Extend IIFE-wrap to Clj [d0ad99d] (RC1)
- [new] Numerous improvements to docs and examples (RC1)
- [new] Add
:rate-limit-by
option to all signal creators [d9c3583] (beta 23) - [new] Add
clean-signal-fn
util [be55f44] (beta 23) - [new] Add
signal-allowed?
util [d12b0b1] (beta 23) - [new] Allow compile-time config of uid kind [965c227] (beta 23)
- [new] Avoid duplicated trace bodies [c9e84e8] (beta 23)
- [new] Cap length of displayed run-form when tracing [85772f7] (beta 23)
- [new] Added experimental shell API for library authors [ece51b2] (beta 22)
- [new] Auto stop existing handler when replacing it (beta 22)
- [new] Added
"(.*)"
wildcard syntax to kind/ns/id filters (beta 22) - [new] Internal and doc improvements: [8066776], [b4b06f3], [3068ccf] (beta 21)
- [new] OpenTelemetry handler: improve span interop [84957c6] (beta 20)
- [new] OpenTelemetry handler: add experimental trace output [67cb494] (beta 18)
- [new] Improve uid control, switch to nano-style by default [5ab2736] (beta 18)
- [new] Add host info to signal content [1cef195] (beta 18)
- [new] Add extra tracing info to signal content [d635318] (beta 18)
- [new] Ongoing API and wiki doc improvements (beta 15)
- [new] [#5] Added comparison to Mulog (beta 15)
- [new] SLF4J and
tools.logging
signals now have a namespace (from logger name) (beta 14) - [new] Added
get-handlers-stats
(beta 13) - [new]
add-handler!
can now specify per-handler:drain-msecs
(beta 13) - [new] Added
*auto-stop-handlers?*
(beta 13) - [new]
remove-handler!
now auto stops relevant handlers after removal (beta 13) - [new]
with-handler
andwith-handler+
now auto stops relevant handlers after use (beta 12) - [new] (Advanced) Handler fns can now include
:dispatch-opts
metadata, useful for handler authors that want to set defaults for use byadd-handler!
(beta 8) - [new] Added Slack handler (beta 8)
- [new] Added TCP and UDP socket handlers (beta 7)
- [new] Clj signal content now includes
:thread {:keys [group name id]}
key (beta 7) - [new] Added postal (email) handler (beta 5)
- [new] Handlers now block to try drain their signal queues on shutdown (beta 3)
- [new] Rate limiter performance improvements (via Encore) (beta 3)
Recent fixes
Since v1.0.0-RC1
(2024-10-29)
- [fix] [#57] File handling: use nio API to create missing parent dirs [af45ffc] (RC5)
- [fix] [#55] SLF4J signals should include
*ctx*
[79173a6] (RC5) - [fix] [#32] Fix clj-kondo warnings [c60f33e] (RC5)
- [fix] [#52]
signal-preamble-fn
should use host info in signal (@marksto) [410ed89] (RC4) - [fix] Timbre shim: rename
spy!
->spy
(@lvh) [3a9ffc6] (RC3) - [fix] Timbre shim: don't attach empty
:vargs
data [0e642ba] (RC3) - [fix] Fix environment val docs [db26a5d] (RC3)
- [fix]
spy!
docstring typo (@rafd) [35606d9] (RC3) - [fix] Broken signal string representation [8c701d4] (RC2)
- [fix] Trace formatting: always include root info [f522307] (RC2)
- [fix] Trace formatting: properly format nil ids [68a894e] (RC2)
- [fix] [#36] Fix missing cljdoc docstrings [b58ec73] (RC2)
Earlier fixes
- [fix]
signal-opts
: allow map forms as intended [f7a5663] (RC1) - [fix]
uncaught->error!
wasn't working (@benalbrecht) [7f52cb1] (RC1) - [fix] Regression affecting deprecated
rate-limiter*
(beta 25) - [fix] Don't try count non-list tracing bodies [88f7a3c] (beta 24)
- [fix] [#21] Work around issue with use in Cljs
core.async/go
bodies [cbab57b] (beta 23) - [fix] [#20] Wrong :arglists meta on
spy!
[568906c] (beta 23) - [fix] [#18] Support
{:uid :auto}
for non-tracing signal creators [f52a04b] (beta 23) - [fix] Runtime Clj env config now works correctly in uberjars (beta 23)
- [fix] Signal
:line
info missing for some wrapped-macro cases [0f09b79] (beta 22) - [fix] OpenTelemetry handler: use signal callsite Context as root span parent [a8e9230] (beta 19)
- [fix] [#16] OpenTelemetry handler: coerce line attrs (@flyingmachine) [17349a0] (beta 19)
- [fix] Decrease min Java version (11->8) (@flyingmachine) [a1c50f1] (beta 19)
- [fix] Broken handler ns and kind filters [2319423] (beta 16)
- [fix] [#10] OpenTelemetry handler: render keywords as plain strings [6e94215] (beta 15)
- [fix] [#11] OpenTelemetry handler: signals without message fail [863cea1] (beta 15)
- [fix] [#14] File handler: Don't truncate gzip output [2d4b049] (beta 15)
- [fix] Don't drop signals while draining async buffer during shutdown, add tests (via Encore) (beta 12, beta 13)
- [fix]
pr-signal-fn
wasn't realizing delayed messages, add tests [cf72017] (beta 11) - [fix]
pr-signal-fn
broken custom pr-fn support, add tests [e7cce0c] (beta 10) - [fix] [#6] Missing root stack trace, add tests [213c647] (beta 9)
- [fix] Broken AOT support, add tests [ffea1a3] (beta 1)
- [fix] SLF4J broken timestamps, add tests [e222297] (beta 1)