diff --git a/README.md b/README.md index 9454db4..30f773f 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 @@ -223,15 +229,15 @@ See relevant docstrings (links below) for usage info- ### Creating signals -| Name | Signal kind | Main arg | Optional arg | Returns | -| :---------------------------------------------------------------------------------------------------------- | :---------- | :------- | :------------- | :--------------------------- | -| [`log!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#log!) | `:log` | `msg` | `opts`/`level` | Signal allowed? | -| [`event!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#event!) | `:event` | `id` | `opts`/`level` | Signal allowed? | -| [`error!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#error!) | `:error` | `error` | `opts`/`id` | Given error | -| [`trace!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#trace!) | `:trace` | `form` | `opts`/`id` | Form result | -| [`spy!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#spy!) | `:spy` | `form` | `opts`/`level` | Form result | -| [`catch->error!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#catch-%3Eerror!) | `:error` | `form` | `opts`/`id` | Form value or given fallback | -| [`signal!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#signal!) | `` | `opts` | - | Depends on opts | +| Name | Kind | Args | Returns | +| :---------------------------------------------------------------------------------------------------------- | :--------- | :--------------- | :--------------------------- | +| [`signal!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#signal!) | `:generic` | `opts` | Depends on opts | +| [`event!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#event!) | `:event` | `id` + `?level` | Signal allowed? | +| [`log!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#log!) | `:log` | `?level` + `msg` | Signal allowed? | +| [`trace!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#trace!) | `:trace` | `?id` + `run` | Form result | +| [`spy!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#spy!) | `:spy` | `?level` + `run` | Form result | +| [`error!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#error!) | `:error` | `?id` + `error` | Given error | +| [`catch->error!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#catch-%3Eerror!) | `:error` | `?id` | Form value or given fallback | ### Internal help 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 6ea2748..8364c66 100644 --- a/projects/main/resources/signal-docstrings/signal-options.txt +++ b/projects/main/resources/signal-docstrings/signal-options.txt @@ -12,7 +12,7 @@ All options are available for 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/1-Getting-started.md b/wiki/1-Getting-started.md index bad54f0..e0a8d1b 100644 --- a/wiki/1-Getting-started.md +++ b/wiki/1-Getting-started.md @@ -129,15 +129,15 @@ Interop can be tough to get configured correctly so the [`check-interop`](https: Use whichever signal creator is most convenient for your needs: -| Name | Signal kind | Main arg | Optional arg | Returns | -|:-- | :-- | :-- | :-- | :-- | -| [`log!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#log!) | `:log` | `msg` | `opts`/`level` | Signal allowed? -| [`event!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#event!) | `:event` | `id` | `opts`/`level` | Signal allowed? -| [`error!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#error!) | `:error` | `error` | `opts`/`id` | Given error -| [`trace!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#trace!) | `:trace` | `form` | `opts`/`id` | Form result -| [`spy!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#spy!) | `:spy` | `form` | `opts`/`level` | Form result -| [`catch->error!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#catch-%3Eerror!) | `:error` | `form` | `opts`/`id` | Form value or given fallback -| [`signal!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#signal!) | `` | `opts` | - | Depends on opts +| Name | Kind | Args | Returns | +| :---------------------------------------------------------------------------------------------------------- | :--------- | :--------------- | :--------------------------- | +| [`signal!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#signal!) | `:generic` | `opts` | Depends on opts | +| [`event!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#event!) | `:event` | `id` + `?level` | Signal allowed? | +| [`log!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#log!) | `:log` | `?level` + `msg` | Signal allowed? | +| [`trace!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#trace!) | `:trace` | `?id` + `run` | Form result | +| [`spy!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#spy!) | `:spy` | `?level` + `run` | Form result | +| [`error!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#error!) | `:error` | `?id` + `error` | Given error | +| [`catch->error!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#catch-%3Eerror!) | `:error` | `?id` | Form value or given fallback | - See relevant docstrings (links above) for usage info. - See [`help:signal-creators`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:signal-creators) for more about 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 21e5288..3a419d0 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.