From 1517f30abf8a6e1a916f7f5461697f5b1ae11b78 Mon Sep 17 00:00:00 2001 From: Peter Taoussanis Date: Tue, 31 Dec 2024 09:45:16 +0100 Subject: [PATCH] [doc] [#42] Timbre shim: document different `spy` error handling --- projects/main/src/taoensso/telemere/timbre.cljc | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/projects/main/src/taoensso/telemere/timbre.cljc b/projects/main/src/taoensso/telemere/timbre.cljc index 387bcaa9..f113055f 100644 --- a/projects/main/src/taoensso/telemere/timbre.cljc +++ b/projects/main/src/taoensso/telemere/timbre.cljc @@ -99,7 +99,21 @@ #?(:clj (defmacro spy - "Prefer `telemere/spy!`." + "Prefer `telemere/spy!`. + + Note that for extra flexibility and improved interop with Open Telemetry, + this shim intentionally handles errors (forms that throw) slightly differently + to Timbre's original `spy`: + + When the given `form` throws, this shim may create an ADDITIONAL signal of + `:error` kind and level. The behaviour is equivalent to: + + (telemere/spy! level ; Creates 0/1 `:spy` signals with given/default (`:debug`) level + (telemere/catch->error! form)) ; Creates 0/1 `:error` signals with `:error` level + + The additional signal helps to separate the success and error cases for + individual filtering and/or handling." + ([ form] (enc/keep-callsite `(spy :debug nil ~form))) ([level form] (enc/keep-callsite `(spy ~level nil ~form))) ([level form-name form]