@nifrajs/otel 1.3.0 → 1.4.0

package/README.md

@@ -2,8 +2,9 @@
 
 Distributed tracing for nifra. The `tracing()` plugin continues (or starts) a **W3C trace** per
 request, opens an **OpenTelemetry-semantic-convention** span, and exposes `c.trace` so you can
-forward the trace to downstream services. Spans go to a **pluggable exporter** — bridge to the
-OpenTelemetry SDK, or log them directly. No SDK bundled; edge-safe.
+forward the trace to downstream services. One fail-open lifecycle owns parentage, identity, timing,
+errors, final status, and exactly-once completion. Pluggable adapters project that observation into
+the OpenTelemetry SDK, DevTools, private backends, or structured logs. No SDK bundled; edge-safe.
 
 ```ts
 import { tracing, traceHeaders, consoleSpanExporter } from "@nifrajs/otel"
@@ -26,20 +27,25 @@ const app = server()
   (`error` for 5xx, `ok` otherwise).
 - **Exposes `c.trace`** (`{ traceId, spanId, parentSpanId?, sampled, traceparent }`) — spread
   `traceHeaders(c.trace)` into any downstream `fetch`/`ctx.api` call to continue the trace.
+- **Exposes `c.observation`** — integrations can start correctly-parented child observations or
+  attach an adapter without rebuilding request lifecycle state.
 - `responseHeader: true` also sets `traceparent` on the response (browser/client correlation).
 
-## Exporters
+## Adapters
 
-Implement `SpanExporter` to send spans wherever you collect them:
+Implement `ObservationAdapter` to send spans wherever you collect them. `SpanExporter` remains as a
+backwards-compatible type alias:
 
 ```ts
-interface SpanExporter {
+interface ObservationAdapter {
   onStart?(span: NifraSpan): void
   onEnd(span: NifraSpan): void
 }
 ```
 
 - `consoleSpanExporter()` — logs each completed span as one structured line (dev / starting point).
+- `tracing({ adapters: [devtoolsAdapter, privateAdapter] })` — fan out the same lifecycle; adapter
+  failures are isolated and never alter the response.
 - **OpenTelemetry SDK bridge** — a ~10-line adapter maps `NifraSpan` onto a real OTel `Span` from a
   `Tracer` (the attribute names already follow OTel conventions, so they pass straight through). Your
   app depends on `@opentelemetry/*`; `@nifrajs/otel` does not.
@@ -50,6 +56,9 @@ Use `traceparent` and the built-in semantic attributes in every request span, th
 your own collector through an exporter. Keep the package edge-safe by installing the OpenTelemetry
 SDK only in apps that need that exporter.
 
+For non-HTTP work, `createObservationLifecycle()` exposes the same state machine directly. Prefer
+it over hand-rolling traceparent parsing, clocks, error status, or completion guards.
+
 ## For AI agents
 
 Start with [`LLM.md`](./LLM.md) — this package's contract card (the exports you call + its footguns),

package/dist/index.d.ts

@@ -8,7 +8,8 @@
  *   import { tracing, traceHeaders, consoleSpanExporter } from "@nifrajs/otel"
  *   app.use(tracing({ exporter: consoleSpanExporter(), serviceName: "orders-api" }))
  */
-export { type AttributeValue, consoleSpanExporter, type NifraSpan, type SpanExporter, type SpanStatus, } from "./span.js";
+export { type ActiveObservation, createObservationLifecycle, type EndObservation, type ObservationClock, type ObservationContext, type ObservationLifecycle, type ObservationLifecycleOptions, type ObservationParent, type StartObservation, } from "./lifecycle.js";
+export { type AttributeValue, combineObservationAdapters, consoleSpanExporter, type NifraSpan, type ObservationAdapter, type SpanExporter, type SpanStatus, } from "./span.js";
 export { formatTraceparent, generateSpanId, generateTraceId, type ParsedTraceparent, parseTraceparent, } from "./traceparent.js";
 export { type TraceContext, type TracingOptions, traceHeaders, tracing } from "./tracing.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,KAAK,cAAc,EACnB,mBAAmB,EACnB,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,UAAU,GAChB,MAAM,WAAW,CAAA;AAClB,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,KAAK,iBAAiB,EACtB,gBAAgB,GACjB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,cAAc,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,KAAK,iBAAiB,EACtB,0BAA0B,EAC1B,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,2BAA2B,EAChC,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,KAAK,cAAc,EACnB,0BAA0B,EAC1B,mBAAmB,EACnB,KAAK,SAAS,EACd,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,UAAU,GAChB,MAAM,WAAW,CAAA;AAClB,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,KAAK,iBAAiB,EACtB,gBAAgB,GACjB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,cAAc,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA"}

package/dist/index.js

@@ -8,7 +8,8 @@
  *   import { tracing, traceHeaders, consoleSpanExporter } from "@nifrajs/otel"
  *   app.use(tracing({ exporter: consoleSpanExporter(), serviceName: "orders-api" }))
  */
-export { consoleSpanExporter, } from "./span.js";
+export { createObservationLifecycle, } from "./lifecycle.js";
+export { combineObservationAdapters, consoleSpanExporter, } from "./span.js";
 export { formatTraceparent, generateSpanId, generateTraceId, parseTraceparent, } from "./traceparent.js";
 export { traceHeaders, tracing } from "./tracing.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAEL,mBAAmB,GAIpB,MAAM,WAAW,CAAA;AAClB,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,eAAe,EAEf,gBAAgB,GACjB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAA0C,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAEL,0BAA0B,GAQ3B,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAEL,0BAA0B,EAC1B,mBAAmB,GAKpB,MAAM,WAAW,CAAA;AAClB,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,eAAe,EAEf,gBAAgB,GACjB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAA0C,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA"}

package/dist/lifecycle.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The deep request-observation lifecycle. This module alone owns trace parent selection, identity,
+ * timing, error recording, final status classification, and exactly-once completion. Integrations
+ * should adapt completed spans; they should not reimplement this state machine.
+ */
+import type { AttributeValue, NifraSpan, ObservationAdapter, SpanStatus } from "./span.js";
+export interface ObservationContext {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly parentSpanId?: string;
+    readonly sampled: boolean;
+    /** This span's outbound W3C trace context. */
+    readonly traceparent: string;
+}
+export interface ObservationParent {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly sampled: boolean;
+}
+export interface StartObservation {
+    readonly name: string;
+    /** Explicit parent. `null` forces a root span; `undefined` falls back to `traceparent`. */
+    readonly parent?: ObservationParent | null;
+    /** Inbound W3C header used when `parent` is undefined. */
+    readonly traceparent?: string | null;
+    readonly attributes?: Readonly<Record<string, AttributeValue>>;
+}
+export interface EndObservation {
+    readonly statusCode?: number;
+    /** Explicit status wins over status-code and recorded-error classification. */
+    readonly status?: Exclude<SpanStatus, "unset">;
+    readonly attributes?: Readonly<Record<string, AttributeValue>>;
+}
+export interface ActiveObservation {
+    readonly span: NifraSpan;
+    readonly context: ObservationContext;
+    /** Adds a sink to this in-flight span. Re-adding the same adapter is idempotent. */
+    addAdapter(adapter: ObservationAdapter): void;
+    /** Starts a child that inherits this span's trace identity and sampling decision. */
+    startChild(input: Omit<StartObservation, "parent" | "traceparent">, additionalAdapters?: readonly ObservationAdapter[]): ActiveObservation;
+    /** Records failure evidence without deciding the final status until the response is known. */
+    recordError(error: unknown): void;
+    /** Ends and exports once. Repeated calls return the same completed span without notifying again. */
+    end(input?: EndObservation): NifraSpan;
+}
+export interface ObservationLifecycle {
+    start(input: StartObservation, additionalAdapters?: readonly ObservationAdapter[]): ActiveObservation;
+}
+export interface ObservationClock {
+    /** Epoch milliseconds for interoperable start/end timestamps. */
+    wallTime(): number;
+    /** Monotonic milliseconds for durations. */
+    monotonicTime(): number;
+}
+export interface ObservationLifecycleOptions {
+    readonly adapters?: readonly ObservationAdapter[];
+    /** Injectable seams are primarily useful for deterministic tests and constrained runtimes. */
+    readonly clock?: ObservationClock;
+    readonly generateTraceId?: () => string;
+    readonly generateSpanId?: () => string;
+}
+/** Creates an independent lifecycle factory. Adapters are always called fail-open. */
+export declare function createObservationLifecycle(options?: ObservationLifecycleOptions): ObservationLifecycle;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAQ1F,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,2FAA2F;IAC3F,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAA;IAC1C,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACpC,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAA;CAC/D;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,CAAA;IAC9C,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAA;CAC/D;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAA;IACpC,oFAAoF;IACpF,UAAU,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAAA;IAC7C,qFAAqF;IACrF,UAAU,CACR,KAAK,EAAE,IAAI,CAAC,gBAAgB,EAAE,QAAQ,GAAG,aAAa,CAAC,EACvD,kBAAkB,CAAC,EAAE,SAAS,kBAAkB,EAAE,GACjD,iBAAiB,CAAA;IACpB,8FAA8F;IAC9F,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAA;IACjC,oGAAoG;IACpG,GAAG,CAAC,KAAK,CAAC,EAAE,cAAc,GAAG,SAAS,CAAA;CACvC;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,CACH,KAAK,EAAE,gBAAgB,EACvB,kBAAkB,CAAC,EAAE,SAAS,kBAAkB,EAAE,GACjD,iBAAiB,CAAA;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,QAAQ,IAAI,MAAM,CAAA;IAClB,4CAA4C;IAC5C,aAAa,IAAI,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAA;IACjD,8FAA8F;IAC9F,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAA;IACjC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,MAAM,CAAA;IACvC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,MAAM,CAAA;CACvC;AAUD,sFAAsF;AACtF,wBAAgB,0BAA0B,CACxC,OAAO,GAAE,2BAAgC,GACxC,oBAAoB,CAkHtB"}

package/dist/lifecycle.js

@@ -0,0 +1,121 @@
+/**
+ * The deep request-observation lifecycle. This module alone owns trace parent selection, identity,
+ * timing, error recording, final status classification, and exactly-once completion. Integrations
+ * should adapt completed spans; they should not reimplement this state machine.
+ */
+import { formatTraceparent, generateSpanId, generateTraceId, parseTraceparent, } from "./traceparent.js";
+const defaultClock = {
+    wallTime: () => Date.now(),
+    monotonicTime: () => (typeof performance === "undefined" ? Date.now() : performance.now()),
+};
+const errorMessage = (error) => error instanceof Error ? error.message : String(error);
+/** Creates an independent lifecycle factory. Adapters are always called fail-open. */
+export function createObservationLifecycle(options = {}) {
+    const adapters = options.adapters ?? [];
+    const clock = options.clock ?? defaultClock;
+    const newTraceId = options.generateTraceId ?? generateTraceId;
+    const newSpanId = options.generateSpanId ?? generateSpanId;
+    const notifyStart = (span, spanAdapters) => {
+        for (const adapter of spanAdapters) {
+            try {
+                adapter.onStart?.(span);
+            }
+            catch {
+                // Observation must never change request behavior.
+            }
+        }
+    };
+    const notifyEnd = (span, spanAdapters) => {
+        for (const adapter of spanAdapters) {
+            try {
+                adapter.onEnd(span);
+            }
+            catch {
+                // Observation must never change request behavior.
+            }
+        }
+    };
+    const start = (input, additionalAdapters = []) => {
+        const spanAdapters = new Set([...adapters, ...additionalAdapters]);
+        const parent = input.parent === undefined ? parseTraceparent(input.traceparent ?? null) : input.parent;
+        const traceId = parent?.traceId ?? newTraceId();
+        const spanId = newSpanId();
+        const sampled = parent?.sampled ?? true;
+        const startTime = clock.wallTime();
+        const monotonicStart = clock.monotonicTime();
+        const span = {
+            traceId,
+            spanId,
+            ...(parent === null ? {} : { parentSpanId: parent.spanId }),
+            sampled,
+            name: input.name,
+            startTime,
+            status: "unset",
+            attributes: { ...input.attributes },
+        };
+        const context = {
+            traceId,
+            spanId,
+            ...(parent === null ? {} : { parentSpanId: parent.spanId }),
+            sampled,
+            traceparent: formatTraceparent(traceId, spanId, sampled),
+        };
+        let recordedError = false;
+        let ended = false;
+        const active = {
+            span,
+            context,
+            addAdapter(adapter) {
+                if (ended || spanAdapters.has(adapter))
+                    return;
+                spanAdapters.add(adapter);
+                try {
+                    adapter.onStart?.(span);
+                }
+                catch {
+                    // Dynamic adapters have the same fail-open guarantee as initial adapters.
+                }
+            },
+            startChild(child, childAdapters) {
+                return start({
+                    ...child,
+                    parent: context,
+                }, childAdapters);
+            },
+            recordError(error) {
+                if (ended)
+                    return;
+                recordedError = true;
+                span.attributes["error.message"] = errorMessage(error);
+            },
+            end(endInput = {}) {
+                if (ended)
+                    return span;
+                ended = true;
+                Object.assign(span.attributes, endInput.attributes);
+                span.endTime = clock.wallTime();
+                span.durationMs = Math.max(0, clock.monotonicTime() - monotonicStart);
+                span.status =
+                    endInput.status ??
+                        (endInput.statusCode === undefined
+                            ? recordedError
+                                ? "error"
+                                : "ok"
+                            : endInput.statusCode >= 500
+                                ? "error"
+                                : "ok");
+                // Publish an immutable completed span: a misbehaving adapter can no longer mutate the shared
+                // attributes bag and corrupt what other adapters (or the caller) observe. Adapters are fail-open,
+                // so a stray write throws into their own try/catch rather than changing request behavior.
+                Object.freeze(span.attributes);
+                Object.freeze(span);
+                notifyEnd(span, [...spanAdapters]);
+                return span;
+            },
+        };
+        notifyStart(span, [...spanAdapters]);
+        return active;
+    };
+    return { start };
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"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"}

package/dist/span.d.ts

@@ -1,7 +1,8 @@
 /**
  * The span model + exporter seam. Attribute names follow OpenTelemetry HTTP semantic conventions
  * (`http.request.method`, `url.path`, `http.response.status_code`, …) so a span maps cleanly onto an
- * OTel `Span` when bridged — but nothing here depends on the OTel SDK. You supply a {@link SpanExporter}
+ * OTel `Span` when bridged — but nothing here depends on the OTel SDK. You supply an
+ * {@link ObservationAdapter}
  * (a ~10-line adapter to `@opentelemetry/api`, or the bundled {@link consoleSpanExporter}).
  */
 export type SpanStatus = "unset" | "ok" | "error";
@@ -33,10 +34,17 @@ export interface NifraSpan {
  * real `Span` from a `Tracer`), ship to a collector, or just log. `onStart` is optional (most
  * backends only need the completed span).
  */
-export interface SpanExporter {
+export interface ObservationAdapter {
     onStart?(span: NifraSpan): void;
     onEnd(span: NifraSpan): void;
 }
+/** Backwards-compatible name for an observation sink. */
+export type SpanExporter = ObservationAdapter;
+/**
+ * Fan out lifecycle notifications to several adapters. Each adapter is isolated: an exception in
+ * one sink cannot prevent the remaining sinks from observing the span.
+ */
+export declare function combineObservationAdapters(adapters: readonly ObservationAdapter[]): ObservationAdapter;
 /** A no-frills exporter that logs each completed span as one structured line. Useful in dev or as a
  * starting point before wiring a real backend. */
 export declare function consoleSpanExporter(log?: (line: string) => void): SpanExporter;

package/dist/span.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"span.d.ts","sourceRoot":"","sources":["../src/span.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,IAAI,GAAG,OAAO,CAAA;AACjD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAEtD,8DAA8D;AAC9D,MAAM,WAAW,SAAS;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,mCAAmC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,UAAU,CAAA;IAClB,2CAA2C;IAC3C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;CACpD;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAAA;IAC/B,KAAK,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAAA;CAC7B;AAED;kDACkD;AAClD,wBAAgB,mBAAmB,CACjC,GAAG,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAEtB,GACA,YAAY,CAgBd"}
+{"version":3,"file":"span.d.ts","sourceRoot":"","sources":["../src/span.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,IAAI,GAAG,OAAO,CAAA;AACjD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAEtD,8DAA8D;AAC9D,MAAM,WAAW,SAAS;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,mCAAmC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,UAAU,CAAA;IAClB,2CAA2C;IAC3C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;CACpD;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAAA;IAC/B,KAAK,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAAA;CAC7B;AAED,yDAAyD;AACzD,MAAM,MAAM,YAAY,GAAG,kBAAkB,CAAA;AAE7C;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,GACtC,kBAAkB,CAqBpB;AAED;kDACkD;AAClD,wBAAgB,mBAAmB,CACjC,GAAG,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAEtB,GACA,YAAY,CAgBd"}

package/dist/span.js

@@ -1,9 +1,38 @@
 /**
  * The span model + exporter seam. Attribute names follow OpenTelemetry HTTP semantic conventions
  * (`http.request.method`, `url.path`, `http.response.status_code`, …) so a span maps cleanly onto an
- * OTel `Span` when bridged — but nothing here depends on the OTel SDK. You supply a {@link SpanExporter}
+ * OTel `Span` when bridged — but nothing here depends on the OTel SDK. You supply an
+ * {@link ObservationAdapter}
  * (a ~10-line adapter to `@opentelemetry/api`, or the bundled {@link consoleSpanExporter}).
  */
+/**
+ * Fan out lifecycle notifications to several adapters. Each adapter is isolated: an exception in
+ * one sink cannot prevent the remaining sinks from observing the span.
+ */
+export function combineObservationAdapters(adapters) {
+    return {
+        onStart(span) {
+            for (const adapter of adapters) {
+                try {
+                    adapter.onStart?.(span);
+                }
+                catch {
+                    // Observation is fail-open by contract.
+                }
+            }
+        },
+        onEnd(span) {
+            for (const adapter of adapters) {
+                try {
+                    adapter.onEnd(span);
+                }
+                catch {
+                    // Observation is fail-open by contract.
+                }
+            }
+        },
+    };
+}
 /** A no-frills exporter that logs each completed span as one structured line. Useful in dev or as a
  * starting point before wiring a real backend. */
 export function consoleSpanExporter(log = (l) => {

package/dist/span.js.map

@@ -1 +1 @@
-{"version":3,"file":"span.js","sourceRoot":"","sources":["../src/span.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAsCH;kDACkD;AAClD,MAAM,UAAU,mBAAmB,CACjC,MAA8B,CAAC,CAAC,EAAE,EAAE;IAClC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;AAChB,CAAC;IAED,OAAO;QACL,KAAK,CAAC,IAAI;YACR,GAAG,CACD,IAAI,CAAC,SAAS,CAAC;gBACb,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,YAAY,EAAE,IAAI,CAAC,YAAY;gBAC/B,UAAU,EAAE,IAAI,CAAC,UAAU;gBAC3B,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,GAAG,IAAI,CAAC,UAAU;aACnB,CAAC,CACH,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC"}
+{"version":3,"file":"span.js","sourceRoot":"","sources":["../src/span.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAyCH;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CACxC,QAAuC;IAEvC,OAAO;QACL,OAAO,CAAC,IAAI;YACV,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;gBAC/B,IAAI,CAAC;oBACH,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,CAAA;gBACzB,CAAC;gBAAC,MAAM,CAAC;oBACP,wCAAwC;gBAC1C,CAAC;YACH,CAAC;QACH,CAAC;QACD,KAAK,CAAC,IAAI;YACR,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;gBAC/B,IAAI,CAAC;oBACH,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;gBACrB,CAAC;gBAAC,MAAM,CAAC;oBACP,wCAAwC;gBAC1C,CAAC;YACH,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED;kDACkD;AAClD,MAAM,UAAU,mBAAmB,CACjC,MAA8B,CAAC,CAAC,EAAE,EAAE;IAClC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;AAChB,CAAC;IAED,OAAO;QACL,KAAK,CAAC,IAAI;YACR,GAAG,CACD,IAAI,CAAC,SAAS,CAAC;gBACb,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,YAAY,EAAE,IAAI,CAAC,YAAY;gBAC/B,UAAU,EAAE,IAAI,CAAC,UAAU;gBAC3B,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,GAAG,IAAI,CAAC,UAAU;aACnB,CAAC,CACH,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/tracing.d.ts

@@ -4,19 +4,15 @@
  * (traceparent) and attribute names (HTTP semantic conventions); the span itself is exported through
  * your {@link SpanExporter} (bridge to the OTel SDK, or log via `consoleSpanExporter`).
  */
-import { type SpanExporter } from "./span.js";
+import { type ObservationContext } from "./lifecycle.js";
+import { type ObservationAdapter, type SpanExporter } from "./span.js";
 /** The trace context exposed on the handler `c.trace` (typed, threaded via `derive`). */
-export interface TraceContext {
-    readonly traceId: string;
-    readonly spanId: string;
-    readonly parentSpanId?: string;
-    readonly sampled: boolean;
-    /** This request's outbound `traceparent` — forward it on downstream calls to continue the trace. */
-    readonly traceparent: string;
-}
+export type TraceContext = ObservationContext;
 export interface TracingOptions {
     /** Where spans are sent. Default: {@link consoleSpanExporter}. */
     readonly exporter?: SpanExporter;
+    /** Additional observation adapters (DevTools, a private redacting backend, metrics, …). */
+    readonly adapters?: readonly ObservationAdapter[];
     /** Sets the `service.name` attribute on every span. */
     readonly serviceName?: string;
     /**

package/dist/tracing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../src/tracing.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,WAAW,CAAA;AAQlB,yFAAyF;AACzF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,oGAAoG;IACpG,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAA;IAChC,uDAAuD;IACvD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAA;CAClC;AAED;uDACuD;AACvD,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,CAEzE;AAUD;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,OAAO,GAAE,cAAmB,oHA2DnD"}
+{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../src/tracing.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAuB,KAAK,kBAAkB,EAAE,KAAK,YAAY,EAAE,MAAM,WAAW,CAAA;AAE3F,yFAAyF;AACzF,MAAM,MAAM,YAAY,GAAG,kBAAkB,CAAA;AAE7C,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAA;IAChC,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAA;IACjD,uDAAuD;IACvD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAA;CAClC;AAED;uDACuD;AACvD,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,CAEzE;AAUD;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,OAAO,GAAE,cAAmB,oHAuDnD"}

package/dist/tracing.js

@@ -5,8 +5,8 @@
  * your {@link SpanExporter} (bridge to the OTel SDK, or log via `consoleSpanExporter`).
  */
 import { definePlugin } from "@nifrajs/core";
-import { consoleSpanExporter, } from "./span.js";
-import { formatTraceparent, generateSpanId, generateTraceId, parseTraceparent, } from "./traceparent.js";
+import { createObservationLifecycle, } from "./lifecycle.js";
+import { consoleSpanExporter } from "./span.js";
 /** Spread into an outgoing `fetch`/`ctx.api` call's headers to continue the trace downstream:
  * `fetch(url, { headers: traceHeaders(c.trace) })`. */
 export function traceHeaders(trace) {
@@ -30,61 +30,56 @@ const pathOf = (url) => {
  * ```
  */
 export function tracing(options = {}) {
-    const exporter = options.exporter ?? consoleSpanExporter();
+    const adapters = [
+        ...(options.exporter === undefined && options.adapters === undefined
+            ? [consoleSpanExporter()]
+            : options.exporter === undefined
+                ? []
+                : [options.exporter]),
+        ...(options.adapters ?? []),
+    ];
+    const lifecycle = createObservationLifecycle({ adapters });
     const serviceName = options.serviceName;
-    // Span per in-flight request, keyed by the Request — ended in onResponse (mirrors @nifrajs/middleware
-    // timing). A WeakMap so an abandoned request can't leak a span.
+    // A WeakMap so an abandoned request cannot leak its active observation.
     const inFlight = new WeakMap();
     return definePlugin("tracing", (app) => app
         .derive((c) => {
-        const parent = parseTraceparent(c.req.headers.get("traceparent"));
-        const traceId = parent?.traceId ?? generateTraceId();
-        const spanId = generateSpanId();
-        const sampled = parent?.sampled ?? true;
         const path = pathOf(c.req.url);
-        const attributes = {
-            "http.request.method": c.req.method,
-            "url.path": path,
-        };
-        if (serviceName !== undefined)
-            attributes["service.name"] = serviceName;
-        const span = {
-            traceId,
-            spanId,
-            ...(parent !== null ? { parentSpanId: parent.spanId } : {}),
-            sampled,
+        const observation = lifecycle.start({
             name: `${c.req.method} ${path}`,
-            startTime: Date.now(),
-            status: "unset",
-            attributes,
-        };
-        inFlight.set(c.req, span);
-        exporter.onStart?.(span);
-        const traceparent = formatTraceparent(traceId, spanId, sampled);
+            traceparent: c.req.headers.get("traceparent"),
+            attributes: {
+                "http.request.method": c.req.method,
+                "url.path": path,
+                ...(serviceName === undefined ? {} : { "service.name": serviceName }),
+            },
+        });
+        inFlight.set(c.req, observation);
         if (options.responseHeader)
-            c.set.headers.traceparent = traceparent;
-        const trace = {
-            traceId,
-            spanId,
-            ...(parent !== null ? { parentSpanId: parent.spanId } : {}),
-            sampled,
-            traceparent,
-        };
-        return { trace };
+            c.set.headers.traceparent = observation.context.traceparent;
+        return { trace: observation.context, observation };
     })
         .use({
         name: "tracing-end",
+        onError: (error, context) => {
+            inFlight.get(context.request)?.recordError(error);
+            return undefined;
+        },
         onResponse: (res, req) => {
-            const span = inFlight.get(req);
-            if (span === undefined)
+            const observation = inFlight.get(req);
+            if (observation === undefined)
                 return res;
             inFlight.delete(req);
-            span.endTime = Date.now();
-            span.durationMs = span.endTime - span.startTime;
-            span.attributes["http.response.status_code"] = res.status;
-            // 5xx is a server error; everything else (incl. handled 4xx) is a normal outcome.
-            span.status = res.status >= 500 ? "error" : "ok";
-            exporter.onEnd(span);
+            const bodySize = Number(res.headers.get("content-length") ?? "0") || 0;
+            const isrStatus = res.headers.get("x-nifra-isr");
+            observation.end({
+                statusCode: res.status,
+                attributes: {
+                    "http.response.status_code": res.status,
+                    "http.response.body.size": bodySize,
+                    ...(isrStatus === null ? {} : { "nifra.isr.status": isrStatus }),
+                },
+            });
             return res;
         },
     }));

package/dist/tracing.js.map

@@ -1 +1 @@
-{"version":3,"file":"tracing.js","sourceRoot":"","sources":["../src/tracing.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tracing.js","sourceRoot":"","sources":["../src/tracing.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/otel",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Distributed tracing for nifra — W3C traceparent/tracestate propagation + OpenTelemetry-semantic-convention spans via a pluggable exporter. Bridge to the OpenTelemetry SDK or log spans directly; no SDK bundled. Edge-safe.",
   "keywords": [
     "bun",
@@ -39,7 +39,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@nifrajs/core": "^1.3.0"
+    "@nifrajs/core": "^1.4.0"
   },
   "devDependencies": {
     "@nifrajs/core": "workspace:*"

package/src/index.ts

@@ -9,10 +9,23 @@
  *   app.use(tracing({ exporter: consoleSpanExporter(), serviceName: "orders-api" }))
  */
 
+export {
+  type ActiveObservation,
+  createObservationLifecycle,
+  type EndObservation,
+  type ObservationClock,
+  type ObservationContext,
+  type ObservationLifecycle,
+  type ObservationLifecycleOptions,
+  type ObservationParent,
+  type StartObservation,
+} from "./lifecycle.ts"
 export {
   type AttributeValue,
+  combineObservationAdapters,
   consoleSpanExporter,
   type NifraSpan,
+  type ObservationAdapter,
   type SpanExporter,
   type SpanStatus,
 } from "./span.ts"

package/src/lifecycle.ts

@@ -0,0 +1,209 @@
+/**
+ * The deep request-observation lifecycle. This module alone owns trace parent selection, identity,
+ * timing, error recording, final status classification, and exactly-once completion. Integrations
+ * should adapt completed spans; they should not reimplement this state machine.
+ */
+
+import type { AttributeValue, NifraSpan, ObservationAdapter, SpanStatus } from "./span.ts"
+import {
+  formatTraceparent,
+  generateSpanId,
+  generateTraceId,
+  parseTraceparent,
+} from "./traceparent.ts"
+
+export interface ObservationContext {
+  readonly traceId: string
+  readonly spanId: string
+  readonly parentSpanId?: string
+  readonly sampled: boolean
+  /** This span's outbound W3C trace context. */
+  readonly traceparent: string
+}
+
+export interface ObservationParent {
+  readonly traceId: string
+  readonly spanId: string
+  readonly sampled: boolean
+}
+
+export interface StartObservation {
+  readonly name: string
+  /** Explicit parent. `null` forces a root span; `undefined` falls back to `traceparent`. */
+  readonly parent?: ObservationParent | null
+  /** Inbound W3C header used when `parent` is undefined. */
+  readonly traceparent?: string | null
+  readonly attributes?: Readonly<Record<string, AttributeValue>>
+}
+
+export interface EndObservation {
+  readonly statusCode?: number
+  /** Explicit status wins over status-code and recorded-error classification. */
+  readonly status?: Exclude<SpanStatus, "unset">
+  readonly attributes?: Readonly<Record<string, AttributeValue>>
+}
+
+export interface ActiveObservation {
+  readonly span: NifraSpan
+  readonly context: ObservationContext
+  /** Adds a sink to this in-flight span. Re-adding the same adapter is idempotent. */
+  addAdapter(adapter: ObservationAdapter): void
+  /** Starts a child that inherits this span's trace identity and sampling decision. */
+  startChild(
+    input: Omit<StartObservation, "parent" | "traceparent">,
+    additionalAdapters?: readonly ObservationAdapter[],
+  ): ActiveObservation
+  /** Records failure evidence without deciding the final status until the response is known. */
+  recordError(error: unknown): void
+  /** Ends and exports once. Repeated calls return the same completed span without notifying again. */
+  end(input?: EndObservation): NifraSpan
+}
+
+export interface ObservationLifecycle {
+  start(
+    input: StartObservation,
+    additionalAdapters?: readonly ObservationAdapter[],
+  ): ActiveObservation
+}
+
+export interface ObservationClock {
+  /** Epoch milliseconds for interoperable start/end timestamps. */
+  wallTime(): number
+  /** Monotonic milliseconds for durations. */
+  monotonicTime(): number
+}
+
+export interface ObservationLifecycleOptions {
+  readonly adapters?: readonly ObservationAdapter[]
+  /** Injectable seams are primarily useful for deterministic tests and constrained runtimes. */
+  readonly clock?: ObservationClock
+  readonly generateTraceId?: () => string
+  readonly generateSpanId?: () => string
+}
+
+const defaultClock: ObservationClock = {
+  wallTime: () => Date.now(),
+  monotonicTime: () => (typeof performance === "undefined" ? Date.now() : performance.now()),
+}
+
+const errorMessage = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error)
+
+/** Creates an independent lifecycle factory. Adapters are always called fail-open. */
+export function createObservationLifecycle(
+  options: ObservationLifecycleOptions = {},
+): ObservationLifecycle {
+  const adapters = options.adapters ?? []
+  const clock = options.clock ?? defaultClock
+  const newTraceId = options.generateTraceId ?? generateTraceId
+  const newSpanId = options.generateSpanId ?? generateSpanId
+
+  const notifyStart = (span: NifraSpan, spanAdapters: readonly ObservationAdapter[]): void => {
+    for (const adapter of spanAdapters) {
+      try {
+        adapter.onStart?.(span)
+      } catch {
+        // Observation must never change request behavior.
+      }
+    }
+  }
+
+  const notifyEnd = (span: NifraSpan, spanAdapters: readonly ObservationAdapter[]): void => {
+    for (const adapter of spanAdapters) {
+      try {
+        adapter.onEnd(span)
+      } catch {
+        // Observation must never change request behavior.
+      }
+    }
+  }
+
+  const start = (
+    input: StartObservation,
+    additionalAdapters: readonly ObservationAdapter[] = [],
+  ): ActiveObservation => {
+    const spanAdapters = new Set([...adapters, ...additionalAdapters])
+    const parent =
+      input.parent === undefined ? parseTraceparent(input.traceparent ?? null) : input.parent
+    const traceId = parent?.traceId ?? newTraceId()
+    const spanId = newSpanId()
+    const sampled = parent?.sampled ?? true
+    const startTime = clock.wallTime()
+    const monotonicStart = clock.monotonicTime()
+    const span: NifraSpan = {
+      traceId,
+      spanId,
+      ...(parent === null ? {} : { parentSpanId: parent.spanId }),
+      sampled,
+      name: input.name,
+      startTime,
+      status: "unset",
+      attributes: { ...input.attributes },
+    }
+    const context: ObservationContext = {
+      traceId,
+      spanId,
+      ...(parent === null ? {} : { parentSpanId: parent.spanId }),
+      sampled,
+      traceparent: formatTraceparent(traceId, spanId, sampled),
+    }
+    let recordedError = false
+    let ended = false
+
+    const active: ActiveObservation = {
+      span,
+      context,
+      addAdapter(adapter) {
+        if (ended || spanAdapters.has(adapter)) return
+        spanAdapters.add(adapter)
+        try {
+          adapter.onStart?.(span)
+        } catch {
+          // Dynamic adapters have the same fail-open guarantee as initial adapters.
+        }
+      },
+      startChild(child, childAdapters) {
+        return start(
+          {
+            ...child,
+            parent: context,
+          },
+          childAdapters,
+        )
+      },
+      recordError(error) {
+        if (ended) return
+        recordedError = true
+        span.attributes["error.message"] = errorMessage(error)
+      },
+      end(endInput = {}) {
+        if (ended) return span
+        ended = true
+        Object.assign(span.attributes, endInput.attributes)
+        span.endTime = clock.wallTime()
+        span.durationMs = Math.max(0, clock.monotonicTime() - monotonicStart)
+        span.status =
+          endInput.status ??
+          (endInput.statusCode === undefined
+            ? recordedError
+              ? "error"
+              : "ok"
+            : endInput.statusCode >= 500
+              ? "error"
+              : "ok")
+        // Publish an immutable completed span: a misbehaving adapter can no longer mutate the shared
+        // attributes bag and corrupt what other adapters (or the caller) observe. Adapters are fail-open,
+        // so a stray write throws into their own try/catch rather than changing request behavior.
+        Object.freeze(span.attributes)
+        Object.freeze(span)
+        notifyEnd(span, [...spanAdapters])
+        return span
+      },
+    }
+
+    notifyStart(span, [...spanAdapters])
+    return active
+  }
+
+  return { start }
+}

package/src/span.ts

@@ -1,7 +1,8 @@
 /**
  * The span model + exporter seam. Attribute names follow OpenTelemetry HTTP semantic conventions
  * (`http.request.method`, `url.path`, `http.response.status_code`, …) so a span maps cleanly onto an
- * OTel `Span` when bridged — but nothing here depends on the OTel SDK. You supply a {@link SpanExporter}
+ * OTel `Span` when bridged — but nothing here depends on the OTel SDK. You supply an
+ * {@link ObservationAdapter}
  * (a ~10-line adapter to `@opentelemetry/api`, or the bundled {@link consoleSpanExporter}).
  */
 
@@ -36,11 +37,43 @@ export interface NifraSpan {
  * real `Span` from a `Tracer`), ship to a collector, or just log. `onStart` is optional (most
  * backends only need the completed span).
  */
-export interface SpanExporter {
+export interface ObservationAdapter {
   onStart?(span: NifraSpan): void
   onEnd(span: NifraSpan): void
 }
 
+/** Backwards-compatible name for an observation sink. */
+export type SpanExporter = ObservationAdapter
+
+/**
+ * Fan out lifecycle notifications to several adapters. Each adapter is isolated: an exception in
+ * one sink cannot prevent the remaining sinks from observing the span.
+ */
+export function combineObservationAdapters(
+  adapters: readonly ObservationAdapter[],
+): ObservationAdapter {
+  return {
+    onStart(span) {
+      for (const adapter of adapters) {
+        try {
+          adapter.onStart?.(span)
+        } catch {
+          // Observation is fail-open by contract.
+        }
+      }
+    },
+    onEnd(span) {
+      for (const adapter of adapters) {
+        try {
+          adapter.onEnd(span)
+        } catch {
+          // Observation is fail-open by contract.
+        }
+      }
+    },
+  }
+}
+
 /** A no-frills exporter that logs each completed span as one structured line. Useful in dev or as a
  * starting point before wiring a real backend. */
 export function consoleSpanExporter(

package/src/tracing.ts

@@ -7,31 +7,20 @@
 
 import { definePlugin } from "@nifrajs/core"
 import {
-  type AttributeValue,
-  consoleSpanExporter,
-  type NifraSpan,
-  type SpanExporter,
-} from "./span.ts"
-import {
-  formatTraceparent,
-  generateSpanId,
-  generateTraceId,
-  parseTraceparent,
-} from "./traceparent.ts"
+  type ActiveObservation,
+  createObservationLifecycle,
+  type ObservationContext,
+} from "./lifecycle.ts"
+import { consoleSpanExporter, type ObservationAdapter, type SpanExporter } from "./span.ts"
 
 /** The trace context exposed on the handler `c.trace` (typed, threaded via `derive`). */
-export interface TraceContext {
-  readonly traceId: string
-  readonly spanId: string
-  readonly parentSpanId?: string
-  readonly sampled: boolean
-  /** This request's outbound `traceparent` — forward it on downstream calls to continue the trace. */
-  readonly traceparent: string
-}
+export type TraceContext = ObservationContext
 
 export interface TracingOptions {
   /** Where spans are sent. Default: {@link consoleSpanExporter}. */
   readonly exporter?: SpanExporter
+  /** Additional observation adapters (DevTools, a private redacting backend, metrics, …). */
+  readonly adapters?: readonly ObservationAdapter[]
   /** Sets the `service.name` attribute on every span. */
   readonly serviceName?: string
   /**
@@ -65,60 +54,56 @@ const pathOf = (url: string): string => {
  * ```
  */
 export function tracing(options: TracingOptions = {}) {
-  const exporter = options.exporter ?? consoleSpanExporter()
+  const adapters: ObservationAdapter[] = [
+    ...(options.exporter === undefined && options.adapters === undefined
+      ? [consoleSpanExporter()]
+      : options.exporter === undefined
+        ? []
+        : [options.exporter]),
+    ...(options.adapters ?? []),
+  ]
+  const lifecycle = createObservationLifecycle({ adapters })
   const serviceName = options.serviceName
-  // Span per in-flight request, keyed by the Request — ended in onResponse (mirrors @nifrajs/middleware
-  // timing). A WeakMap so an abandoned request can't leak a span.
-  const inFlight = new WeakMap<Request, NifraSpan>()
+  // A WeakMap so an abandoned request cannot leak its active observation.
+  const inFlight = new WeakMap<Request, ActiveObservation>()
 
   return definePlugin("tracing", (app) =>
     app
       .derive((c) => {
-        const parent = parseTraceparent(c.req.headers.get("traceparent"))
-        const traceId = parent?.traceId ?? generateTraceId()
-        const spanId = generateSpanId()
-        const sampled = parent?.sampled ?? true
         const path = pathOf(c.req.url)
-        const attributes: Record<string, AttributeValue> = {
-          "http.request.method": c.req.method,
-          "url.path": path,
-        }
-        if (serviceName !== undefined) attributes["service.name"] = serviceName
-        const span: NifraSpan = {
-          traceId,
-          spanId,
-          ...(parent !== null ? { parentSpanId: parent.spanId } : {}),
-          sampled,
+        const observation = lifecycle.start({
           name: `${c.req.method} ${path}`,
-          startTime: Date.now(),
-          status: "unset",
-          attributes,
-        }
-        inFlight.set(c.req, span)
-        exporter.onStart?.(span)
-        const traceparent = formatTraceparent(traceId, spanId, sampled)
-        if (options.responseHeader) c.set.headers.traceparent = traceparent
-        const trace: TraceContext = {
-          traceId,
-          spanId,
-          ...(parent !== null ? { parentSpanId: parent.spanId } : {}),
-          sampled,
-          traceparent,
-        }
-        return { trace }
+          traceparent: c.req.headers.get("traceparent"),
+          attributes: {
+            "http.request.method": c.req.method,
+            "url.path": path,
+            ...(serviceName === undefined ? {} : { "service.name": serviceName }),
+          },
+        })
+        inFlight.set(c.req, observation)
+        if (options.responseHeader) c.set.headers.traceparent = observation.context.traceparent
+        return { trace: observation.context, observation }
       })
       .use({
         name: "tracing-end",
+        onError: (error, context) => {
+          inFlight.get(context.request)?.recordError(error)
+          return undefined
+        },
         onResponse: (res, req) => {
-          const span = inFlight.get(req)
-          if (span === undefined) return res
+          const observation = inFlight.get(req)
+          if (observation === undefined) return res
           inFlight.delete(req)
-          span.endTime = Date.now()
-          span.durationMs = span.endTime - span.startTime
-          span.attributes["http.response.status_code"] = res.status
-          // 5xx is a server error; everything else (incl. handled 4xx) is a normal outcome.
-          span.status = res.status >= 500 ? "error" : "ok"
-          exporter.onEnd(span)
+          const bodySize = Number(res.headers.get("content-length") ?? "0") || 0
+          const isrStatus = res.headers.get("x-nifra-isr")
+          observation.end({
+            statusCode: res.status,
+            attributes: {
+              "http.response.status_code": res.status,
+              "http.response.body.size": bodySize,
+              ...(isrStatus === null ? {} : { "nifra.isr.status": isrStatus }),
+            },
+          })
           return res
         },
       }),