From 7284d480f36a11b94034dda3d0cec34cf7ed156e Mon Sep 17 00:00:00 2001 From: Peter Taoussanis Date: Fri, 20 Dec 2024 14:44:34 +0100 Subject: [PATCH] [doc] Misc improvements --- README.md | 10 ++++++++-- examples.cljc | 2 +- .../resources/signal-docstrings/signal-options.txt | 2 +- projects/main/src/taoensso/telemere.cljc | 2 +- wiki/3-Config.md | 6 +++--- wiki/5-Migrating.md | 4 ++-- wiki/6-FAQ.md | 8 ++++---- 7 files changed, 20 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 9454db4..10003e5 100644 --- a/README.md +++ b/README.md @@ -209,9 +209,15 @@ It enables you to write code that is **information-verbose by default**. - Telemere [compared](../../wiki/5-Migrating#from-timbre) to [Timbre](https://www.taoensso.com/timbre) (Telemere's predecessor) - Telemere [compared](../../wiki/6-FAQ#how-does-telemere-compare-to-mulog) to [Mulog](https://github.com/BrunoBonacci/mulog) (Structured micro-logging library) -## Video demo +## Videos -See for intro and basic usage: +### Lightning intro (7 mins): + + + Telemere lightning intro + + +### REPL demo (24 mins): Telemere demo video diff --git a/examples.cljc b/examples.cljc index b3a7e1e..efc20f8 100644 --- a/examples.cljc +++ b/examples.cljc @@ -327,7 +327,7 @@ (t/log! (str "This message " "was built " "by `str`")) ;; %> {:msg "This message was built by `str`"} -(t/log! (format "This message was built by `%s`" "format")) +(t/log! (enc/format "This message was built by `%s`" "format")) ;; %> {:msg "This message was built by `format`"} ;;; App-level kvs diff --git a/projects/main/resources/signal-docstrings/signal-options.txt b/projects/main/resources/signal-docstrings/signal-options.txt index 6255da7..23e90ff 100644 --- a/projects/main/resources/signal-docstrings/signal-options.txt +++ b/projects/main/resources/signal-docstrings/signal-options.txt @@ -11,7 +11,7 @@ Signal options (shared by all signal creators): `:data` -------- Arb app-level ?data to incl. in signal: usu. a map `:error` ------- Arb app-level ?error to incl. in signal: platform error [2] -`:run` --------- ?form to execute UNCONDITIONALLY; will incl. `:run-value` in signal +`:run` --------- ?form to execute UNCONDITIONALLY; will incl. `:run-val` in signal `:do` ---------- ?form to execute conditionally (iff signal allowed), before establishing `:let` ?binding `:let` --------- ?bindings to establish conditionally (iff signal allowed), BEFORE evaluating `:data` and `:msg` (useful!) diff --git a/projects/main/src/taoensso/telemere.cljc b/projects/main/src/taoensso/telemere.cljc index 8b9e3c7..9e72cc5 100644 --- a/projects/main/src/taoensso/telemere.cljc +++ b/projects/main/src/taoensso/telemere.cljc @@ -185,7 +185,7 @@ :via :global})))))) #?(:clj - (def ^:dynamic ^:no-doc *otel-tracer* + (def ^:dynamic *otel-tracer* "Experimental, subject to change. Feedback welcome! OpenTelemetry `Tracer` to use for Telemere's tracing signal creators diff --git a/wiki/3-Config.md b/wiki/3-Config.md index 01beb46..df15c33 100644 --- a/wiki/3-Config.md +++ b/wiki/3-Config.md @@ -103,19 +103,19 @@ Aside from configuring the exporters (2), Telemere's OpenTelemetry interop **doe ## Tufte -> [Tufte](https:/www.taoensso.com/tufte) is a simple performance monitoring library for Clojure/Script by the author of Telemere. +> [Tufte](https://www.taoensso.com/tufte) is a simple performance monitoring library for Clojure/Script by the author of Telemere. Telemere can easily incorporate Tufte performance data in its signals, just like any other data: ```clojure (let [[_ perf-data] (tufte/profiled
)] - (t/log! "Performance data" {:perf-data perf-data})) + (t/log! {:perf-data perf-data} "Performance data")) ``` Telemere and Tufte work great together: - Their functionality is complementary. -- The [upcoming](https:/www.taoensso.com/roadmap) Tufte v3 will share the same core as Telemere and offer an **identical API** for managing filters and handlers. +- The [upcoming](https://www.taoensso.com/roadmap) Tufte v3 will share the same core as Telemere and offer an **identical API** for managing filters and handlers. ## Truss diff --git a/wiki/5-Migrating.md b/wiki/5-Migrating.md index 4bc025c..d03da96 100644 --- a/wiki/5-Migrating.md +++ b/wiki/5-Migrating.md @@ -5,8 +5,8 @@ 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: - Better support for [structured logging](./1-Getting-started#data-types-and-structures) -- Much better [performance](https://github.com/taoensso/telemere#performance) -- Much better [documentation](https://github.com/taoensso/telemere#documentation) +- Better [performance](https://github.com/taoensso/telemere#performance) +- Better [documentation](https://github.com/taoensso/telemere#documentation) - 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 - Better [included handlers](./4-Handlers##included-handlers) diff --git a/wiki/6-FAQ.md b/wiki/6-FAQ.md index bbe661f..ba44a84 100644 --- a/wiki/6-FAQ.md +++ b/wiki/6-FAQ.md @@ -1,6 +1,6 @@ # Does Telemere replace Timbre? -> [Timbre](https:/www.taoensso.com/timbre) is a pure Clojure/Script logging library, and ancestor of Telemere. +> [Timbre](https://www.taoensso.com/timbre) is a pure Clojure/Script logging library, and ancestor of Telemere. **Yes**, Telemere's functionality is a **superset of Timbre**, and offers *many* improvements over Timbre. @@ -12,7 +12,7 @@ See section [5-Migrating](./5-Migrating#from-timbre) for migration info. # Why not just update Timbre? -> [Timbre](https:/www.taoensso.com/timbre) is a pure Clojure/Script logging library, and ancestor of Telemere. +> [Timbre](https://www.taoensso.com/timbre) is a pure Clojure/Script logging library, and ancestor of Telemere. Why release Telemere as a *new library* instead of just updating Timbre? @@ -32,9 +32,9 @@ This will eventually ease long-term maintenance, increase reliability, and help # Does Telemere replace Tufte? -> [Tufte](https:/www.taoensso.com/tufte) is a simple performance monitoring library for Clojure/Script by the author of Telemere. +> [Tufte](https://www.taoensso.com/tufte) is a simple performance monitoring library for Clojure/Script by the author of Telemere. -**No**, Telemere does **not** replace [Tufte](https:/www.taoensso.com/tufte). They work great together, and the [upcoming](https:/www.taoensso.com/roadmap) Tufte v3 will share the same core as Telemere and offer an **identical API** for managing filters and handlers. +**No**, Telemere does **not** replace [Tufte](https://www.taoensso.com/tufte). They work great together, and the [upcoming](https://www.taoensso.com/roadmap) Tufte v3 will share the same core as Telemere and offer an **identical API** for managing filters and handlers. There is **some feature overlap** though since Telemere offers basic performance measurement as part of its tracing features.