From d8ef32f088a70971fa21ce411f4518229183ec4c Mon Sep 17 00:00:00 2001 From: Peter Taoussanis Date: Thu, 14 Mar 2024 11:18:29 +0100 Subject: [PATCH] [nop] Misc housekeeping --- README.md | 2 +- resources/signal-docstrings/signal-content.txt | 8 +++++--- resources/signal-docstrings/signal-options.txt | 4 ++-- src/taoensso/telemere.cljc | 11 +++-------- src/taoensso/telemere/impl.cljc | 14 +++++++------- 5 files changed, 18 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index c2719ef..1ed5cfb 100644 --- a/README.md +++ b/README.md @@ -68,8 +68,8 @@ Telemere is **highly optimized** and offers terrific performance at any scale: Measurements: - Are **~nanoseconds per signal call** (= milliseconds per 1e6 calls) -- Taken on a 2020 Macbook Pro M1, running OpenJDK 21 - Exclude handler runtime (which depends on handler/s, is usually async) +- Taken on a 2020 Macbook Pro M1, running OpenJDK 21 **Tip**: Telemere offers extensive per-call and per-handler **filtering**, **sampling**, and **rate-limiting**. Use these to ensure that you're not capturing useless/low-value information in production. See [here](/TODO) for more tips! diff --git a/resources/signal-docstrings/signal-content.txt b/resources/signal-docstrings/signal-content.txt index bdfeb6a..08f8fe5 100644 --- a/resources/signal-docstrings/signal-content.txt +++ b/resources/signal-docstrings/signal-content.txt @@ -11,11 +11,11 @@ Default keys: `:id` - ?id of signal call (common to all signals created by signal call, contrast with `:uid`) `:uid` - ?id of signal instance (unique to each signal created by signal call, contrast with `:id`) -`:data` - Arb user-level data ?val (usu. a map) given to signal call `:msg` - Arb user-level message ?str given to signal call +`:data` - Arb user-level data ?val (usu. a map) given to signal call `:error` - Arb user-level platform ?error [2] given to signal call -`:run-form` - Unevaluated ?form given to signal macro as `:run` +`:run-form` - Unevaluated ?form given to signal call as `:run` `:run-value` - Successful return ?val of `:run` ?form `:end-instant` - Platform ?instant [1] when `:run` ?form completed `:runtime-nsecs`- ?int nanosecs runtime of `:run` ?form @@ -24,12 +24,14 @@ Default keys: `:parent` - ?{:keys [id uid]} of parent signal, present in nested signals when tracing `:location` - ?{:keys [ns file line column]} signal call location `:ns` - ?str namespace of signal call, same as (:ns location) -`:file` - ?str filename of signal call, same as (:file location) `:line` - ?int line of signal call, same as (:line location) `:column` - ?int column of signal call, same as (:column location) +`:file` - ?str filename of signal call, same as (:file location) `:sample-rate` - ?rate ∈ℝ[0,1] for combined call AND handler sampling (0.75 => allow 75% of signals, nil => allow all) + - Arb user-level ?kvs given to signal call + If anything is unclear, please ping me (@ptaoussanis) so that I can improve these docs! [1] Clj: `java.time.Instant`, Cljs: `js/Date` diff --git a/resources/signal-docstrings/signal-options.txt b/resources/signal-docstrings/signal-options.txt index 68ef23d..b48d458 100644 --- a/resources/signal-docstrings/signal-options.txt +++ b/resources/signal-docstrings/signal-options.txt @@ -6,8 +6,8 @@ Signal options (shared by `signal!`, `event!`, ...): `:id` - ?id of signal call (common to all signals created by signal call, contrast with `:uid`) `:uid` - ?id of signal instance (unique to each signal created by signal call, contrast with `:id`) -`:data` - Arb user-level ?data to incl. in signal: usu. a map `:msg` - Arb user-level ?message to incl. in signal: str or vec of strs to join (with `\space`) +`:data` - Arb user-level ?data to incl. in signal: usu. a map `:error` - Arb user-level ?error to incl. in signal: platform error [2] `:run` - ?form to execute UNCONDITIONALLY; will incl. `:run-value` in signal @@ -25,7 +25,7 @@ Signal options (shared by `signal!`, `event!`, ...): `:middleware` - ?[(fn [signal])=>modified-signal ...] call middleware `:trace?` - Should tracing be enabled for `:run` form? - - Arb user-level ?kvs to incl. in signal + - Arb user-level ?kvs to incl. in signal If anything is unclear, please ping me (@ptaoussanis) so that I can improve these docs! diff --git a/src/taoensso/telemere.cljc b/src/taoensso/telemere.cljc index df4e01d..ead9245 100644 --- a/src/taoensso/telemere.cljc +++ b/src/taoensso/telemere.cljc @@ -21,14 +21,9 @@ (enc/assert-min-encore-version [3 91 0]) ;;;; TODO -;; - Core handlers -;; - (.log js/console ) better than string stacktrace -;; - Handler utils: complete, docstrings, tests -;; - Reading plan -;; - Final polish, docstrings -;; - Initial wiki docs -;; - Explainer/demo video -;; - v1.0.0-beta1 +;; - First handlers ns +;; - Review, TODOs, missing docstrings +;; - Reading plan, wiki docs, explainer/demo video ;; ;; - First OpenTelemetry tools ;; - Update Tufte (signal API, config API, signal keys, etc.) diff --git a/src/taoensso/telemere/impl.cljc b/src/taoensso/telemere/impl.cljc index 6a4912f..dd81eba 100644 --- a/src/taoensso/telemere/impl.cljc +++ b/src/taoensso/telemere/impl.cljc @@ -379,7 +379,7 @@ '([{:as opts :keys [#_defaults #_elide? #_allow? #_expansion-id, ; Undocumented elidable? location instant uid middleware, - sample-rate ns kind id level when rate-limit, + sample-rate kind ns id level when rate-limit, ctx parent trace?, do let data msg error run & user-opts]}]) :event! ; [id] [id level-or-opts] => allowed? @@ -389,7 +389,7 @@ {:as opts :keys [#_defaults #_elide? #_allow? #_expansion-id, elidable? location instant uid middleware, - sample-rate ns kind id level when rate-limit, + sample-rate kind ns id level when rate-limit, ctx parent trace?, do let data msg error #_run & user-opts]}]) :log! ; [msg] [level-or-opts msg] => allowed? @@ -398,7 +398,7 @@ [{:as opts :keys [#_defaults #_elide? #_allow? #_expansion-id, elidable? location instant uid middleware, - sample-rate ns kind id level when rate-limit, + sample-rate kind ns id level when rate-limit, ctx parent trace?, do let data msg error #_run & user-opts]} msg]) @@ -408,7 +408,7 @@ [{:as opts :keys [#_defaults #_elide? #_allow? #_expansion-id, elidable? location instant uid middleware, - sample-rate ns kind id level when rate-limit, + sample-rate kind ns id level when rate-limit, ctx parent trace?, do let data msg error #_run & user-opts]} error]) @@ -418,7 +418,7 @@ [{:as opts :keys [#_defaults #_elide? #_allow? #_expansion-id, elidable? location instant uid middleware, - sample-rate ns kind id level when rate-limit, + sample-rate kind ns id level when rate-limit, ctx parent trace?, do let data msg error run & user-opts]} form]) @@ -428,7 +428,7 @@ [{:as opts :keys [#_defaults #_elide? #_allow? #_expansion-id, rethrow? catch-val, elidable? location instant uid middleware, - sample-rate ns kind id level when rate-limit, + sample-rate kind ns id level when rate-limit, ctx parent trace?, do let data msg error #_run & user-opts]} form]) @@ -438,7 +438,7 @@ [{:as opts :keys [#_defaults #_elide? #_allow? #_expansion-id, elidable? location instant uid middleware, - sample-rate ns kind id level when rate-limit, + sample-rate kind ns id level when rate-limit, ctx parent trace?, do let data msg error #_run & user-opts]}]) (enc/unexpected-arg! macro-id))))