4.9 KiB
Documentation | Latest releases | Get support
Telemere
Structured telemetry library for Clojure/Script
This library is still under development, ETA: April 2024.
Telemere handles traditional and structured logging, tracing, and performance measurement with one clean, simple, unified API.
It's a next-generation observability toolkit and modern replacement for Timbre, representing the refinement and culmination of ideas brewing over Timbre's 12+ years in a wide variety of real-world Clojure/Script environments.
Latest release/s
v1.0.0-alpha4(dev): release info (for early adopters)
See here for earlier releases.
Why Telemere?
Usability
- Simple, lightweight API that's easy to use, easy to configure, and deeply flexible.
- Sensible defaults to make getting started fast and easy.
- Extensive beginner-oriented documentation and docstrings.
Interop
- First-class out-the-box interop with OpenTelemetry, SLF4J v2, clojure.tools.logging, and Tufte.
- Included shim for easy/gradual migration from Timbre.
Performance
- Hyper-optimized and blazing fast, see benchmarks.
- Scales comfortably from the smallest disposable code, to the most massive and complex production environments.
Flexibility
- Config via plain Clojure vals and fns for easy customization, composition, and REPL debug.
- Top-notch support for environmental config (JVM props, ENV vars, edn resources, etc.).
- Expressive per-call and per-handler filtering at both runtime and compile-time.
- Easily filter by namespace and id pattern, level, level by namespace pattern, etc.
- Support for auto sampling, rate-limiting, and back-pressure monitoring.
- Support for fully configurable a/sync dispatch (blocking, dropping, sliding, etc.).
Video demo
See for intro and usage: (TODO: coming later)
Quick example
;; TODO: coming later
Observability tips
See here for general advice re: building and maintaining highly observable Clojure/Script systems.
Benchmarks
Telemere is highly optimized and offers terrific performance at any scale:
| Compile-time filtering? | Runtime filtering? | Time? | Trace? | nsecs |
|---|---|---|---|---|
| ✓ (elide) | - | - | - | 0 |
| - | ✓ | - | - | 200 |
| - | ✓ | ✓ | - | 280 |
| - | ✓ | ✓ | ✓ | 650 |
Measurements:
- Are ~nanoseconds per signal call (= milliseconds per 1e6 calls)
- Exclude handler runtime (which depends on handler/s, is usually async)
- Taken on a 2020 Macbook Pro M1, running OpenJDK 21
Tip: Telemere offers extensive per-call and per-handler filtering, sampling, and rate-limiting. Use these to ensure that you're not capturing useless/low-value information in production. See here for more tips!
Documentation
Funding
You can help support continued work on this project, thank you!! 🙏
License
Copyright © 2023-2024 Peter Taoussanis.
Licensed under EPL 1.0 (same as Clojure).