diff --git a/CHANGELOG.md b/CHANGELOG.md index 3d55b76..ed468e1 100644 --- a/CHANGELOG.md +++ b/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 `:needs-stopping?` [handler dispatch opt](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:handler-dispatch-options) -* **\[mod]** Cljs handlers MUST now include stop (0) arity -* **\[mod]** Users MUST now **manually call** [`stop-handlers!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#stop-handlers!) +* **\[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) (beta 15) +* **\[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!) (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]** [#5] Added [comparison to Mulog](https://github.com/taoensso/telemere/wiki/6-FAQ#how-does-telemere-compare-to-mulog) +* **\[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) (beta 15) -- @@ -67,10 +67,10 @@ Earlier: Latest (beta 16, 15): -* **\[fix]** Broken handler ns and kind filters \[23194238] -* **\[fix]** [#10] OpenTelemetry handler: render keywords as plain strings \[6e94215e] -* **\[fix]** [#11] OpenTelemetry handler: signals without message fail \[863cea15] -* **\[fix]** [#14] File handler: Don't truncate gzip output \[2d4b0497] +* **\[fix]** Broken handler ns and kind filters \[23194238] (beta 16) +* **\[fix]** [#10] OpenTelemetry handler: render keywords as plain strings \[6e94215e] (beta 15) +* **\[fix]** [#11] OpenTelemetry handler: signals without message fail \[863cea15] (beta 15) +* **\[fix]** [#14] File handler: Don't truncate gzip output \[2d4b0497] (beta 15) -- diff --git a/README.md b/README.md index be9ebfa..097c9ba 100644 --- a/README.md +++ b/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: diff --git a/src/taoensso/telemere.cljc b/src/taoensso/telemere.cljc index d846037..f83e9d1 100644 --- a/src/taoensso/telemere.cljc +++ b/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! {:catch-sym my-err :msg_ ["Error:" my-err]} (/ 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)))) #?(: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)) diff --git a/src/taoensso/telemere/impl.cljc b/src/taoensso/telemere/impl.cljc index b244c17..2a0a9cc 100644 --- a/src/taoensso/telemere/impl.cljc +++ b/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 [[ ] [ ...]]. Useful for tests/debugging." ([ form] `(with-signals false false ~form)) diff --git a/src/taoensso/telemere/sockets.clj b/src/taoensso/telemere/sockets.clj index b8f6d47..b6e26c8 100644 --- a/src/taoensso/telemere/sockets.clj +++ b/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). diff --git a/test/taoensso/telemere_tests.cljc b/test/taoensso/telemere_tests.cljc index c20fe51..83682e1 100644 --- a/test/taoensso/telemere_tests.cljc +++ b/test/taoensso/telemere_tests.cljc @@ -26,9 +26,9 @@ (do (def ^:dynamic *dynamic-var* nil) - (def t0s "2024-06-09T21:15:20.170Z") - (def t0 (enc/as-inst t0s)) - (def udt0 (enc/as-udt t0)) + (do (def t1s "2024-01-01T01:01:01.110Z") (def t1 (enc/as-inst t1s)) (def udt1 (enc/as-udt t1))) + (do (def t2s "2024-02-02T02:02:02.120Z") (def t2 (enc/as-inst t2s)) (def udt2 (enc/as-udt t2))) + (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"]}))] - (is (enc/str-starts-with? ((tel/format-signal-fn) sig) "2024-06-09T21:15:20.170Z INFO EVENT")) + (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-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 :weekly (files/udt->edy udt0)) "2024-06-03w")) - (is (= (files/format-file-timestamp :monthly (files/udt->edy udt0)) "2024-06-01m"))])) + [(is (= (files/format-file-timestamp :daily (files/udt->edy udt1)) "2024-01-01d")) + (is (= (files/format-file-timestamp :weekly (files/udt->edy udt1)) "2024-01-01w")) + (is (= (files/format-file-timestamp :monthly (files/udt->edy udt1)) "2024-01-01m"))])) (comment (files/manage-test-files! :create)) diff --git a/wiki/6-FAQ.md b/wiki/6-FAQ.md index 44025de..237d373 100644 --- a/wiki/6-FAQ.md +++ b/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! diff --git a/wiki/8-Community.md b/wiki/8-Community.md index 27c3491..7cbed30 100644 --- a/wiki/8-Community.md +++ b/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! diff --git a/wiki/9-Maintainers.md b/wiki/9-Maintainers.md index 5840d58..a46d760 100644 --- a/wiki/9-Maintainers.md +++ b/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 . + "Sets minimum level of Telemere signals (logs) created by . 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). \ No newline at end of file +Will add more info prior to Telemere's [stable v1 release](https://www.taoensso.com/roadmap).