@nifrajs/otel 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nifra Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+# @nifrajs/otel
+
+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.
+
+```ts
+import { tracing, traceHeaders, consoleSpanExporter } from "@nifrajs/otel"
+
+const app = server()
+  .use(tracing({ exporter: consoleSpanExporter(), serviceName: "orders-api" }))
+  .get("/orders/:id", async (c) => {
+    // continue the trace into a downstream call:
+    const res = await fetch(`${INVENTORY_URL}/stock`, { headers: traceHeaders(c.trace) })
+    return { id: c.params.id, inStock: (await res.json()).ok }
+  })
+```
+
+## What it does per request
+
+- **Continues an inbound trace** — parses the `traceparent` header; reuses its `trace-id` and records
+  the inbound span as the parent. No inbound header → starts a fresh trace.
+- **Opens a span** with HTTP semantic-convention attributes (`http.request.method`, `url.path`,
+  `http.response.status_code`, optional `service.name`), ended on response with duration + status
+  (`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.
+- `responseHeader: true` also sets `traceparent` on the response (browser/client correlation).
+
+## Exporters
+
+Implement `SpanExporter` to send spans wherever you collect them:
+
+```ts
+interface SpanExporter {
+  onStart?(span: NifraSpan): void
+  onEnd(span: NifraSpan): void
+}
+```
+
+- `consoleSpanExporter()` — logs each completed span as one structured line (dev / starting point).
+- **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.
+
+## Connect your collector
+
+Use `traceparent` and the built-in semantic attributes in every request span, then send spans to
+your own collector through an exporter. Keep the package edge-safe by installing the OpenTelemetry
+SDK only in apps that need that exporter.

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @nifrajs/otel — 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 with `traceHeaders(c.trace)`. Spans go to a pluggable
+ * `SpanExporter` — bridge to the OpenTelemetry SDK, or log with `consoleSpanExporter`. No SDK
+ * bundled; edge-safe.
+ *
+ *   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 { 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

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * @nifrajs/otel — 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 with `traceHeaders(c.trace)`. Spans go to a pluggable
+ * `SpanExporter` — bridge to the OpenTelemetry SDK, or log with `consoleSpanExporter`. No SDK
+ * bundled; edge-safe.
+ *
+ *   import { tracing, traceHeaders, consoleSpanExporter } from "@nifrajs/otel"
+ *   app.use(tracing({ exporter: consoleSpanExporter(), serviceName: "orders-api" }))
+ */
+export { 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

@@ -0,0 +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"}

package/dist/span.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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}
+ * (a ~10-line adapter to `@opentelemetry/api`, or the bundled {@link consoleSpanExporter}).
+ */
+export type SpanStatus = "unset" | "ok" | "error";
+export type AttributeValue = string | number | boolean;
+/** A completed (or in-flight) server span for one request. */
+export interface NifraSpan {
+    /** 32-hex W3C trace id — shared across every span/service in the trace. */
+    readonly traceId: string;
+    /** 16-hex id of this span. */
+    readonly spanId: string;
+    /** The inbound span's id, if this request continued an upstream trace. */
+    readonly parentSpanId?: string;
+    /** Whether the trace is sampled (the W3C flag). */
+    readonly sampled: boolean;
+    /** Span name — `"<METHOD> <path>"`. */
+    readonly name: string;
+    /** Wall-clock start (epoch ms). */
+    readonly startTime: number;
+    /** Wall-clock end (epoch ms) — set on completion. */
+    endTime?: number;
+    /** Duration in ms (monotonic). */
+    durationMs?: number;
+    status: SpanStatus;
+    /** OTel-semantic-convention attributes. */
+    readonly attributes: Record<string, AttributeValue>;
+}
+/**
+ * Where ended spans go. Implement this to bridge to the OpenTelemetry SDK (map each field onto a
+ * 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 {
+    onStart?(span: NifraSpan): void;
+    onEnd(span: NifraSpan): void;
+}
+/** 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;
+//# sourceMappingURL=span.d.ts.map

package/dist/span.d.ts.map

@@ -0,0 +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"}

package/dist/span.js

@@ -0,0 +1,26 @@
+/**
+ * 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}
+ * (a ~10-line adapter to `@opentelemetry/api`, or the bundled {@link consoleSpanExporter}).
+ */
+/** 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) => {
+    console.log(l);
+}) {
+    return {
+        onEnd(span) {
+            log(JSON.stringify({
+                name: span.name,
+                traceId: span.traceId,
+                spanId: span.spanId,
+                parentSpanId: span.parentSpanId,
+                durationMs: span.durationMs,
+                status: span.status,
+                ...span.attributes,
+            }));
+        },
+    };
+}
+//# sourceMappingURL=span.js.map

package/dist/span.js.map

@@ -0,0 +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"}

package/dist/traceparent.d.ts

@@ -0,0 +1,27 @@
+/**
+ * W3C Trace Context — `traceparent` parsing/formatting + id generation. This is OpenTelemetry's
+ * wire format for propagating a trace across services, so producing/forwarding it correctly is the
+ * core of distributed tracing regardless of which backend ends up collecting the spans.
+ *
+ *   traceparent: 00-<32-hex trace-id>-<16-hex span-id>-<2-hex flags>
+ *
+ * Pure + dependency-free; the request plugin is a thin layer over this.
+ */
+/** A parsed inbound `traceparent`. */
+export interface ParsedTraceparent {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly sampled: boolean;
+}
+/**
+ * Parse a `traceparent` header, or `null` if it's absent/malformed/version-unknown — per the spec,
+ * a bad header means "start a fresh trace", never an error. Only version `00` is accepted.
+ */
+export declare function parseTraceparent(header: string | null | undefined): ParsedTraceparent | null;
+/** Format a `traceparent` header value (version `00`). */
+export declare function formatTraceparent(traceId: string, spanId: string, sampled: boolean): string;
+/** A fresh 16-byte (32-hex) trace id. */
+export declare function generateTraceId(): string;
+/** A fresh 8-byte (16-hex) span id. */
+export declare function generateSpanId(): string;
+//# sourceMappingURL=traceparent.d.ts.map

package/dist/traceparent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceparent.d.ts","sourceRoot":"","sources":["../src/traceparent.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,sCAAsC;AACtC,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;AAMD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,iBAAiB,GAAG,IAAI,CAW5F;AAED,0DAA0D;AAC1D,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAE3F;AAQD,yCAAyC;AACzC,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,uCAAuC;AACvC,wBAAgB,cAAc,IAAI,MAAM,CAEvC"}

package/dist/traceparent.js

@@ -0,0 +1,53 @@
+/**
+ * W3C Trace Context — `traceparent` parsing/formatting + id generation. This is OpenTelemetry's
+ * wire format for propagating a trace across services, so producing/forwarding it correctly is the
+ * core of distributed tracing regardless of which backend ends up collecting the spans.
+ *
+ *   traceparent: 00-<32-hex trace-id>-<16-hex span-id>-<2-hex flags>
+ *
+ * Pure + dependency-free; the request plugin is a thin layer over this.
+ */
+const HEX = /^[0-9a-f]+$/;
+const ZERO_TRACE = "00000000000000000000000000000000";
+const ZERO_SPAN = "0000000000000000";
+/**
+ * Parse a `traceparent` header, or `null` if it's absent/malformed/version-unknown — per the spec,
+ * a bad header means "start a fresh trace", never an error. Only version `00` is accepted.
+ */
+export function parseTraceparent(header) {
+    if (!header)
+        return null;
+    const parts = header.trim().split("-");
+    if (parts.length !== 4)
+        return null;
+    const [version, traceId, spanId, flags] = parts;
+    if (version !== "00")
+        return null;
+    if (traceId.length !== 32 || !HEX.test(traceId) || traceId === ZERO_TRACE)
+        return null;
+    if (spanId.length !== 16 || !HEX.test(spanId) || spanId === ZERO_SPAN)
+        return null;
+    if (flags.length !== 2 || !HEX.test(flags))
+        return null;
+    // bit 0 of the flags byte = sampled
+    return { traceId, spanId, sampled: (Number.parseInt(flags, 16) & 0x01) === 1 };
+}
+/** Format a `traceparent` header value (version `00`). */
+export function formatTraceparent(traceId, spanId, sampled) {
+    return `00-${traceId}-${spanId}-${sampled ? "01" : "00"}`;
+}
+const toHex = (bytes) => {
+    let out = "";
+    for (const b of bytes)
+        out += b.toString(16).padStart(2, "0");
+    return out;
+};
+/** A fresh 16-byte (32-hex) trace id. */
+export function generateTraceId() {
+    return toHex(crypto.getRandomValues(new Uint8Array(16)));
+}
+/** A fresh 8-byte (16-hex) span id. */
+export function generateSpanId() {
+    return toHex(crypto.getRandomValues(new Uint8Array(8)));
+}
+//# sourceMappingURL=traceparent.js.map

package/dist/traceparent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceparent.js","sourceRoot":"","sources":["../src/traceparent.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH,MAAM,GAAG,GAAG,aAAa,CAAA;AACzB,MAAM,UAAU,GAAG,kCAAkC,CAAA;AACrD,MAAM,SAAS,GAAG,kBAAkB,CAAA;AAEpC;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAiC;IAChE,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAA;IACxB,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IACtC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IACnC,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,GAAG,KAAyC,CAAA;IACnF,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,IAAI,CAAA;IACjC,IAAI,OAAO,CAAC,MAAM,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,OAAO,KAAK,UAAU;QAAE,OAAO,IAAI,CAAA;IACtF,IAAI,MAAM,CAAC,MAAM,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,IAAI,CAAA;IAClF,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IACvD,oCAAoC;IACpC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAA;AAChF,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,MAAc,EAAE,OAAgB;IACjF,OAAO,MAAM,OAAO,IAAI,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;AAC3D,CAAC;AAED,MAAM,KAAK,GAAG,CAAC,KAAiB,EAAU,EAAE;IAC1C,IAAI,GAAG,GAAG,EAAE,CAAA;IACZ,KAAK,MAAM,CAAC,IAAI,KAAK;QAAE,GAAG,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;IAC7D,OAAO,GAAG,CAAA;AACZ,CAAC,CAAA;AAED,yCAAyC;AACzC,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,CAAC,MAAM,CAAC,eAAe,CAAC,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;AAC1D,CAAC;AAED,uCAAuC;AACvC,MAAM,UAAU,cAAc;IAC5B,OAAO,KAAK,CAAC,MAAM,CAAC,eAAe,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AACzD,CAAC"}

package/dist/tracing.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The `tracing()` plugin — establishes a span per request, propagates W3C trace context, and exposes
+ * `c.trace` for forwarding the trace to downstream services. OpenTelemetry-compatible by wire format
+ * (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";
+/** 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 interface TracingOptions {
+    /** Where spans are sent. Default: {@link consoleSpanExporter}. */
+    readonly exporter?: SpanExporter;
+    /** Sets the `service.name` attribute on every span. */
+    readonly serviceName?: string;
+    /**
+     * Set the outbound `traceparent` on the RESPONSE too (handy for browser/client correlation).
+     * Default false — most setups only propagate downstream, not back to the caller.
+     */
+    readonly responseHeader?: boolean;
+}
+/** Spread into an outgoing `fetch`/`ctx.api` call's headers to continue the trace downstream:
+ * `fetch(url, { headers: traceHeaders(c.trace) })`. */
+export declare function traceHeaders(trace: TraceContext): {
+    traceparent: string;
+};
+/**
+ * Distributed-tracing plugin. Each request continues the inbound trace (or starts one), opens a
+ * server span, and ends it on response with the status + HTTP attributes. Idempotent.
+ *
+ * ```ts
+ * app.use(tracing({ exporter: myOtelExporter, serviceName: "orders-api" }))
+ * // in a handler: fetch(url, { headers: traceHeaders(c.trace) })  // continue the trace downstream
+ * ```
+ */
+export declare function tracing(options?: TracingOptions): import("@nifrajs/core").NifraPlugin<import("@nifrajs/core").AnyServer, import("@nifrajs/core").Server<any, any>>;
+//# sourceMappingURL=tracing.d.ts.map

package/dist/tracing.d.ts.map

@@ -0,0 +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"}

package/dist/tracing.js

@@ -0,0 +1,92 @@
+/**
+ * The `tracing()` plugin — establishes a span per request, propagates W3C trace context, and exposes
+ * `c.trace` for forwarding the trace to downstream services. OpenTelemetry-compatible by wire format
+ * (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 { definePlugin } from "@nifrajs/core";
+import { consoleSpanExporter, } from "./span.js";
+import { formatTraceparent, generateSpanId, generateTraceId, parseTraceparent, } from "./traceparent.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) {
+    return { traceparent: trace.traceparent };
+}
+const pathOf = (url) => {
+    try {
+        return new URL(url).pathname;
+    }
+    catch {
+        return url;
+    }
+};
+/**
+ * Distributed-tracing plugin. Each request continues the inbound trace (or starts one), opens a
+ * server span, and ends it on response with the status + HTTP attributes. Idempotent.
+ *
+ * ```ts
+ * app.use(tracing({ exporter: myOtelExporter, serviceName: "orders-api" }))
+ * // in a handler: fetch(url, { headers: traceHeaders(c.trace) })  // continue the trace downstream
+ * ```
+ */
+export function tracing(options = {}) {
+    const exporter = options.exporter ?? consoleSpanExporter();
+    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();
+    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,
+            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 = {
+            traceId,
+            spanId,
+            ...(parent !== null ? { parentSpanId: parent.spanId } : {}),
+            sampled,
+            traceparent,
+        };
+        return { trace };
+    })
+        .use({
+        name: "tracing-end",
+        onResponse: (res, req) => {
+            const span = inFlight.get(req);
+            if (span === 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);
+            return res;
+        },
+    }));
+}
+//# sourceMappingURL=tracing.js.map

package/dist/tracing.js.map

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

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@nifrajs/otel",
+  "version": "0.1.0-alpha.1",
+  "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",
+    "typescript",
+    "nifra",
+    "web-framework",
+    "full-stack",
+    "edge",
+    "ssr",
+    "opentelemetry",
+    "tracing",
+    "observability",
+    "w3c-traceparent"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && bun run ../../scripts/fix-dts.ts dist"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@nifrajs/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@nifrajs/core": "workspace:*"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nifrajs/nifra.git",
+    "directory": "packages/otel"
+  },
+  "bugs": {
+    "url": "https://github.com/nifrajs/nifra/issues"
+  },
+  "homepage": "https://github.com/nifrajs/nifra#readme"
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+/**
+ * @nifrajs/otel — 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 with `traceHeaders(c.trace)`. Spans go to a pluggable
+ * `SpanExporter` — bridge to the OpenTelemetry SDK, or log with `consoleSpanExporter`. No SDK
+ * bundled; edge-safe.
+ *
+ *   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.ts"
+export {
+  formatTraceparent,
+  generateSpanId,
+  generateTraceId,
+  type ParsedTraceparent,
+  parseTraceparent,
+} from "./traceparent.ts"
+export { type TraceContext, type TracingOptions, traceHeaders, tracing } from "./tracing.ts"

package/src/span.ts

@@ -0,0 +1,66 @@
+/**
+ * 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}
+ * (a ~10-line adapter to `@opentelemetry/api`, or the bundled {@link consoleSpanExporter}).
+ */
+
+export type SpanStatus = "unset" | "ok" | "error"
+export type AttributeValue = string | number | boolean
+
+/** A completed (or in-flight) server span for one request. */
+export interface NifraSpan {
+  /** 32-hex W3C trace id — shared across every span/service in the trace. */
+  readonly traceId: string
+  /** 16-hex id of this span. */
+  readonly spanId: string
+  /** The inbound span's id, if this request continued an upstream trace. */
+  readonly parentSpanId?: string
+  /** Whether the trace is sampled (the W3C flag). */
+  readonly sampled: boolean
+  /** Span name — `"<METHOD> <path>"`. */
+  readonly name: string
+  /** Wall-clock start (epoch ms). */
+  readonly startTime: number
+  /** Wall-clock end (epoch ms) — set on completion. */
+  endTime?: number
+  /** Duration in ms (monotonic). */
+  durationMs?: number
+  status: SpanStatus
+  /** OTel-semantic-convention attributes. */
+  readonly attributes: Record<string, AttributeValue>
+}
+
+/**
+ * Where ended spans go. Implement this to bridge to the OpenTelemetry SDK (map each field onto a
+ * 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 {
+  onStart?(span: NifraSpan): void
+  onEnd(span: NifraSpan): void
+}
+
+/** 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: (line: string) => void = (l) => {
+    console.log(l)
+  },
+): SpanExporter {
+  return {
+    onEnd(span) {
+      log(
+        JSON.stringify({
+          name: span.name,
+          traceId: span.traceId,
+          spanId: span.spanId,
+          parentSpanId: span.parentSpanId,
+          durationMs: span.durationMs,
+          status: span.status,
+          ...span.attributes,
+        }),
+      )
+    },
+  }
+}

package/src/traceparent.ts

@@ -0,0 +1,58 @@
+/**
+ * W3C Trace Context — `traceparent` parsing/formatting + id generation. This is OpenTelemetry's
+ * wire format for propagating a trace across services, so producing/forwarding it correctly is the
+ * core of distributed tracing regardless of which backend ends up collecting the spans.
+ *
+ *   traceparent: 00-<32-hex trace-id>-<16-hex span-id>-<2-hex flags>
+ *
+ * Pure + dependency-free; the request plugin is a thin layer over this.
+ */
+
+/** A parsed inbound `traceparent`. */
+export interface ParsedTraceparent {
+  readonly traceId: string
+  readonly spanId: string
+  readonly sampled: boolean
+}
+
+const HEX = /^[0-9a-f]+$/
+const ZERO_TRACE = "00000000000000000000000000000000"
+const ZERO_SPAN = "0000000000000000"
+
+/**
+ * Parse a `traceparent` header, or `null` if it's absent/malformed/version-unknown — per the spec,
+ * a bad header means "start a fresh trace", never an error. Only version `00` is accepted.
+ */
+export function parseTraceparent(header: string | null | undefined): ParsedTraceparent | null {
+  if (!header) return null
+  const parts = header.trim().split("-")
+  if (parts.length !== 4) return null
+  const [version, traceId, spanId, flags] = parts as [string, string, string, string]
+  if (version !== "00") return null
+  if (traceId.length !== 32 || !HEX.test(traceId) || traceId === ZERO_TRACE) return null
+  if (spanId.length !== 16 || !HEX.test(spanId) || spanId === ZERO_SPAN) return null
+  if (flags.length !== 2 || !HEX.test(flags)) return null
+  // bit 0 of the flags byte = sampled
+  return { traceId, spanId, sampled: (Number.parseInt(flags, 16) & 0x01) === 1 }
+}
+
+/** Format a `traceparent` header value (version `00`). */
+export function formatTraceparent(traceId: string, spanId: string, sampled: boolean): string {
+  return `00-${traceId}-${spanId}-${sampled ? "01" : "00"}`
+}
+
+const toHex = (bytes: Uint8Array): string => {
+  let out = ""
+  for (const b of bytes) out += b.toString(16).padStart(2, "0")
+  return out
+}
+
+/** A fresh 16-byte (32-hex) trace id. */
+export function generateTraceId(): string {
+  return toHex(crypto.getRandomValues(new Uint8Array(16)))
+}
+
+/** A fresh 8-byte (16-hex) span id. */
+export function generateSpanId(): string {
+  return toHex(crypto.getRandomValues(new Uint8Array(8)))
+}

package/src/tracing.ts

@@ -0,0 +1,126 @@
+/**
+ * The `tracing()` plugin — establishes a span per request, propagates W3C trace context, and exposes
+ * `c.trace` for forwarding the trace to downstream services. OpenTelemetry-compatible by wire format
+ * (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 { definePlugin } from "@nifrajs/core"
+import {
+  type AttributeValue,
+  consoleSpanExporter,
+  type NifraSpan,
+  type SpanExporter,
+} from "./span.ts"
+import {
+  formatTraceparent,
+  generateSpanId,
+  generateTraceId,
+  parseTraceparent,
+} from "./traceparent.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 interface TracingOptions {
+  /** Where spans are sent. Default: {@link consoleSpanExporter}. */
+  readonly exporter?: SpanExporter
+  /** Sets the `service.name` attribute on every span. */
+  readonly serviceName?: string
+  /**
+   * Set the outbound `traceparent` on the RESPONSE too (handy for browser/client correlation).
+   * Default false — most setups only propagate downstream, not back to the caller.
+   */
+  readonly responseHeader?: boolean
+}
+
+/** 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: TraceContext): { traceparent: string } {
+  return { traceparent: trace.traceparent }
+}
+
+const pathOf = (url: string): string => {
+  try {
+    return new URL(url).pathname
+  } catch {
+    return url
+  }
+}
+
+/**
+ * Distributed-tracing plugin. Each request continues the inbound trace (or starts one), opens a
+ * server span, and ends it on response with the status + HTTP attributes. Idempotent.
+ *
+ * ```ts
+ * app.use(tracing({ exporter: myOtelExporter, serviceName: "orders-api" }))
+ * // in a handler: fetch(url, { headers: traceHeaders(c.trace) })  // continue the trace downstream
+ * ```
+ */
+export function tracing(options: TracingOptions = {}) {
+  const exporter = options.exporter ?? consoleSpanExporter()
+  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>()
+
+  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,
+          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 }
+      })
+      .use({
+        name: "tracing-end",
+        onResponse: (res, req) => {
+          const span = inFlight.get(req)
+          if (span === 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)
+          return res
+        },
+      }),
+  )
+}