[new] OpenTelemetry handler: support spans created outside Telemere

BEFORE this commit:

  Telemere captured OpenTelemetry context only when generating
  tracing signals (`trace!`, `spy!`, etc.).

AFTER this commit:

  Telemere always captures OpenTelemetry context when present.

Motivation for the change:

  Telemere users may have spans automatically created by the
  OpenTelemetry Java Agent, or manually created by other libs
  like clj-otel.

  By always capturing the OpenTelemetry context when present,
  this lets even non-tracing Telemere signals (like `log!`)
  include the relevant trace and span IDs for external tooling.

Thanks to @devurandom for suggesting this, and for helping
debug/identify the necessary changes 🙏

main/resources/docs/signal-options.txt

@@ -26,7 +26,7 @@ All options are available for all signal creator calls:
 
 `:elidable?` --- Should signal be subject to compile-time elision? (default true)
 `:allow?` ------ Custom override for usual runtime filtering (true => ALWAYS create signal)
-`:trace?` ------ Should tracing be enabled for `:run` form?
+`:trace?` ------ Should tracing be enabled for this signal? (default true iff `:run` provided or OpenTelemetry tracing enabled)
 
 `:sample` ------ Sample ?rate ∈ℝ[0,1] for random signal sampling (0.75 => allow 75% of signals, nil => allow all)
 `:when` -------- Arb ?form; when present, form must return truthy to allow signal

main/src/taoensso/telemere/impl.cljc

@@ -569,7 +569,10 @@
                  id-form    :id
                  level-form :level} opts
 
-                trace? (get opts :trace? run-form?)
+                otel?         (get opts :otel? (and clj? present:otel?)) ; Undocumented
+                otel-tracing? (and otel? enabled:otel-tracing?)
+
+                trace? (get opts :trace? (or run-form? otel-tracing?))
                 _
                 (when-not (contains? #{true false nil} trace?)
                   (truss/ex-info!
@@ -614,7 +617,7 @@
                                 :sample :ns :kind :id :level :filter :when #_:limit #_:limit-by,
                                 :ctx :ctx+ :parent :trace?, :do :let :data :msg :error,
                                 :run :run-form :run-val, :elide? :allow? #_:callsite-id,
-                                :host :thread :otel/context))]
+                                :host :thread :otel? :otel/context))]
 
                         (if-let [kvs+ (get opts :kvs+)] ; Undocumented
                           (if base
@@ -638,10 +641,10 @@
                       (let [record-form
                             (let   [clause [(if run-form? :run :no-run) (if clj? :clj :cljs)]]
                               (case clause
-                                [:run    :clj ]  `(Signal. 1 ~'__inst ~'__uid, ~'__ns ~coords ~host-form ~'__thread ~'__otel-context, ~sample-form, ~'__kind ~'__id ~'__level, ~ctx-form ~parent-form ~'__root1, ~data-form ~kvs-form ~'_msg_,   ~'_run-err  '~show-run-form ~show-run-val ~'_end-inst ~'_run-nsecs)
-                                [:run    :cljs]  `(Signal. 1 ~'__inst ~'__uid, ~'__ns ~coords                                         ~sample-form, ~'__kind ~'__id ~'__level, ~ctx-form ~parent-form ~'__root1, ~data-form ~kvs-form ~'_msg_,   ~'_run-err  '~show-run-form ~show-run-val ~'_end-inst ~'_run-nsecs)
-                                [:no-run :clj ]  `(Signal. 1 ~'__inst ~'__uid, ~'__ns ~coords ~host-form ~'__thread ~'__otel-context, ~sample-form, ~'__kind ~'__id ~'__level, ~ctx-form ~parent-form ~'__root1, ~data-form ~kvs-form ~msg-form, ~error-form nil             nil           nil         nil)
-                                [:no-run :cljs]  `(Signal. 1 ~'__inst ~'__uid, ~'__ns ~coords                                         ~sample-form, ~'__kind ~'__id ~'__level, ~ctx-form ~parent-form ~'__root1, ~data-form ~kvs-form ~msg-form, ~error-form nil             nil           nil         nil)
+                                [:run    :clj ]  `(Signal. 1 ~'__inst ~'__uid, ~'__ns ~coords ~host-form ~'__thread ~'__otel-context1, ~sample-form, ~'__kind ~'__id ~'__level, ~ctx-form ~parent-form ~'__root1, ~data-form ~kvs-form ~'_msg_,   ~'_run-err  '~show-run-form ~show-run-val ~'_end-inst ~'_run-nsecs)
+                                [:run    :cljs]  `(Signal. 1 ~'__inst ~'__uid, ~'__ns ~coords                                          ~sample-form, ~'__kind ~'__id ~'__level, ~ctx-form ~parent-form ~'__root1, ~data-form ~kvs-form ~'_msg_,   ~'_run-err  '~show-run-form ~show-run-val ~'_end-inst ~'_run-nsecs)
+                                [:no-run :clj ]  `(Signal. 1 ~'__inst ~'__uid, ~'__ns ~coords ~host-form ~'__thread ~'__otel-context1, ~sample-form, ~'__kind ~'__id ~'__level, ~ctx-form ~parent-form ~'__root1, ~data-form ~kvs-form ~msg-form, ~error-form nil             nil           nil         nil)
+                                [:no-run :cljs]  `(Signal. 1 ~'__inst ~'__uid, ~'__ns ~coords                                          ~sample-form, ~'__kind ~'__id ~'__level, ~ctx-form ~parent-form ~'__root1, ~data-form ~kvs-form ~msg-form, ~error-form nil             nil           nil         nil)
                                 (truss/ex-info!
                                   (str "Unexpected signal constructor args at "
                                     (sigs/format-callsite ns-form coords)))))
@@ -682,26 +685,12 @@
                 run-fn-form (when run-form? `(fn [] ~run-form))
                 run-form*   (when run-form? `(~'__run-fn-form))
 
-                binds-form-base
-                `[~'__inst   ~inst-form
-                  ~'__thread ~thread-form
-                  ~'__root0  ~root-form0 ; ?{:keys [id uid]}
-
-                  ~'__otel-context
-                  ~(when (and clj? enabled:otel-tracing?)
-                     (if run-form?
-                       `(otel-context+span ~'__id ~'__inst ~(get opts :otel/context `(otel-context)) ~(get opts :otel/span-kind))
-                       (do                                  (get opts :otel/context `(otel-context)))))
-
-                  ~'__uid
-                  ~(if (and clj? enabled:otel-tracing? trace?)
-                     (auto-> uid-form `(or (otel-span-id ~'__otel-context) (com.taoensso.encore.Ids/genHexId16)))
-                     (auto-> uid-form `(taoensso.telemere/*uid-fn* (if ~'__root0 false true))))]
-
-                binds-form-more
+                into-let-form
                 (enc/cond!
-                  (not trace?) ; Non-tracing signal
-                  `[~'__root1 ~'__root0 ; Retain, but don't establish
+                  (not trace?) ; Don't trace
+                  `[~'__otel-context1 nil
+                    ~'__uid   ~(auto-> uid-form `(taoensso.telemere/*uid-fn* (if ~'__root0 false true)))
+                    ~'__root1 ~'__root0 ; Retain, but don't establish
                     ~'__run-result
                     ~(when run-form?
                        `(let [t0# (enc/now-nano*)]
@@ -710,8 +699,10 @@
                             (catch :all t# (RunResult. nil        t#  (- (enc/now-nano*) t0#))))))]
 
                   ;; Trace without OpenTelemetry
-                  (or cljs? (not enabled:otel-tracing?))
-                  `[~'__root1 (or ~'__root0 ~(when trace? `{:id ~'__id, :uid ~'__uid}))
+                  (or cljs? (not otel-tracing?))
+                  `[~'__otel-context1 nil
+                    ~'__uid  ~(auto-> uid-form `(taoensso.telemere/*uid-fn* (if ~'__root0 false true)))
+                    ~'__root1 (or ~'__root0 ~(when trace? `{:id ~'__id, :uid ~'__uid}))
                     ~'__run-result
                     ~(when run-form?
                        `(binding [*trace-root*   ~'__root1
@@ -722,18 +713,21 @@
                               (catch :all t# (RunResult. nil        t#  (- (enc/now-nano*) t0#)))))))]
 
                   ;; Trace with OpenTelemetry
-                  (and clj? enabled:otel-tracing?)
-                  `[~'__root1
+                  (and clj? otel-tracing?)
+                  `[~'__otel-context0  ~(get opts :otel/context `(otel-context)) ; Context
+                    ~'__otel-context1  ~(if run-form? `(otel-context+span ~'__id ~'__inst ~'__otel-context0 ~(get opts :otel/span-kind)) `~'__otel-context0)
+                    ~'__uid            ~(auto-> uid-form `(or (otel-span-id ~'__otel-context1) (com.taoensso.encore.Ids/genHexId16)))
+                    ~'__root1
                     (or ~'__root0
                       ~(when trace?
-                         `{:id ~'__id, :uid (or (otel-trace-id ~'__otel-context) (com.taoensso.encore.Ids/genHexId32))}))
+                         `{:id ~'__id, :uid (or (otel-trace-id ~'__otel-context1) (com.taoensso.encore.Ids/genHexId32))}))
 
                     ~'__run-result
                     ~(when run-form?
-                       `(binding [*otel-context* ~'__otel-context
+                       `(binding [*otel-context* ~'__otel-context1
                                   *trace-root*   ~'__root1
                                   *trace-parent* {:id ~'__id, :uid ~'__uid}]
-                          (let [otel-scope# (.makeCurrent ~'__otel-context)
+                          (let [otel-scope# (.makeCurrent ~'__otel-context1)
                                 t0#         (enc/now-nano*)]
                             (truss/try*
                               (do            (RunResult. ~run-form* nil (- (enc/now-nano*) t0#)))
@@ -750,8 +744,11 @@
 
                   (enc/if-not ~allow?
                     ~run-form*
-                    (let [~@binds-form-base
-                          ~@binds-form-more
+                    (let [~'__inst   ~inst-form
+                          ~'__thread ~thread-form
+                          ~'__root0  ~root-form0 ; ?{:keys [id uid]}
+
+                          ~@into-let-form ; Inject conditional bindings
                           signal# ~signal-delay-form]
 
                       (dispatch-signal!

main/test/taoensso/telemere_tests.cljc

@@ -447,10 +447,10 @@
         (let [sv (with-sig (sig! {:level :info, :parent {:uid :uid1, :foo :bar}}))] (is (sm? sv {:parent {:id :submap/nx :uid      :uid1, :foo :bar}}) "Manual `:parent/uid`"))
         (let [sv (with-sig (sig! {:level :info, :root   {:id   :id1, :foo :bar}}))] (is (sm? sv {:root   {:id :id1       :uid :submap/nx, :foo :bar}}) "Manual `:root/id`"))
         (let [sv (with-sig (sig! {:level :info, :root   {:uid :uid1, :foo :bar}}))] (is (sm? sv {:root   {:id :submap/nx :uid      :uid1, :foo :bar}}) "Manual `:root/uid`"))
-        (let [sv (with-sig (sig! {:level :info}))                                 ] (is (sm? sv {:uid nil})))
+        (let [sv (with-sig (sig! {:level :info, :otel? false}))                   ] (is (sm? sv {:uid nil})))
         (let [sv (with-sig (sig! {:level :info, :uid :auto}))                     ] (is (sm? sv {:uid string?})))
         (let [sv (binding [tel/*uid-fn* (fn [_] "my-uid")]
-                   (with-sig (sig! {:level :info, :uid :auto})))                  ] (is (sm? sv {:uid "my-uid"})))])
+                   (with-sig (sig! {:level :info, :uid :auto, :otel? false})))    ] (is (sm? sv {:uid "my-uid"})))])
 
      (testing "Auto parent/root"
        [(testing "Tracing disabled"
@@ -882,7 +882,7 @@
              (is (= ((tel/pr-signal-fn {:pr-fn (fn [_] "str")}) sig) (str "str" utils/newline))))]))
 
       (testing "format-signal-fn"
-        (let [sig (with-sig :raw :trap (tel/event! ::ev-id {:inst t1, :msg ["a" "b"]}))]
+        (let [sig (with-sig :raw :trap (tel/event! ::ev-id {:inst t1, :msg ["a" "b"], :otel? false}))]
           [(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) (dissoc sig :host)) "::ev-id a b\n"))]))])])