luciano/telemere
1
0
Fork 0
mirror of https://github.com/taoensso/telemere.git synced 2025-12-27 21:58:26 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

[nop] Housekeeping

Browse source
This commit is contained in:
Peter Taoussanis 2024-08-13 09:19:43 +02:00
parent 4efa2656f2
commit 54494b33be
9 changed files with 51 additions and 42 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
CHANGELOG.md
View file

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

8
README.md
View file

@ -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:

6
src/taoensso/telemere.cljc
View file

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

6
src/taoensso/telemere/impl.cljc
View file

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

3
src/taoensso/telemere/sockets.clj
View file

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

28
test/taoensso/telemere_tests.cljc
View file

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

16
wiki/6-FAQ.md
View file

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

2
wiki/8-Community.md
View file

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

4
wiki/9-Maintainers.md
View file

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