@nifrajs/otel 2.2.0 → 2.4.0

package/README.md

@@ -20,17 +20,17 @@ const app = server()
 
 ## What it does per request
 
-- **Continues an inbound trace** — parses the `traceparent` header; reuses its `trace-id` and records
+- **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
+- **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.causality`** - a bounded, payload-free request node that survives durable command,
   event, workflow, projection, and repair seams. `traceHeaders(c.trace, c.causality)` forwards both
   conventions to a trusted downstream service.
-- **Exposes `c.observation`** — integrations can start correctly-parented child observations or
+- **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).
 
@@ -70,10 +70,10 @@ interface ObservationAdapter {
 }
 ```
 
-- `consoleSpanExporter()` — logs each completed span as one structured line (dev / starting point).
-- `tracing({ adapters: [devtoolsAdapter, privateAdapter] })` — fan out the same lifecycle; adapter
+- `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
+- **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.
 
@@ -88,7 +88,7 @@ it over hand-rolling traceparent parsing, clocks, error status, or completion gu
 
 ## For AI agents
 
-Start with [`LLM.md`](./LLM.md) — this package's contract card (the exports you call + its footguns),
+Start with [`LLM.md`](./LLM.md) - this package's contract card (the exports you call + its footguns),
 one cheap read instead of the whole corpus. For the wider framework: the repo's
 [`AGENTS.md`](../../AGENTS.md) is the copy-paste quick reference, and
 [`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 /**
- * @nifrajs/otel — distributed tracing for nifra. The `tracing()` plugin continues (or starts) a W3C
+ * @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
- * `ObservationAdapter` — bridge to the OpenTelemetry SDK, or log with `consoleSpanExporter`. No SDK
+ * `ObservationAdapter` - bridge to the OpenTelemetry SDK, or log with `consoleSpanExporter`. No SDK
  * bundled; edge-safe.
  *
  *   import { tracing, traceHeaders, consoleSpanExporter } from "@nifrajs/otel"

package/dist/index.js

@@ -1,8 +1,8 @@
 /**
- * @nifrajs/otel — distributed tracing for nifra. The `tracing()` plugin continues (or starts) a W3C
+ * @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
- * `ObservationAdapter` — bridge to the OpenTelemetry SDK, or log with `consoleSpanExporter`. No SDK
+ * `ObservationAdapter` - bridge to the OpenTelemetry SDK, or log with `consoleSpanExporter`. No SDK
  * bundled; edge-safe.
  *
  *   import { tracing, traceHeaders, consoleSpanExporter } from "@nifrajs/otel"

package/dist/lifecycle.d.ts

@@ -41,7 +41,7 @@ export interface ActiveObservation {
     /** Starts a child that inherits this span's trace identity and sampling decision. */
     startChild(input: Omit<StartObservation, "parent" | "traceparent">, additionalAdapters?: readonly ObservationAdapter[]): ActiveObservation;
     /**
-     * Merge attributes onto the in-flight span — the seam for plugins that learn something mid-request
+     * Merge attributes onto the in-flight span - the seam for plugins that learn something mid-request
      * (an authenticated principal, a feature-flag bucket, a cache verdict) after the span opened.
      * Silently ignored once the observation has ended (the exported span is immutable).
      */

package/dist/span.d.ts

@@ -1,7 +1,7 @@
 /**
  * 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 an
+ * 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}).
  */
@@ -15,7 +15,7 @@ export interface ObservationLink {
 }
 /** 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. */
+    /** 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;
@@ -23,11 +23,11 @@ export interface NifraSpan {
     readonly parentSpanId?: string;
     /** Whether the trace is sampled (the W3C flag). */
     readonly sampled: boolean;
-    /** Span name — `"<METHOD> <path>"`. */
+    /** Span name - `"<METHOD> <path>"`. */
     readonly name: string;
     /** Wall-clock start (epoch ms). */
     readonly startTime: number;
-    /** Wall-clock end (epoch ms) — set on completion. */
+    /** Wall-clock end (epoch ms) - set on completion. */
     endTime?: number;
     /** Duration in ms (monotonic). */
     durationMs?: number;

package/dist/span.js

@@ -1,7 +1,7 @@
 /**
  * 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 an
+ * 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}).
  */

package/dist/traceparent.d.ts

@@ -1,5 +1,5 @@
 /**
- * W3C Trace Context — `traceparent` parsing/formatting + id generation. This is OpenTelemetry's
+ * 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.
  *
@@ -14,7 +14,7 @@ export interface ParsedTraceparent {
     readonly sampled: boolean;
 }
 /**
- * Parse a `traceparent` header, or `null` if it's absent/malformed/version-unknown — per the spec,
+ * 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;

package/dist/traceparent.js

@@ -1,5 +1,5 @@
 /**
- * W3C Trace Context — `traceparent` parsing/formatting + id generation. This is OpenTelemetry's
+ * 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.
  *
@@ -11,7 +11,7 @@ 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,
+ * 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) {

package/dist/tracing.d.ts

@@ -1,5 +1,5 @@
 /**
- * The `tracing()` plugin — establishes a span per request, propagates W3C trace context, and exposes
+ * 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 ObservationAdapter} (bridge to the OTel SDK, or log via `consoleSpanExporter`).
@@ -18,7 +18,7 @@ export interface TracingOptions {
     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.
+     * Default false - most setups only propagate downstream, not back to the caller.
      */
     readonly responseHeader?: boolean;
     /**

package/dist/tracing.js

@@ -1,5 +1,5 @@
 /**
- * The `tracing()` plugin — establishes a span per request, propagates W3C trace context, and exposes
+ * 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 ObservationAdapter} (bridge to the OTel SDK, or log via `consoleSpanExporter`).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nifrajs/otel",
-  "version": "2.2.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.",
+  "version": "2.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",
     "typescript",
@@ -49,7 +49,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@nifrajs/core": "^2.2.0"
+    "@nifrajs/core": "^2.4.0"
   },
   "devDependencies": {
     "@nifrajs/core": "workspace:*"

package/src/index.ts

@@ -1,8 +1,8 @@
 /**
- * @nifrajs/otel — distributed tracing for nifra. The `tracing()` plugin continues (or starts) a W3C
+ * @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
- * `ObservationAdapter` — bridge to the OpenTelemetry SDK, or log with `consoleSpanExporter`. No SDK
+ * `ObservationAdapter` - bridge to the OpenTelemetry SDK, or log with `consoleSpanExporter`. No SDK
  * bundled; edge-safe.
  *
  *   import { tracing, traceHeaders, consoleSpanExporter } from "@nifrajs/otel"

package/src/lifecycle.ts

@@ -62,7 +62,7 @@ export interface ActiveObservation {
     additionalAdapters?: readonly ObservationAdapter[],
   ): ActiveObservation
   /**
-   * Merge attributes onto the in-flight span — the seam for plugins that learn something mid-request
+   * Merge attributes onto the in-flight span - the seam for plugins that learn something mid-request
    * (an authenticated principal, a feature-flag bucket, a cache verdict) after the span opened.
    * Silently ignored once the observation has ended (the exported span is immutable).
    */

package/src/span.ts

@@ -1,7 +1,7 @@
 /**
  * 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 an
+ * 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}).
  */
@@ -18,7 +18,7 @@ export interface ObservationLink {
 
 /** 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. */
+  /** 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
@@ -26,11 +26,11 @@ export interface NifraSpan {
   readonly parentSpanId?: string
   /** Whether the trace is sampled (the W3C flag). */
   readonly sampled: boolean
-  /** Span name — `"<METHOD> <path>"`. */
+  /** Span name - `"<METHOD> <path>"`. */
   readonly name: string
   /** Wall-clock start (epoch ms). */
   readonly startTime: number
-  /** Wall-clock end (epoch ms) — set on completion. */
+  /** Wall-clock end (epoch ms) - set on completion. */
   endTime?: number
   /** Duration in ms (monotonic). */
   durationMs?: number

package/src/traceparent.ts

@@ -1,5 +1,5 @@
 /**
- * W3C Trace Context — `traceparent` parsing/formatting + id generation. This is OpenTelemetry's
+ * 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.
  *
@@ -20,7 +20,7 @@ const ZERO_TRACE = "00000000000000000000000000000000"
 const ZERO_SPAN = "0000000000000000"
 
 /**
- * Parse a `traceparent` header, or `null` if it's absent/malformed/version-unknown — per the spec,
+ * 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 {

package/src/tracing.ts

@@ -1,5 +1,5 @@
 /**
- * The `tracing()` plugin — establishes a span per request, propagates W3C trace context, and exposes
+ * 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 ObservationAdapter} (bridge to the OTel SDK, or log via `consoleSpanExporter`).
@@ -33,7 +33,7 @@ export interface TracingOptions {
   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.
+   * Default false - most setups only propagate downstream, not back to the caller.
    */
   readonly responseHeader?: boolean
   /**