API | Wiki | Latest releases | Slack channel
Telemere is a next-generation replacement for Timbre that offers one simple unified API for traditional logging, structured logging, tracing, and basic performance monitoring.
Friendly enough for complete beginners, but flexible enough for the most complex and performance-sensitive real-world projects.
It helps enable Clojure/Script systems that are easily observable, robust, and debuggable - and it represents the refinement and culmination of ideas brewing over 12+ years in Timbre, Tufte, Truss, etc.
Supports Clojure, ClojureScript, GraalVM, but not (yet) Babashka.
See here for full introduction.
2024-08-28
v1.0.0-beta22
: release info (for early adopters/feedback)See here for earlier releases.
(require '[taoensso.telemere :as t])
;; (Just works / no config necessary for typical use cases)
;; Without structured data
(t/log! :info "Hello world!") ; %> Basic log signal (has message)
(t/event! ::my-id :debug) ; %> Basic event signal (just id)
;; With structured data
(t/log! {:level :info, :data {...}} "Hello again!")
(t/event! ::my-id {:level :debug, :data {...}})
;; Trace (auto interops with OpenTelemetry)
;; Tracks form runtime, return value, and (nested) parent tree
(t/trace! {:id ::my-id :data {...}}
(do-some-work))
;; Check resulting signal content for debug/tests
(t/with-signal (t/event! ::my-id)) ; => {:keys [ns level id data msg_ ...]}
;; Transform signals
(t/set-middleware! (fn [signal] (assoc signal :my-key "my-val")))
;; Filter signals by returning nil
(t/set-middleware! (fn [signal] (when-not (-> signal :data :skip-me?) signal)))
;; Getting fancy (all costs are conditional!)
(t/log!
{:level :debug
:sample-rate (my-dynamic-sample-rate)
:when (my-conditional)
:rate-limit {"1 per sec" [1 1000]
"5 per min" [5 60000]}
:do (inc-my-metric!)
:let
[diagnostics (my-expensive-diagnostics)
formatted (my-expensive-format diagnostics)]
:data
{:diagnostics diagnostics
:formatted formatted
:local-state *my-dynamic-context*}}
;; Message string or vector to join as string
["Something interesting happened!" formatted])
A key hurdle in building observable systems is that it's often inconvenient and costly to get out the kind of detailed info that we need when debugging.
Telemere's strategy to address this is to:
The effect is more than impressive micro-benchmarks. This approach enables a fundamental (qualitative) change in one's approach to observability.
It enables you to write code that is information-verbose by default.
See for intro and basic usage:
;; Set minimum level
(t/set-min-level! :warn) ; For all signals
(t/set-min-level! :log :debug) ; For `log!` signals only
;; Set namespace and id filters
(t/set-ns-filter! {:disallow "taoensso.*" :allow "taoensso.sente.*"})
(t/set-id-filter! {:allow #{::my-particular-id "my-app/*"}})
;; Set minimum level for `event!` signals for particular ns pattern
(t/set-min-level! :event "taoensso.sente.*" :warn)
;; See `t/help:filters` docstring for more
;; Use middleware to:
;; - Transform signals
;; - Filter signals by arb conditions (incl. data/content)
(t/set-middleware!
(fn [signal]
(if (-> signal :data :skip-me?)
nil ; Filter signal (don't handle)
(assoc signal :passed-through-middleware? true))))
(t/with-signal (t/event! ::my-id {:data {:skip-me? true}})) ; => nil
(t/with-signal (t/event! ::my-id {:data {:skip-me? false}})) ; => {...}
;; Signal handlers
(t/get-handlers) ; => {<handler-id> {:keys [handler-fn handler-stats_ dispatch-opts]}}
(t/add-handler! :my-console-handler
(t/handler:console {}) ; Returns handler fn, has many opts
{:async {:mode :dropping, :buffer-size 1024, :n-threads 1}
:priority 100
:sample-rate 0.5
:min-level :info
:ns-filter {:disallow "taoensso.*"}
:rate-limit {"1 per sec" [1 1000]}
;; See `t/help:handler-dispatch-options` for more
})
;; Print human-readable output to console
(t/add-handler! :my-console-handler
(t/handler:console
{:output-fn (t/format-signal-fn {...})}))
;; Print edn to console
(t/add-handler! :my-console-handler
(t/handler:console
{:output-fn (t/pr-signal-fn {:pr-fn :edn})}))
;; Print JSON to console
;; Ref. <https://github.com/metosin/jsonista> (or any alt JSON lib)
#?(:clj (require '[jsonista.core :as jsonista]))
(t/add-handler! :my-console-handler
(t/handler:console
{:output-fn
#?(:cljs :json ; Use js/JSON.stringify
:clj jsonista/write-value-as-string)}))
See examples.cljc for REPL-ready snippets!
See relevant docstrings (links below) for usage info-
Name | Signal kind | Main arg | Optional arg | Returns |
---|---|---|---|---|
log! | :log | msg | opts /level | Signal allowed? |
event! | :event | id | opts /level | Signal allowed? |
error! | :error | error | opts /id | Given error |
trace! | :trace | form | opts /id | Form result |
spy! | :spy | form | opts /level | Form result |
catch->error! | :error | form | opts /id | Form value or given fallback |
signal! | <arb> | opts | - | Depends on opts |
Detailed help is available without leaving your IDE:
Var | Help with |
---|---|
help:signal-creators | Creating signals |
help:signal-options | Options when creating signals |
help:signal-content | Signal content (map given to middleware/handlers) |
help:filters | Signal filtering and transformation |
help:handlers | Signal handler management |
help:handler-dispatch-options | Signal handler dispatch options |
help:environmental-config | Config via JVM properties, environment variables, or classpath resources |
See ✅ links below for features and usage,
See ❤️ links below to vote on future handlers:
Target (↓) | Clj | Cljs |
---|---|---|
Apache Kafka | ❤️ | - |
AWS Kinesis | ❤️ | - |
Console | ✅ | ✅ |
Console (raw) | - | ✅ |
Datadog | ❤️ | ❤️ |
✅ | - | |
Graylog | ❤️ | - |
Jaeger | ❤️ | - |
Logstash | ❤️ | - |
OpenTelemetry | ✅ | ❤️ |
Redis | ❤️ | - |
SQL | ❤️ | - |
Slack | ✅ | - |
TCP socket | ✅ | - |
UDP socket | ✅ | - |
Zipkin | ❤️ | - |
You can also easily write your own handlers.
My plan for Telemere is to offer a stable core of limited scope, then to focus on making it as easy for the community to write additional stuff like handlers, middleware, and utils.
See here for community resources.
Telemere is highly optimized and offers great performance at any scale:
Compile-time filtering? | Runtime filtering? | Profile? | Trace? | nsecs |
---|---|---|---|---|
✓ (elide) | - | - | - | 0 |
- | ✓ | - | - | 350 |
- | ✓ | ✓ | - | 450 |
- | ✓ | ✓ | ✓ | 1000 |
Measurements:
Telemere is optimized for real-world performance. This means prioritizing flexibility and realistic usage over synthetic micro-benchmarks.
Large applications can produce absolute heaps of data, not all equally valuable. Quickly processing infinite streams of unmanageable junk is an anti-pattern. As scale and complexity increase, it becomes more important to strategically plan what data to collect, when, in what quantities, and how to manage it.
Telemere is designed to help with all that. It offers rich data and unmatched filtering support - including per-signal and per-handler sampling and rate-limiting.
Use these to ensure that you're not capturing useless/low-value/high-noise information in production! With appropriate planning, Telemere is designed to scale to systems of any size and complexity.
See here for detailed tips on real-world usage.
You can help support continued work on this project, thank you!! 🙏
Copyright © 2023-2024 Peter Taoussanis.
Licensed under EPL 1.0 (same as Clojure).
Can you improve this documentation?Edit on GitHub
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close