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/project.clj b/project.clj index 1c5e6c8..2680007 100644 --- a/project.clj +++ b/project.clj @@ -34,7 +34,6 @@ {:jvm-opts ["-server" "-Dtaoensso.elide-deprecated=true" - "-Dtaoensso.telemere.auto-handlers=false" "-Dclojure.tools.logging.to-telemere=true"] :global-vars 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 dab6c8d..21f7d0e 100644 --- a/src/taoensso/telemere.cljc +++ b/src/taoensso/telemere.cljc @@ -11,10 +11,9 @@ [taoensso.encore.signals :as sigs] [taoensso.telemere.impl :as impl] [taoensso.telemere.utils :as utils] - #?(:clj [taoensso.telemere.streams :as streams]) - - #?(:default [taoensso.telemere.handlers.console :as handlers:console]) - #?(:clj [taoensso.telemere.handlers.file :as handlers:file])) + #?(:clj [taoensso.telemere.streams :as streams]) + #?(:default [taoensso.telemere.console-handlers :as ch]) + #?(:clj [taoensso.telemere.file-handler :as fh])) #?(:cljs (:require-macros @@ -36,11 +35,8 @@ (enc/assert-min-encore-version [3 104 1]) ;;;; 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) @@ -380,9 +376,9 @@ ;;;; Handlers (enc/defaliases - #?(:default handlers:console/handler:console) - #?(:cljs handlers:console/handler:console-raw) - #?(:clj handlers:file/handler:file)) + #?(:default ch/handler:console) + #?(:cljs ch/handler:console-raw) + #?(:clj fh/handler:file)) ;;;; Flow benchmarks @@ -418,8 +414,7 @@ ;;;; (impl/on-init - (when impl/auto-handlers? - (add-handler! :default/console (handler:console))) + (add-handler! :default/console (handler:console)) #?(:clj (enc/catching (require '[taoensso.telemere.tools-logging]))) #?(:clj (enc/catching (require '[taoensso.telemere.slf4j])))) @@ -427,7 +422,7 @@ ;;;; (comment - (with-handler :hid1 (handlers/console-handler) {} (log! "Message")) + (with-handler :hid1 (handler:console) {} (log! "Message")) (let [sig (with-signal @@ -437,6 +432,6 @@ (ex-info "Ex2" {:b :B} (ex-info "Ex1" {:a :A}))}))] - (do (let [hf (handlers/file-handler)] (hf sig) (hf))) - (do (let [hf (handlers/console-handler)] (hf sig) (hf))) - #?(:cljs (let [hf (handlers/raw-console-handler)] (hf sig) (hf))))) + (do (let [hf (handler:file)] (hf sig) (hf))) + (do (let [hf (handler:console)] (hf sig) (hf))) + #?(:cljs (let [hf (handler:console-raw)] (hf sig) (hf))))) diff --git a/src/taoensso/telemere/handlers/console.cljc b/src/taoensso/telemere/console_handlers.cljc similarity index 97% rename from src/taoensso/telemere/handlers/console.cljc rename to src/taoensso/telemere/console_handlers.cljc index 5a1fa43..e2053dc 100644 --- a/src/taoensso/telemere/handlers/console.cljc +++ b/src/taoensso/telemere/console_handlers.cljc @@ -1,4 +1,4 @@ -(ns ^:no-doc taoensso.telemere.handlers.console +(ns ^:no-doc taoensso.telemere.console-handlers "Private ns, implementation detail. Core console handlers." (:require @@ -6,7 +6,7 @@ [taoensso.telemere.utils :as utils])) (comment - (remove-ns 'taoensso.telemere.handlers.console) + (remove-ns 'taoensso.telemere.console-handlers) (:api (enc/interns-overview))) #?(:clj diff --git a/src/taoensso/telemere/handlers/file.clj b/src/taoensso/telemere/file_handler.clj similarity index 99% rename from src/taoensso/telemere/handlers/file.clj rename to src/taoensso/telemere/file_handler.clj index 25995c3..ad8dd23 100644 --- a/src/taoensso/telemere/handlers/file.clj +++ b/src/taoensso/telemere/file_handler.clj @@ -1,4 +1,4 @@ -(ns ^:no-doc taoensso.telemere.handlers.file +(ns ^:no-doc taoensso.telemere.file-handler "Private ns, implementation detail. Core archiving file handler." (:require @@ -6,7 +6,7 @@ [taoensso.telemere.utils :as utils])) (comment - (remove-ns 'taoensso.telemere.handlers.file) + (remove-ns 'taoensso.telemere.file-handler) (:api (enc/interns-overview))) ;;;; Implementation diff --git a/src/taoensso/telemere/impl.cljc b/src/taoensso/telemere/impl.cljc index aa0b074..e479089 100644 --- a/src/taoensso/telemere/impl.cljc +++ b/src/taoensso/telemere/impl.cljc @@ -21,8 +21,6 @@ ;;;; Utils -(def auto-handlers? (enc/get-env {:as :bool, :default true} :taoensso.telemere/auto-handlers)) - #?(:clj (defmacro threaded [& body] `(let [t# (Thread. (fn [] ~@body))] (.start t#) t#))) #?(:clj diff --git a/src/taoensso/telemere/open_telemetry.clj b/src/taoensso/telemere/open_telemetry.clj index cd088eb..c290891 100644 --- a/src/taoensso/telemere/open_telemetry.clj +++ b/src/taoensso/telemere/open_telemetry.clj @@ -1,6 +1,5 @@ (ns taoensso.telemere.open-telemetry "Core OpenTelemetry handler and utils. - Telemere will attempt to load this ns automatically when possible. Needs `OpenTelemetry Java`, Ref. ." diff --git a/test/taoensso/telemere_tests.cljc b/test/taoensso/telemere_tests.cljc index 68155a7..1b0f5fb 100644 --- a/test/taoensso/telemere_tests.cljc +++ b/test/taoensso/telemere_tests.cljc @@ -14,10 +14,8 @@ #_[taoensso.telemere.streams :as streams] #?(:clj [taoensso.telemere.slf4j :as slf4j]) #?(:clj [taoensso.telemere.open-telemetry :as otel]) - #?(:clj [clojure.tools.logging :as ctl]) - - #?(:default [taoensso.telemere.handlers.console :as handlers:console]) - #?(:clj [taoensso.telemere.handlers.file :as handlers:file]))) + #?(:clj [taoensso.telemere.file-handler :as fh]) + #?(:clj [clojure.tools.logging :as ctl]))) (comment (remove-ns 'taoensso.telemere-tests) @@ -705,8 +703,6 @@ ;;;; File handler -#?(:clj (alias 'fh 'taoensso.telemere.handlers.file)) - #?(:clj (deftest _file-names [(is (= (fh/get-file-name "/logs/app.log" nil nil false) "/logs/app.log")) @@ -805,9 +801,9 @@ ;;;; Other handlers (deftest _handler-constructors - [#?(:default (is (fn? (handlers:console/handler:console)))) - #?(:cljs (is (fn? (handlers:console/handler:console-raw)))) - #?(:clj (is (fn? (handlers:file/handler:file)))) + [#?(:default (is (fn? (tel/handler:console)))) + #?(:cljs (is (fn? (tel/handler:console-raw)))) + #?(:clj (is (fn? (tel/handler:file)))) #?(:clj (is (fn? (otel/handler:open-telemetry-logger))))]) (comment (def attrs-map otel/signal->attrs-map)) 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`.