v1.0.0-RC5 (2025-03-10)

📦 Dependencies

Available on Clojars:

1. Telemere - main dependency.
2. 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.

- Peter Taoussanis

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: swap ctx, 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 use clean-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 calling add-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 to format-signal-fn and pr-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 in signal! 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 to signal!, 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! with catch->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 and with-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 by add-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)