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

projects/main/resources/signal-docstrings/spy!.txt

@@ -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!`:
+  - It's often useful to wrap `run` form with `catch->error!`:
-      (catch->error! ::error-id (spy! ...)).
+      (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

projects/main/resources/signal-docstrings/trace!.txt

@@ -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!`:
+  - It's often useful to wrap `run` form with `catch->error!`:
-      (catch->error! ::error-id (trace! ...)).
+      (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

projects/main/test/taoensso/telemere_tests.cljc

@@ -593,6 +593,12 @@
                                                                                                                     :cljs "(ex1!) !> cljs.core/ExceptionInfo")}))])
       (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}))
          (is (sm? (with-sig (tel/trace! (+ 1 2 3 4)))  {:run-form '(+ 1 2 3 4)}))
@@ -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}))])