[nop] Misc housekeeping

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! 🙏
 

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

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

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

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.

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.

src/taoensso/telemere.cljc

@@ -12,9 +12,8 @@
    [taoensso.telemere.impl  :as impl]
    [taoensso.telemere.utils :as utils]
    #?(:clj     [taoensso.telemere.streams          :as streams])
-
+   #?(:default [taoensso.telemere.console-handlers :as ch])
-   #?(:default [taoensso.telemere.handlers.console :as handlers:console])
+   #?(:clj     [taoensso.telemere.file-handler     :as fh]))
-   #?(:clj     [taoensso.telemere.handlers.file    :as handlers:file]))
 
   #?(: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
-;;
+;; - Native OpenTelemetry traces and spans
-;; - Next OpenTelemetry tools (traces, etc.)
 ;; - 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)
+  #?(:default ch/handler:console)
-  #?(:cljs    handlers:console/handler:console-raw)
+  #?(:cljs    ch/handler:console-raw)
-  #?(:clj        handlers:file/handler:file))
+  #?(: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 (handler:file)]        (hf sig) (hf)))
-    (do      (let [hf (handlers/console-handler)]     (hf sig) (hf)))
+    (do      (let [hf (handler:console)]     (hf sig) (hf)))
-    #?(:cljs (let [hf (handlers/raw-console-handler)] (hf sig) (hf)))))
+    #?(:cljs (let [hf (handler:console-raw)] (hf sig) (hf)))))

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

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

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

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. <https://github.com/open-telemetry/opentelemetry-java>."

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])
+   #?(:clj [taoensso.telemere.file-handler   :as fh])
-
+   #?(:clj [clojure.tools.logging            :as ctl])))
-   #?(:default [taoensso.telemere.handlers.console :as handlers:console])
-   #?(:clj     [taoensso.telemere.handlers.file    :as handlers:file])))
 
 (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))))
+  [#?(:default (is (fn? (tel/handler:console))))
-   #?(:cljs    (is (fn? (handlers:console/handler:console-raw))))
+   #?(:cljs    (is (fn? (tel/handler:console-raw))))
-   #?(:clj     (is (fn? (handlers:file/handler:file))))
+   #?(:clj     (is (fn? (tel/handler:file))))
    #?(:clj     (is (fn? (otel/handler:open-telemetry-logger))))])
 
 (comment (def attrs-map otel/signal->attrs-map))

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`.