diff --git a/CHANGELOG.md b/CHANGELOG.md index ea3239c..ea0a79e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,11 +4,12 @@ This project uses [**Break Versioning**](https://www.taoensso.com/break-versioni # `v1.0.0-beta1` (2024-04-19) -> 📦 [Available on Clojars](https://clojars.org/com.taoensso/telemere/versions/1.0.0-beta1), this project uses [Break Versioning](https://www.taoensso.com/break-versioning). +> **Dep/s**: [Telemere](https://clojars.org/com.taoensso/telemere/versions/1.0.0-beta1) and [Telemere SLF4J provider](https://clojars.org/com.taoensso/slf4j-telemere) are on Clojars. +> **Versioning**: Telemere uses [Break Versioning](https://www.taoensso.com/break-versioning). This is Telemere's first public pre-release and mostly intended for early testers and those that'd like to give feedback. -While no significant changes are expected before the [planned v1.0 final release](https://www.taoensso.com/roadmap), you probably don't want to use this in production just yet. +While no significant changes are expected before the [planned v1.0 final release](https://www.taoensso.com/roadmap), you **probably don't want to use this in production** just yet. **Please report any unexpected problems** and let me know if anything is unclear, inconvenient, etc. Now's the ideal time to get any last-minute changes in. Thank you! 🙏 diff --git a/README.md b/README.md index 29bb51d..c69f8d8 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ It helps enable Clojure/Script systems that are **observable**, **robust**, and ## Latest release/s -- `v1.0.0-beta1`: [release info](https://clojars.org/com.taoensso/telemere/versions/1.0.0-beta1) +- `v1.0.0-beta1`: [release info](../../releases/tag/v1.0.0-beta1) [![Main tests][Main tests SVG]][Main tests URL] [![Graal tests][Graal tests SVG]][Graal tests URL] @@ -35,7 +35,7 @@ See [here][GitHub releases] for earlier releases. #### Scaling -- Hyper-optimized and **blazing fast**, see [benchmarks](#performance). +- Hyper-optimized and **blazing fast**, see [benchmarks](#benchmarks). - An API that **scales comfortably** from the smallest disposable code, to the most massive and complex real-world production environments. #### Flexibility diff --git a/resources/signal-docstrings/signal-options.txt b/resources/signal-docstrings/signal-options.txt index e2e52ce..1985dd4 100644 --- a/resources/signal-docstrings/signal-options.txt +++ b/resources/signal-docstrings/signal-options.txt @@ -16,10 +16,10 @@ Signal options (shared by all signal creators): `:ctx` --------- Custom ?val to override auto (dynamic `*ctx*`) in signal `:parent` ------ Custom ?{:keys [id uid]} to override auto (dynamic) parent signal info in signal -`:location` ---- Custom ?{:keys [ns line column file]} to override auto signal call location +`:location` ---- Custom ?{:keys [ns line column file]} to override auto signal creator callsite location `:elidable?` --- Should signal be subject to compile-time elision? (Default: true). -`:sample-rate` - ?rate ∈ℝ[0,1] for call sampling (0.75 => allow 75% of signals, nil => allow all) +`:sample-rate` - ?rate ∈ℝ[0,1] for signal sampling (0.75 => allow 75% of signals, nil => allow all) `:when` -------- Arb ?form; when present, form must return truthy to allow signal `:rate-limit` -- ?spec as given to `taoensso.telemere/rate-limiter`, see its docstring for details `:middleware` -- ?[(fn [signal])=>modified-signal ...] signal middleware diff --git a/resources/signal-docstrings/spy!.txt b/resources/signal-docstrings/spy!.txt index 11e1f51..9fb97e3 100644 --- a/resources/signal-docstrings/spy!.txt +++ b/resources/signal-docstrings/spy!.txt @@ -25,7 +25,7 @@ Tips: - Test using `with-signal`: (with-signal (spy! ...)). - Supports the same options [2] as other signals [1]. - - Identical to `trace!`, but emphasizing form + level rather than form + id. + - Identical to `trace!`, but emphasizes form + level rather than form + id. - Useful for debugging/monitoring forms, and tracing (nested) execution flow. - Execution of `form` arg may create additional (nested) signals. diff --git a/resources/signal-docstrings/trace!.txt b/resources/signal-docstrings/trace!.txt index 786e2ba..1a9629e 100644 --- a/resources/signal-docstrings/trace!.txt +++ b/resources/signal-docstrings/trace!.txt @@ -25,7 +25,7 @@ Tips: - Test using `with-signal`: (with-signal (trace! ...)). - Supports the same options [2] as other signals [1]. - - Identical to `spy!`, but emphasizing form + id rather than form + level. + - Identical to `spy!`, but emphasizes form + id rather than form + level. - Useful for debugging/monitoring forms, and tracing (nested) execution flow. - Execution of `form` arg may create additional (nested) signals. diff --git a/src/taoensso/telemere.cljc b/src/taoensso/telemere.cljc index 6c9c83b..e1b2a45 100644 --- a/src/taoensso/telemere.cljc +++ b/src/taoensso/telemere.cljc @@ -36,11 +36,8 @@ (enc/assert-min-encore-version [3 103 0]) ;;;; TODO -;; - Review, TODOs, missing docstrings -;; - Reading plan, wiki docs, explainer/demo video ;; - Add email handler -;; -;; - Next OpenTelemetry tools (traces, etc.) +;; - Native OpenTelemetry traces and spans ;; - Update Tufte (signal API, config API, signal keys, etc.) ;; - Update Timbre (signal API, config API, signal keys, backport improvements) diff --git a/wiki/7-Tips.md b/wiki/7-Tips.md index d6134b6..8f32e7a 100644 --- a/wiki/7-Tips.md +++ b/wiki/7-Tips.md @@ -86,7 +86,11 @@ Consider the [differences](https://www.youtube.com/watch?v=oyLBGkS5ICk) between - **Signal sampling** and **handler sampling** are **multiplicative**. - If a signal is created with *20%* sampling and a handler handles *50%* of given signals, then *10%* of possible signals will be handled. This multiplicative rate is helpfully reflected in each signal's final `:sample-rate` value. + If a signal is created with *20%* sampling and a handler handles *50%* of given signals, then *10%* of possible signals will be handled. + + This multiplicative rate is helpfully reflected in each signal's final `:sample-rate` value, making it possible to estimate unsampled cardinalities in relevant cases. + + So for `n` randomly sampled signals matching some criteria, you'd have seen an estimated `Σ(1.0/sample-rate_i)` such signals _without_ sampling, etc. - Middleware can return any type, but it's best to return only `nil` or a map. - Middleware can be used to **filter signals** by returning `nil`.