[nop] Misc housekeeping

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!
 

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)
 
+<user-kvs> - 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`

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?
 
-<user-opts>    - Arb user-level ?kvs to incl. in signal
+<user-kvs> - Arb user-level ?kvs to incl. in signal
 
 If anything is unclear, please ping me (@ptaoussanis) so that I can improve these docs!
 

src/taoensso/telemere.cljc

@@ -21,14 +21,9 @@
 (enc/assert-min-encore-version [3 91 0])
 
 ;;;; TODO
-;; - Core handlers
-;;   - (.log js/console <js/Error>) 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.)

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))))