fx.observability.trace — io.github.conjurernix/fx.observability 0.0.1-alpha8

Zero-dependency distributed tracing, span lifecycles, and W3C Trace Context propagation for fx.

*default-span-reporter* clj/s

extract-trace-context clj/s

(extract-trace-context carrier)

Extracts W3C trace context from incoming request/carrier map (checks :headers, string/keyword keys).

extract-trace-context> clj/s

(extract-trace-context> carrier)

(extract-trace-context> prev-effect carrier)

Creates an effect that extracts W3C trace context from incoming carrier/headers and binds it to :fx.observability/trace-context in context for downstream operations.

format-traceparent clj/s

(format-traceparent trace-id span-id)

(format-traceparent trace-id span-id sampled?)

Formats trace context map or IDs into a valid W3C traceparent header string.

inject-trace-context clj/s

(inject-trace-context carrier trace-ctx)

Injects traceparent into carrier (or carrier's :headers if present) using active span or trace-ctx.

inject-trace-context> clj/s

(inject-trace-context> carrier)

(inject-trace-context> prev-effect carrier)

Creates an effect that injects active trace context (W3C traceparent) into carrier map.

parse-traceparent clj/s

(parse-traceparent traceparent-str)

Parses a W3C traceparent header string into a trace context map, or nil if invalid.

random-span-id clj/s

(random-span-id)

Generates a random 16-character lowercase hex string suitable for W3C span-id / parent-id.

random-trace-id clj/s

(random-trace-id)

Generates a random 32-character lowercase hex string suitable for W3C trace-id.

span-reporter-layer> clj/s

(span-reporter-layer> reporter-fn)

Creates a Layer providing :fx.observability/span-reporter.

trace-context-layer> clj/s

(trace-context-layer> trace-ctx)

Creates a Layer providing :fx.observability/trace-context.

with-span-attributes> clj/s

(with-span-attributes> attributes)

(with-span-attributes> prev-effect attributes)

Attaches key-value attribute metadata to the active execution span in context.

Example: (-> (fetch-order id) (fx.observability.trace/with-span-attributes> {:order-id id :status :pending}))

with-span-reporter> clj/s

(with-span-reporter> reporter-fn-or-eff eff-or-reporter-fn)

(with-span-reporter> prev-effect reporter-fn target-eff)

Scopes a span reporter function (fn [span-map] ...) to effect.

Example: (fx.observability.trace/with-span-reporter> (fn [span] (println "Completed span:" (:name span))) (work>))

with-span> clj/s

(with-span> span-name-or-prev body-or-span-name)

(with-span> a b c)

(with-span> prev-effect span-name attributes body-eff)

Wraps execution of effect in a named distributed tracing span. Measures elapsed nanoseconds, tracks hierarchical parent-child span IDs in context, and invokes registered span reporters on completion (success or failure).

Examples: (fx.observability.trace/with-span> "db.query" (query-db> sql)) (fx.observability.trace/with-span> "http.request" {:route "/users"} (handle-request> req)) (-> (prev-op) (fx.observability.trace/with-span> "step-2" (handle-request> req)))

with-trace-context> clj/s

(with-trace-context> trace-ctx-or-eff eff-or-trace-ctx)

(with-trace-context> prev-effect trace-ctx target-eff)

Scopes a trace context map {:trace-id ... :parent-span-id ...} to effect.

Example: (fx.observability.trace/with-trace-context> {:trace-id "..."} (handle-request> req))