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

• Wiki (getting started, usage, etc.) (TODO: coming later)
• API reference: Codox, clj-doc

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).