[nop] Housekeeping

CHANGELOG.md

@@ -19,10 +19,10 @@ Please **report any unexpected problems** on [GitHub](https://github.com/taoenss
 
 Latest (beta 16, 15):
 
-* **\[mod]** Removed `*auto-stop-handlers?*` var
+* **\[mod]** Removed `*auto-stop-handlers?*` var (beta 15)
-* **\[mod]** Removed `:needs-stopping?` [handler dispatch opt](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:handler-dispatch-options)
+* **\[mod]** Removed `:needs-stopping?` [handler dispatch opt](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:handler-dispatch-options) (beta 15)
-* **\[mod]** Cljs handlers MUST now include stop (0) arity
+* **\[mod]** Cljs handlers MUST now include stop (0) arity (beta 15)
-* **\[mod]** Users MUST now **manually call** [`stop-handlers!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#stop-handlers!)
+* **\[mod]** Users MUST now **manually call** [`stop-handlers!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#stop-handlers!) (beta 15)
 
 --
 
@@ -42,8 +42,8 @@ Earlier:
 
 Latest (beta 16, 15):
 
-* **\[new]** Ongoing [API](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere) and [wiki](https://github.com/taoensso/telemere/wiki) doc improvements
+* **\[new]** Ongoing [API](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere) and [wiki](https://github.com/taoensso/telemere/wiki) doc improvements (beta 15)
-* **\[new]** [#5] Added [comparison to Mulog](https://github.com/taoensso/telemere/wiki/6-FAQ#how-does-telemere-compare-to-mulog)
+* **\[new]** [#5] Added [comparison to Mulog](https://github.com/taoensso/telemere/wiki/6-FAQ#how-does-telemere-compare-to-mulog) (beta 15)
 
 --
 
@@ -67,10 +67,10 @@ Earlier:
 
 Latest (beta 16, 15):
 
-* **\[fix]** Broken handler ns and kind filters \[23194238]
+* **\[fix]** Broken handler ns and kind filters \[23194238] (beta 16)
-* **\[fix]** [#10] OpenTelemetry handler: render keywords as plain strings \[6e94215e]
+* **\[fix]** [#10] OpenTelemetry handler: render keywords as plain strings \[6e94215e] (beta 15)
-* **\[fix]** [#11] OpenTelemetry handler: signals without message fail \[863cea15]
+* **\[fix]** [#11] OpenTelemetry handler: signals without message fail \[863cea15] (beta 15)
-* **\[fix]** [#14] File handler: Don't truncate gzip output \[2d4b0497]
+* **\[fix]** [#14] File handler: Don't truncate gzip output \[2d4b0497] (beta 15)
 
 --
 

README.md

@@ -198,9 +198,15 @@ See [here](../../wiki/4-Handlers) for more/upcoming handlers, community handlers
 - [Wiki][GitHub wiki] (getting started, usage, etc.)
 - API reference via [cljdoc][cljdoc docs] or [Codox][Codox docs]
 - Extensive [internal help](#internal-help) (no need to leave your IDE)
-- Support via [Slack channel][] or [GitHub issues][]
+- Support via [#Telemere Slack channel][] or [GitHub issues][]
 - [General observability tips](../../wiki/7-Tips) (advice on building and maintaining observable Clojure/Script systems, and getting the most out of Telemere)
 
+## Community
+
+My plan for Telemere is to offer a **stable core of limited scope**, then to focus on making it as easy for the **community** to write additional stuff like handlers, middleware, and utils.
+
+See [here](../../wiki/8-Community) for community resources.
+
 ## Benchmarks
 
 Telemere is **highly optimized** and offers terrific performance at any scale:

src/taoensso/telemere.cljc

@@ -151,8 +151,8 @@
 
 (comment
   (with-signal (catch->error! ::my-id (/ 1 0)))
-  (with-signal (catch->error! {                  :msg_ ["Error:" __caught-error]} (/ 1 0)))
+  (with-signal (catch->error! {                  :msg ["Error:" __caught-error]} (/ 1 0)))
-  (with-signal (catch->error! {:catch-sym my-err :msg_ ["Error:" my-err]}         (/ 1 0))))
+  (with-signal (catch->error! {:catch-sym my-err :msg ["Error:" my-err]}         (/ 1 0))))
 
 #?(:clj
    (defmacro trace!
@@ -333,3 +333,5 @@
     (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)))))
+
+(comment (let [[_ [s1 s2]] (with-signals (trace! ::id1 (trace! ::id2 "form2")))] s1))

src/taoensso/telemere/impl.cljc

@@ -207,7 +207,7 @@
 (do     (enc/def-print-impl [sig Signal] (str "#" `Signal (pr-str (into {} sig)))))
 #?(:clj (enc/def-print-dup  [sig Signal] (str "#" `Signal (pr-str (into {} sig))))) ; NB intentionally verbose, to support extra keys
 
-(def ^:no-doc standard-signal-keys "Private, don't use."  (set (keys (map->Signal {:schema 0}))))
+(def standard-signal-keys (set (keys (map->Signal {:schema 0}))))
 
 (comment
   (def s1 (with-signal (signal! {:level :info, :my-k1 :my-v1})))
@@ -252,7 +252,7 @@
 
 #?(:clj
    (defmacro ^:public with-signal
-     "Experimental.
+     "Experimental, subject to change.
      Executes given form, trapping errors. Returns the LAST signal created by form.
      Useful for tests/debugging.
 
@@ -279,7 +279,7 @@
 
 #?(:clj
    (defmacro ^:public with-signals
-     "Experimental.
+     "Experimental, subject to change.
      Like `with-signal` but returns [[<form-value> <form-error>] [<signal1> ...]].
      Useful for tests/debugging."
      ([                        form] `(with-signals false false          ~form))

src/taoensso/telemere/sockets.clj

@@ -48,7 +48,8 @@
           (sw output)))))))
 
 (defn handler:udp-socket
-  "Experimental, subject to change. Feedback welcome!
+  "Highly experimental, subject to change.
+  Feedback very welcome!
 
   Returns a signal handler that:
     - Takes a Telemere signal (map).

test/taoensso/telemere_tests.cljc

@@ -26,9 +26,9 @@
 (do
   (def ^:dynamic *dynamic-var* nil)
 
-  (def   t0s "2024-06-09T21:15:20.170Z")
+  (do (def t1s "2024-01-01T01:01:01.110Z") (def t1 (enc/as-inst t1s)) (def udt1 (enc/as-udt t1)))
-  (def   t0  (enc/as-inst t0s))
+  (do (def t2s "2024-02-02T02:02:02.120Z") (def t2 (enc/as-inst t2s)) (def udt2 (enc/as-udt t2)))
-  (def udt0  (enc/as-udt  t0))
+  (do (def t3s "2024-03-03T03:03:03.130Z") (def t3 (enc/as-inst t3s)) (def udt3 (enc/as-udt t3)))
 
   (def  ex-info-type (#'enc/ex-type (ex-info "" {})))
   (def  ex1 (ex-info "Ex1" {}))
@@ -707,7 +707,7 @@
 
    (testing "Formatters, etc."
      [(is (= ((utils/format-nsecs-fn) 1.5e9) "1.50s")) ; More tests in Encore
-      (is (= ((utils/format-inst-fn)     t0) "2024-06-09T21:15:20.170Z"))
+      (is (= ((utils/format-inst-fn)     t1) "2024-01-01T01:01:01.110Z"))
 
       (testing "format-error-fn"
         (let [ex2-str ((utils/format-error-fn) ex2)]
@@ -719,14 +719,14 @@
            (is (enc/str-contains? ex2-str "invoke") "Root stack trace includes content")]))
 
       (testing "signal-preamble-fn"
-        (let [sig      (with-sig :raw :trap (tel/event! ::ev-id {:inst t0, :msg ["a" "b"]}))
+        (let [sig      (with-sig :raw :trap (tel/event! ::ev-id {:inst t1, :msg ["a" "b"]}))
               preamble ((utils/signal-preamble-fn) sig)] ; "2024-06-09T21:15:20.170Z INFO EVENT taoensso.telemere-tests(592,35) ::ev-id"
-          [(is (enc/str-starts-with? preamble "2024-06-09T21:15:20.170Z INFO EVENT"))
+          [(is (enc/str-starts-with? preamble "2024-01-01T01:01:01.110Z INFO EVENT"))
            (is (enc/str-ends-with?   preamble "::ev-id - a b"))
            (is (string? (re-find #"taoensso.telemere-tests\(\d+,\d+\)" preamble)))]))
 
       (testing "pr-signal-fn"
-        (let [sig (with-sig :raw :trap (tel/event! ::ev-id {:inst t0, :msg ["a" "b"]}))]
+        (let [sig (with-sig :raw :trap (tel/event! ::ev-id {:inst t1, :msg ["a" "b"]}))]
 
           [(testing ":edn pr-fn"
              (let [sig   (update sig :inst enc/inst->udt)
@@ -739,7 +739,7 @@
                     {:schema 1, :kind :event, :id ::ev-id, :level :info,
                      :ns      "taoensso.telemere-tests"
                      :msg_    "a b"
-                     :inst    udt0
+                     :inst    udt1
                      :line    pnat-int?
                      :column  pnat-int?}))]))
 
@@ -751,7 +751,7 @@
                       {"schema" 1, "kind" "event", "id" "taoensso.telemere-tests/ev-id",
                        "level" "info",             "ns" "taoensso.telemere-tests"
                        "msg_"    "a b"
-                       "inst"    t0s
+                       "inst"    t1s
                        "line"    pnat-int?
                        "column"  pnat-int?})))))
 
@@ -778,8 +778,8 @@
                                                                                     :location "loc", :kvs "kvs", :file "file", :thread "thread"}))]))]))
 
       (testing "format-signal-fn"
-        (let [sig (with-sig :raw :trap (tel/event! ::ev-id {:inst t0, :msg ["a" "b"]}))]
+        (let [sig (with-sig :raw :trap (tel/event! ::ev-id {:inst t1, :msg ["a" "b"]}))]
-          (is (enc/str-starts-with? ((tel/format-signal-fn) sig) "2024-06-09T21:15:20.170Z INFO EVENT"))
+          (is (enc/str-starts-with? ((tel/format-signal-fn) sig) "2024-01-01T01:01:01.110Z INFO EVENT"))
           (is (enc/str-ends-with?   ((tel/format-signal-fn) sig) "::ev-id - a b\n"))))])])
 
 ;;;; File handler
@@ -796,9 +796,9 @@
 
 #?(:clj
    (deftest _file-timestamps
-     [(is (= (files/format-file-timestamp :daily   (files/udt->edy udt0)) "2024-06-09d"))
+     [(is (= (files/format-file-timestamp :daily   (files/udt->edy udt1)) "2024-01-01d"))
-      (is (= (files/format-file-timestamp :weekly  (files/udt->edy udt0)) "2024-06-03w"))
+      (is (= (files/format-file-timestamp :weekly  (files/udt->edy udt1)) "2024-01-01w"))
-      (is (= (files/format-file-timestamp :monthly (files/udt->edy udt0)) "2024-06-01m"))]))
+      (is (= (files/format-file-timestamp :monthly (files/udt->edy udt1)) "2024-01-01m"))]))
 
 (comment (files/manage-test-files! :create))
 

wiki/6-FAQ.md

@@ -127,6 +127,14 @@ Some **similarities** between Telemere and Mulog:
 - Both are **fast** and offer **async handling**
 - Both offer a variety of **handlers** and are designed for ease of use
 
+Some particular **strengths of Mulog** that I'm aware of:
+
+- More **established/mature**
+- Wider **range of handlers** (incl. Kafka, Kinesis, Prometheus, Zipkin, etc.)
+- More **community resources** (videos, guides, users, etc.)
+- **Smaller code** base (Telemere currently depends on [Encore](https://github.com/taoensso/encore))
+- There may be others!
+
 Some particular **strengths of Telemere**:
 
 - Both **Clj and Cljs support** (Mulog is Clj only)
@@ -138,14 +146,6 @@ Some particular **strengths of Telemere**:
 - Lazy `:let`, `:data`, `:msg`, `:do` - evaluated only **after filtering**
 - Extensive [in-IDE documentation](./1-Getting-started#internal-help)
 
-Some particular **strengths of Mulog** that I'm aware of:
-
-- More **established/mature**
-- Wider **range of handlers** (incl. Kafka, Kinesis, Prometheus, Zipkin, etc.)
-- More **community resources** (videos, guides, users, etc.)
-- **Smaller code** base (Telemere currently depends on [Encore](https://github.com/taoensso/encore))
-- There may be others!
-
 **My subjective thoughts**:
 
 Mulog is an awesome, well-designed library with quality documentation and a solid API. It's **absolutely worth checking out** - you may well prefer it to Telemere!

wiki/8-Community.md

@@ -1,4 +1,4 @@
-My plan is for Telemere to offer a **stable core of limited scope**, and leave it to the **community** to author additional stuff like handlers, middleware, and utils.
+My plan for Telemere is to offer a **stable core of limited scope**, then to focus on making it as easy for the **community** to write additional stuff like handlers, middleware, and utils.
 
 **PRs very welcome** to add links to this page!
 

wiki/9-Maintainers.md

@@ -32,7 +32,7 @@ The most common thing library users may want to do is **adjust the minimum level
 
 ```clojure
 (defn set-min-log-level!
-  "Sets minimum level of Telemere signals (logs) generated by <my-library>.
+  "Sets minimum level of Telemere signals (logs) created by <my-library>.
   Possible levels (from most to least verbose):
     #{:trace :debug :info :warn :error :fatal :report}.
 
@@ -75,4 +75,4 @@ Example migration steps:
 
 In this case you'll need to decide if you want to use Telemere as an [optional](#telemere-as-an-optional-dependency) or [non-optional](#telemere-as-a-non-optional-dependency) dependency.
 
-Will add more info prior to Telemere's [stable v1 release](https://www.taoensso.com/roadmap).
+Will add more info prior to Telemere's [stable v1 release](https://www.taoensso.com/roadmap).