From 881b8dbd72b5cc6c13cf53a64b4e7f3c2f86418e Mon Sep 17 00:00:00 2001 From: Peter Taoussanis Date: Wed, 6 Mar 2024 11:54:51 +0100 Subject: [PATCH] [wip] Initial README content, etc. --- README.md | 61 +++++++++++++++++++++++++++++++++++--- examples.clj | 1 + examples.cljs | 1 + src/taoensso/telemere.cljc | 1 + 4 files changed, 60 insertions(+), 4 deletions(-) create mode 100644 examples.clj create mode 100644 examples.cljs diff --git a/README.md b/README.md index 7040db8..c2719ef 100644 --- a/README.md +++ b/README.md @@ -5,11 +5,18 @@ ### Structured telemetry library for Clojure/Script -This library is **still under development** and not available yet for public use. +> This library is **still under development**!! + +**Telemere** is an [**upcoming**](https://www.taoensso.com/roadmap) next-generation observability toolkit for **capturing all kinds of un/structured information** in your running Clojure and ClojureScript programs. + +It offers a **simple, clean, unified API** that covers: **logging**, **events**, **performance measurement**, **tracing**, etc. + +Taking full advantage of Clojure's unique **macro and interop** capabilities, Telemere represents the **refinement and culmination** of ideas brewing for 10+ years in [Timbre](https://www.taoensso.com/timbre), [Tufte](https://www.taoensso.com/tufte), [Truss](https://www.taoensso.com/truss), etc. ## Latest release/s -- Coming [~Apr 2024](https://www.taoensso.com/roadmap) +- Stable release: coming [~Apr 2024](https://www.taoensso.com/roadmap) +- `v1.0.0-SNAPSHOT` (dev): [release info](https://clojars.org/com.taoensso/telemere) (for early adopters) [![Main tests][Main tests SVG]][Main tests URL] [![Graal tests][Graal tests SVG]][Graal tests URL] @@ -18,11 +25,57 @@ See [here][GitHub releases] for earlier releases. ## Why Telemere? -- Coming later +- Simple, lightweight API that's **easy to use**, **easy to configure**, and **deeply flexible**. +- An **unmatched logging experience** designed to **scale comfortably** from the smallest disposable code, to the most massive production applications. +- **Easy integration** with the **tooling of your choice**, including first-class **out-the-box interop** with [OpenTelemetry](https://opentelemetry.io/), [SLF4J v2](https://www.slf4j.org/), [clojure.tools.logging](https://github.com/clojure/tools.logging), and [Tufte](https://www.taoensso.com/tufte). +- Hyper-optimized and **blazing fast**, see [performance](#performance). +- 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.). +- **Sensible defaults** to make getting started **fast and easy**. +- Extensive **beginner-oriented** [documentation](#documentation), docstrings, examples, etc. + +## Video demo + +See for intro and usage: (**TODO**: coming later) + + + Telemere demo video + + +## Quick example + +```clojure +;; TODO: coming later +``` + +## Observability tips + +See [here](/TODO) for general advice re: building and maintaining **highly observable** Clojure/Script systems. + +## Performance + +Telemere is **highly optimized** and offers terrific performance at any scale: + +| Compile-time filtering? | Runtime filtering? | Time? | Trace? | nsecs +| :-: | :-: | :-: | :-: | --: +| ✓ (elide) | - | - | - | 0 +| - | ✓ | - | - | 220 +| - | ✓ | ✓ | - | 300 +| - | ✓ | ✓ | ✓ | 730 + +Measurements: + +- Are **~nanoseconds per signal call** (= milliseconds per 1e6 calls) +- Taken on a 2020 Macbook Pro M1, running OpenJDK 21 +- Exclude handler runtime (which depends on handler/s, is usually async) + +**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](/TODO) for more tips! ## Documentation -- [Wiki][GitHub wiki] (getting started, usage, etc.) +- [Wiki][GitHub wiki] (getting started, usage, etc.) (**TODO:** coming later) - API reference: [Codox][Codox docs], [clj-doc][clj-doc docs] ## Funding diff --git a/examples.clj b/examples.clj new file mode 100644 index 0000000..d6c08a7 --- /dev/null +++ b/examples.clj @@ -0,0 +1 @@ +;; TODO diff --git a/examples.cljs b/examples.cljs new file mode 100644 index 0000000..d6c08a7 --- /dev/null +++ b/examples.cljs @@ -0,0 +1 @@ +;; TODO diff --git a/src/taoensso/telemere.cljc b/src/taoensso/telemere.cljc index 707c137..d02fad3 100644 --- a/src/taoensso/telemere.cljc +++ b/src/taoensso/telemere.cljc @@ -73,6 +73,7 @@ enc/chance enc/rate-limiter enc/newline + impl/msg-splice impl/msg-skip #?(:clj impl/with-signal)