luciano/telemere
1
0
Fork 0
mirror of https://github.com/taoensso/telemere.git synced 2025-12-16 17:41:12 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

[doc] Better document pattern of using trace!/spy! with catch->error!

Browse source
This commit is contained in:
Peter Taoussanis 2024-12-23 09:55:13 +01:00
parent 0de5c094e5
commit 5c977a348b
3 changed files with 38 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
projects/main/resources/signal-docstrings/spy!.txt
View file

@ -53,8 +53,18 @@ Tips:
- Execution of `run` form may create additional (nested) signals.
Each signal's `:parent` key will indicate its immediate parent.
- Can be useful to wrap with `catch->error!`:
(catch->error! ::error-id (spy! ...)).
- It's often useful to wrap `run` form with `catch->error!`:
(trace! ::trace-id (catch->error! ::error-id ...)).
This way you have independent filtering for `run` forms that throw,
allowing you to use a higher min level and/or reduced sampling, etc.
In this case you'll create:
0 or 1 `:trace` signals (depending on filtering), AND
0 or 1 `:error` signals (depending on filtering).
Note that the `:error` signal will contain tracing info (e.g. `:parent` key)
iff the enclosing `trace!` is allowed.
- Runtime of async or lazy code in `run` form will intentionally NOT be
included in resulting signal's `:run-nsecs` value. If you want to measure

14
projects/main/resources/signal-docstrings/trace!.txt
View file

@ -53,8 +53,18 @@ Tips:
- Execution of `run` form may create additional (nested) signals.
Each signal's `:parent` key will indicate its immediate parent.
- Can be useful to wrap with `catch->error!`:
(catch->error! ::error-id (trace! ...)).
- It's often useful to wrap `run` form with `catch->error!`:
(trace! ::trace-id (catch->error! ::error-id ...)).
This way you have independent filtering for `run` forms that throw,
allowing you to use a higher min level and/or reduced sampling, etc.
In this case you'll create:
0 or 1 `:trace` signals (depending on filtering), AND
0 or 1 `:error` signals (depending on filtering).
Note that the `:error` signal will contain tracing info (e.g. `:parent` key)
iff the enclosing `trace!` is allowed.
- Default level is `:info`, not `:trace`! The name "trace" in "trace signal"
refers to the general action of tracing program flow rather than to the

16
projects/main/test/taoensso/telemere_tests.cljc
View file

@ -591,7 +591,13 @@
(let [[[_ re] [sv]] (with-sigs (tel/trace! :id1 (ex1!))) ] [(is (ex1? re)) (is (sm? sv {:kind :trace, :line :submap/some, :level :info, :id :id1, :error pex1?,
:msg_ #?(:clj "(ex1!) !> clojure.lang.ExceptionInfo"
:cljs "(ex1!) !> cljs.core/ExceptionInfo")}))])
(let [[[rv] [sv]] (with-sigs (tel/trace! {:allow? false} (+ 1 2))) ] [(is (= rv 3)) (is (nil? sv))])
(let [[[rv] [sv]] (with-sigs (tel/trace! {:allow? false} (+ 1 2)))] [(is (= rv 3)) (is (nil? sv))])
(testing "Use with `catch->error!`"
(let [[[_ re] [sv1 sv2]] (with-sigs (tel/trace! ::id1 (tel/catch->error! ::id2 (ex1!))))]
[(is (ex1? re))
(is (sm? sv1 {:kind :error, :line :submap/some, :level :error, :id ::id2, :error ex1, :parent {:id ::id1}}))
(is (sm? sv2 {:kind :trace, :line :submap/some, :level :info, :id ::id1, :error ex1, :root {:id ::id1}}))]))
(testing ":run-form" ; Undocumented, experimental
[(is (sm? (with-sig (tel/trace! :non-list)) {:run-form :non-list}))
@ -612,7 +618,13 @@
(let [[[_ re] [sv]] (with-sigs (tel/spy! :warn (ex1!)))] [(is (ex1? re)) (is (sm? sv {:kind :spy, :line :submap/some, :level :warn, :error pex1?,
:msg_ #?(:clj "(ex1!) !> clojure.lang.ExceptionInfo"
:cljs "(ex1!) !> cljs.core/ExceptionInfo")}))])
(let [[[rv] [sv]] (with-sigs (tel/spy! {:allow? false} (+ 1 2))) ] [(is (= rv 3)) (is (nil? sv))])])
(let [[[rv] [sv]] (with-sigs (tel/spy! {:allow? false} (+ 1 2))) ] [(is (= rv 3)) (is (nil? sv))])
(testing "Use with `catch->error!`"
(let [[[_ re] [sv1 sv2]] (with-sigs (tel/spy! :warn (tel/catch->error! :error (ex1!))))]
[(is (ex1? re))
(is (sm? sv1 {:kind :error, :line :submap/some, :level :error, :error ex1, :parent {}}))
(is (sm? sv2 {:kind :spy, :line :submap/some, :level :warn, :error ex1, :root {}}))]))])
(testing "error!" ; ?id + error => unconditional given error
[(let [[[rv] [sv]] (with-sigs (tel/error! ex1)) ] [(is (ex1? rv)) (is (sm? sv {:kind :error, :line :submap/some, :level :error, :error pex1?, :id nil}))])