From a39b720935b575a1816eec42ea01f37a15e727e5 Mon Sep 17 00:00:00 2001 From: Peter Taoussanis Date: Wed, 7 Aug 2024 12:00:22 +0200 Subject: [PATCH] [doc] Doc and example improvements --- README.md | 12 ++++++++---- examples.cljc | 4 ++-- resources/signal-docstrings/signal-creators.txt | 2 +- wiki/5-Migrating.md | 14 +++++++------- wiki/6-FAQ.md | 4 ++-- 5 files changed, 20 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index cb87c24..fd6b7e2 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ ### Structured telemetry library for Clojure/Script -**Telemere** is a next-generation replacement for [Timbre](https://www.taoensso.com/timbre). It handles **structured and traditional logging**, **tracing**, and **basic performance monitoring** with a simple unified API. +**Telemere** is a next-generation replacement for [Timbre](https://www.taoensso.com/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](https://www.taoensso.com/timbre), [Tufte](https://www.taoensso.com/tufte), [Truss](https://www.taoensso.com/truss), etc. @@ -48,7 +48,10 @@ See [here][GitHub releases] for earlier releases. - Fully [configurable](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:handler-dispatch-options) **a/sync dispatch support**: blocking, dropping, sliding, etc. - Turn-key **sampling**, **rate-limiting**, and **back-pressure monitoring** with sensible defaults. -> A comparison to the excellent [Mulog](https://github.com/BrunoBonacci/mulog) micro-logging library is provided [here](../../wiki/6-FAQ#how-does-telemere-compare-to-mulog). +#### Comparisons + +- Telemere [compared](../../wiki/5-Migrating#from-timbre) to [Timbre](https://www.taoensso.com/timbre) +- Telemere [compared](../../wiki/6-FAQ#how-does-telemere-compare-to-mulog) to [Mulog](https://github.com/BrunoBonacci/mulog) ## Video demo @@ -193,8 +196,9 @@ See [here](../../wiki/4-Handlers) for more/upcoming handlers, community handlers ## Documentation - [Wiki][GitHub wiki] (getting started, usage, etc.) -- API reference: [cljdoc][cljdoc docs] or [Codox][Codox docs] -- Support: [Slack channel][] or [GitHub issues][] +- API reference via [cljdoc][cljdoc docs] or [Codox][Codox docs] +- Extensive [internal help](#internal-help) (no need to leave your IDE) +- Support via [Slack channel][] or [GitHub issues][] - [General observability tips](../../wiki/7-Tips) (advice on building and maintaining observable Clojure/Script systems, and getting the most out of Telemere) ## Benchmarks diff --git a/examples.cljc b/examples.cljc index 7bc5231..c0c6641 100644 --- a/examples.cljc +++ b/examples.cljc @@ -147,8 +147,8 @@ (t/with-min-level :trace ; Override global minimum level (t/with-signal (t/event! ::my-id1 :debug))) ; => {:keys [inst id ...]} -;; Deny all signals in matching namespaces -(t/set-ns-filter! {:deny "some.nosy.namespace.*"}) +;; Disallow all signals in matching namespaces +(t/set-ns-filter! {:disallow "some.nosy.namespace.*"}) ;;; Configuring handlers diff --git a/resources/signal-docstrings/signal-creators.txt b/resources/signal-docstrings/signal-creators.txt index 0d7c3a8..cc046d6 100644 --- a/resources/signal-docstrings/signal-creators.txt +++ b/resources/signal-docstrings/signal-creators.txt @@ -29,4 +29,4 @@ and return values), making them more/less convenient for certain use cases: ---------------------------------------------------------------------- [2] See `help:signal-options` - {:keys [kind level id data ...]} [3] See `help:signal-content` - {:keys [kind level id data ...]} -[4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.) +[4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.) diff --git a/wiki/5-Migrating.md b/wiki/5-Migrating.md index 59e390b..16f5a64 100644 --- a/wiki/5-Migrating.md +++ b/wiki/5-Migrating.md @@ -4,13 +4,13 @@ While [Timbre](https://taoensso.com/timbre) will **continue to be maintained and Telemere's functionality is a **superset of Timbre**, and offers *many* improvements including: -- Improved performance -- Better support for structured logging -- A cleaner and more flexible API -- Much better documentation -- Better built-in handlers -- Easier configuration in many cases -- A more robust architecture, free from all historical constraints +- Better support for [structured logging](./1-Getting-started#data-types-and-structures) +- Better [performance](https://github.com/taoensso/telemere#benchmarks) +- Better [documentation](https://github.com/taoensso/telemere#documentation) +- Better [included handlers](./4-Handlers##included-handlers) +- A more flexible [API](./1-Getting-started#usage) that unifies all telemetry and logging needs +- A more robust [architecture](./2-Architecture), free from all historical constraints +- Easier [configuration](./3-Config) Migrating from Timbre to Telemere should be straightforward **unless you depend on specific/custom appenders** that might not be available for Telemere (yet). diff --git a/wiki/6-FAQ.md b/wiki/6-FAQ.md index a41b235..44025de 100644 --- a/wiki/6-FAQ.md +++ b/wiki/6-FAQ.md @@ -134,9 +134,9 @@ Some particular **strengths of Telemere**: - Rich **dispatch control** (see [`help:handler-dispatch-options`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:handler-dispatch-options)) - Rich **environmental config** (see [`help:environmental-config`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:environmental-config)) for all platforms - Detailed **handler stats** (see [`get-handlers-stats`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#get-handlers-stats)) -- Extensive [in-IDE documentation](./1-Getting-started#internal-help) - Single **unified API** for all telemetry and traditional logging needs (see [`help:signal-creators`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:signal-creators)) - Lazy `:let`, `:data`, `:msg`, `:do` - evaluated only **after filtering** +- Extensive [in-IDE documentation](./1-Getting-started#internal-help) Some particular **strengths of Mulog** that I'm aware of: @@ -157,7 +157,7 @@ Ultimately I wrote Telemere because: 1. I have some particular needs, including very complex and large-scale applications that benefit from the kind of flexibility that Telemere offers re: filtering, dispatch, environmental config, lazy (post-filter) evaluation, etc. 2. I have some particular tastes re: my ideal API. 3. I wanted something that integrated particularly well with [Tufte](https://taoensso.com/tufte) and could share an identical API for filtering, handlers, etc. -4. I wanted a modern replacement for [Timbre](https://www.taoensso.com/timbre) users that offered a superset of its functionality and easy migration path. +4. I wanted a modern replacement for [Timbre](https://www.taoensso.com/timbre) users that offered a superset of its functionality and an [easy migration path](./5-Migrating#from-timbre). # Other questions?