API | Wiki | Latest releases | Slack channel
Telemere is a next-generation replacement for Timbre that offers a simple unified API for structured and traditional logging, tracing, and basic performance monitoring.
It helps enable Clojure/Script systems that are observable, robust, and debuggable - and it represents the refinement and culmination of ideas brewing over 12+ years in Timbre, Tufte, Truss, etc.
[Terminology] Telemetry derives from the Greek tele (remote) and metron (measure). It refers to the collection of in situ (in position) data, for transmission to other systems for monitoring/analysis. Logs are the most common form of software telemetry. So think of telemetry as the superset of logging-like activities that help monitor and understand (software) systems.
2024-08-20
v1.0.0-beta19
: release info (for early adopters/feedback)See here for earlier releases.
See for intro and basic usage:
(require '[taoensso.telemere :as t])
(t/log! {:id ::my-id, :data {:x1 :x2}} "My message") %>
;; 2024-04-11T10:54:57.202869Z INFO LOG Schrebermann.local examples(56,1) ::my-id - My message
;; data: {:x1 :x2}
(t/log! "This will send a `:log` signal to the Clj/s console")
(t/log! :info "This will do the same, but only when the current level is >= `:info`")
;; Easily construct messages from parts
(t/log! :info ["Here's a" "joined" "message!"])
;; Attach an id
(t/log! {:level :info, :id ::my-id} "This signal has an id")
;; Attach arb user data
(t/log! {:level :info, :data {:x :y}} "This signal has structured data")
;; Capture for debug/testing
(t/with-signal (t/log! "This will be captured"))
;; => {:keys [location level id data msg_ ...]}
;; `:let` bindings are available to `:data` and message, but only paid
;; for when allowed by minimum level and other filtering criteria
(t/log!
{:level :info
:let [expensive-metric1 (last (for [x (range 100), y (range 100)] (* x y)))]
:data {:metric1 expensive-metric1}}
["Message with metric value:" expensive-metric1])
;; With sampling 50% and 1/sec rate limiting
(t/log!
{:sample-rate 0.5
:rate-limit {"1 per sec" [1 1000]}}
"This signal will be sampled and rate limited")
;; There are several signal creators available for convenience.
;; All support the same options but each offer's a calling API
;; optimized for a particular use case. Compare:
;; `log!` - [msg] or [level-or-opts msg]
(t/with-signal (t/log! {:level :info, :id ::my-id} "Hi!"))
;; `event!` - [id] or [id level-or-opts]
(t/with-signal (t/event! ::my-id {:level :info, :msg "Hi!"}))
;; `signal!` - [opts]
(t/with-signal (t/signal! {:level :info, :id ::my-id, :msg "Hi!"}))
;; See `t/help:signal-creators` docstring for more
;;; A quick taste of filtering
(t/set-ns-filter! {:disallow "taoensso.*" :allow "taoensso.sente.*"})
(t/set-id-filter! {:allow #{::my-particular-id "my-app/*"}})
(t/set-min-level! :warn) ; Set minimum level for all signals
(t/set-min-level! :log :debug) ; Set minimul level for `log!` signals
;; Set minimum level for `event!` signals originating in
;; the "taoensso.sente.*" ns
(t/set-min-level! :event "taoensso.sente.*" :warn)
;; See `t/help:filters` docstring for more
;;; Use middleware to transform signals and/or filter signals
;;; by signal data/content/etc.
(t/set-middleware!
(fn [signal]
(if (get-in signal [:data :hide-me?])
nil ; Suppress signal (don't handle)
(assoc signal :passed-through-middleware? true))))
(t/with-signal (t/event! ::my-id {:data {:hide-me? true}})) ; => nil
(t/with-signal (t/event! ::my-id {:data {:hide-me? false}})) ; => {...}
See examples.cljc for more 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 for features and usage
See 👍 links to vote on handler for future addition
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