mirror of
https://github.com/taoensso/telemere.git
synced 2025-12-24 04:18:26 +00:00
[doc] Misc improvements
This commit is contained in:
Peter Taoussanis
parent
55720aca54
commit
cca8bb33ff
8 changed files with 38 additions and 32 deletions
28
README.md
28
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):
|
||||
|
||||
<a href="https://www.youtube.com/watch?v=lOaZ0SgPVu4" target="_blank">
|
||||
<img src="https://img.youtube.com/vi/lOaZ0SgPVu4/maxresdefault.jpg" alt="Telemere lightning intro" width="480" border="0" />
|
||||
</a>
|
||||
|
||||
### REPL demo (24 mins):
|
||||
|
||||
<a href="https://www.youtube.com/watch?v=-L9irDG8ysM" target="_blank">
|
||||
<img src="https://img.youtube.com/vi/-L9irDG8ysM/maxresdefault.jpg" alt="Telemere demo video" width="480" border="0" />
|
||||
|
|
@ -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!) | `<arb>` | `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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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!)
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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!) | `<arb>` | `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.
|
||||
|
|
|
|||
|
|
@ -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 <opts> <form>)]
|
||||
(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
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue