@nifrajs/otel 2.0.0 → 2.1.0

package/dist/effects.d.ts

@@ -0,0 +1,24 @@
+/** Token-only OpenTelemetry spans for capability admission, execution, compensation, and reconciliation. */
+import type { EffectLifecycleObserver } from "@nifrajs/core/effect-lifecycle";
+import type { IdentityPlugin } from "@nifrajs/core/server";
+import type { ObservationAdapter } from "./span.js";
+export interface EffectTracingOptions {
+    readonly exporter?: ObservationAdapter;
+    readonly adapters?: readonly ObservationAdapter[];
+    /** Maximum unmatched started events retained at once. Default 10,000. */
+    readonly maxActive?: number;
+    /** Opportunistically expire unmatched events older than this many milliseconds. Default 5 min. */
+    readonly maxActiveAgeMs?: number;
+    /** Injectable wall clock for deterministic retention tests. */
+    readonly now?: () => number;
+}
+export interface EffectTracingPlugin extends IdentityPlugin {
+    /** Pass the same observer to `createSagaEngine({ observer })` and reconciliation helpers. */
+    readonly observer: EffectLifecycleObserver;
+}
+/**
+ * Installs child effect spans on subsequent routes. The observer consumes only the constrained
+ * `EffectLifecycleEvent` contract; request/business payloads and error text cannot enter an export.
+ */
+export declare function effectTracing(options?: EffectTracingOptions): EffectTracingPlugin;
+//# sourceMappingURL=effects.d.ts.map

package/dist/effects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effects.d.ts","sourceRoot":"","sources":["../src/effects.ts"],"names":[],"mappings":"AAAA,4GAA4G;AAE5G,OAAO,KAAK,EAAwB,uBAAuB,EAAE,MAAM,gCAAgC,CAAA;AACnG,OAAO,KAAK,EAAa,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAErE,OAAO,KAAK,EAAkB,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAEnE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAA;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAA;IACjD,yEAAyE;IACzE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,kGAAkG;IAClG,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,+DAA+D;IAC/D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAC5B;AAED,MAAM,WAAW,mBAAoB,SAAQ,cAAc;IACzD,6FAA6F;IAC7F,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,CAAA;CAC3C;AAoBD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,mBAAmB,CAoGrF"}

package/dist/effects.js

@@ -0,0 +1,129 @@
+/** Token-only OpenTelemetry spans for capability admission, execution, compensation, and reconciliation. */
+import { createObservationLifecycle } from "./lifecycle.js";
+function attributesOf(event) {
+    const attributes = {
+        "nifra.effect.id": event.effectId,
+        "nifra.effect.capability": event.capability,
+        "nifra.effect.stage": event.stage,
+        "nifra.effect.phase": event.phase,
+    };
+    if (event.target !== undefined)
+        attributes["nifra.effect.target"] = event.target;
+    if (event.digest !== undefined)
+        attributes["nifra.effect.digest"] = event.digest;
+    if (event.attempt !== undefined)
+        attributes["nifra.effect.attempt"] = event.attempt;
+    if (event.errorCode !== undefined)
+        attributes["nifra.effect.error_code"] = event.errorCode;
+    if (event.durationMs !== undefined)
+        attributes["nifra.effect.duration_ms"] = event.durationMs;
+    for (const [axis, value] of Object.entries(event.cost ?? {})) {
+        attributes[`nifra.effect.cost.${axis}`] = value;
+    }
+    return attributes;
+}
+/**
+ * Installs child effect spans on subsequent routes. The observer consumes only the constrained
+ * `EffectLifecycleEvent` contract; request/business payloads and error text cannot enter an export.
+ */
+export function effectTracing(options = {}) {
+    const adapters = [
+        ...(options.exporter === undefined ? [] : [options.exporter]),
+        ...(options.adapters ?? []),
+    ];
+    const maxActive = options.maxActive ?? 10_000;
+    const maxActiveAgeMs = options.maxActiveAgeMs ?? 5 * 60_000;
+    if (!Number.isSafeInteger(maxActive) || maxActive < 1) {
+        throw new RangeError("effect tracing maxActive must be a positive safe integer");
+    }
+    if (!Number.isSafeInteger(maxActiveAgeMs) || maxActiveAgeMs < 1) {
+        throw new RangeError("effect tracing maxActiveAgeMs must be a positive safe integer");
+    }
+    const now = options.now ?? Date.now;
+    const lifecycle = createObservationLifecycle({ adapters });
+    const active = new Map();
+    let nextSweepAt = Number.POSITIVE_INFINITY;
+    const keyOf = (event) => `${event.effectId}\n${event.stage}`;
+    const evict = (key, errorCode) => {
+        const entry = active.get(key);
+        if (entry === undefined)
+            return;
+        active.delete(key);
+        entry.observation.setAttributes({
+            "nifra.effect.phase": "ambiguous",
+            "nifra.effect.error_code": errorCode,
+        });
+        entry.observation.end({ status: "error" });
+    };
+    const sweep = () => {
+        const at = now();
+        if (!Number.isFinite(at) || at < nextSweepAt)
+            return at;
+        // `active` iterates in insertion order and entries carry a monotonic `at`, so the front is the
+        // oldest / earliest-expiring. Evict the expired prefix and stop at the first live entry: its expiry
+        // is the earliest remaining, i.e. the next sweep deadline. A sweep is therefore O(evicted), not
+        // O(active.size). (A backwards clock only defers an eviction to the size cap - the hard bound; age
+        // eviction is opportunistic.)
+        nextSweepAt = Number.POSITIVE_INFINITY;
+        for (const [key, entry] of active) {
+            const expiresAt = entry.at + maxActiveAgeMs;
+            if (at >= expiresAt) {
+                evict(key, "observation_expired");
+            }
+            else {
+                nextSweepAt = expiresAt;
+                break;
+            }
+        }
+        return at;
+    };
+    const observer = (event) => {
+        const at = sweep();
+        const key = keyOf(event);
+        if (event.phase === "started") {
+            if (active.has(key))
+                return;
+            while (active.size >= maxActive) {
+                const oldest = active.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                evict(oldest, "observation_evicted");
+            }
+            const startedAt = Number.isFinite(at) ? at : event.at;
+            active.set(key, Object.freeze({
+                observation: lifecycle.start({
+                    name: `nifra.effect.${event.stage}`,
+                    parent: event.trace ?? null,
+                    attributes: attributesOf(event),
+                }),
+                at: startedAt,
+            }));
+            nextSweepAt = Math.min(nextSweepAt, startedAt + maxActiveAgeMs);
+            return;
+        }
+        const entry = active.get(key);
+        let observation;
+        if (entry === undefined) {
+            observation = lifecycle.start({
+                name: `nifra.effect.${event.stage}`,
+                parent: event.trace ?? null,
+                attributes: attributesOf(event),
+            });
+        }
+        else {
+            active.delete(key);
+            observation = entry.observation;
+            observation.setAttributes(attributesOf(event));
+        }
+        observation.end({ status: event.phase === "succeeded" ? "ok" : "error" });
+    };
+    const apply = (app) => {
+        app.observeCapability(observer);
+        return app;
+    };
+    return Object.assign(apply, {
+        pluginName: "nifra:effect-tracing",
+        observer,
+    });
+}
+//# sourceMappingURL=effects.js.map

package/dist/effects.js.map

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

package/dist/index.d.ts

@@ -9,6 +9,7 @@
  *   app.use(tracing({ exporter: consoleSpanExporter(), serviceName: "orders-api" }))
  */
 export { causalitySpanLink } from "./causality.js";
+export { type EffectTracingOptions, type EffectTracingPlugin, effectTracing, } from "./effects.js";
 export { type ActiveObservation, createObservationLifecycle, type EndObservation, type ObservationClock, type ObservationContext, type ObservationLifecycle, type ObservationLifecycleOptions, type ObservationParent, type StartObservation, } from "./lifecycle.js";
 export { type OtlpExporter, type OtlpExporterOptions, otlpExporter } from "./otlp.js";
 export { type AttributeValue, combineObservationAdapters, consoleSpanExporter, type NifraSpan, type ObservationAdapter, type ObservationLink, type SpanStatus, } from "./span.js";

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,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAClD,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,EAAE,KAAK,YAAY,EAAE,KAAK,mBAAmB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AACrF,OAAO,EACL,KAAK,cAAc,EACnB,0BAA0B,EAC1B,mBAAmB,EACnB,KAAK,SAAS,EACd,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,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,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAClD,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,aAAa,GACd,MAAM,cAAc,CAAA;AACrB,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,EAAE,KAAK,YAAY,EAAE,KAAK,mBAAmB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AACrF,OAAO,EACL,KAAK,cAAc,EACnB,0BAA0B,EAC1B,mBAAmB,EACnB,KAAK,SAAS,EACd,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,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

@@ -9,6 +9,7 @@
  *   app.use(tracing({ exporter: consoleSpanExporter(), serviceName: "orders-api" }))
  */
 export { causalitySpanLink } from "./causality.js";
+export { effectTracing, } from "./effects.js";
 export { createObservationLifecycle, } from "./lifecycle.js";
 export { otlpExporter } from "./otlp.js";
 export { combineObservationAdapters, consoleSpanExporter, } from "./span.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAClD,OAAO,EAEL,0BAA0B,GAQ3B,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAA+C,YAAY,EAAE,MAAM,WAAW,CAAA;AACrF,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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAClD,OAAO,EAGL,aAAa,GACd,MAAM,cAAc,CAAA;AACrB,OAAO,EAEL,0BAA0B,GAQ3B,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAA+C,YAAY,EAAE,MAAM,WAAW,CAAA;AACrF,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/otel",
-  "version": "2.0.0",
+  "version": "2.1.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",
@@ -29,6 +29,11 @@
       "bun": "./src/metrics.ts",
       "types": "./dist/metrics.d.ts",
       "default": "./dist/metrics.js"
+    },
+    "./effects": {
+      "bun": "./src/effects.ts",
+      "types": "./dist/effects.d.ts",
+      "default": "./dist/effects.js"
     }
   },
   "files": [
@@ -44,7 +49,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@nifrajs/core": "^2.0.0"
+    "@nifrajs/core": "^2.1.0"
   },
   "devDependencies": {
     "@nifrajs/core": "workspace:*"

package/src/effects.ts

@@ -0,0 +1,146 @@
+/** Token-only OpenTelemetry spans for capability admission, execution, compensation, and reconciliation. */
+
+import type { EffectLifecycleEvent, EffectLifecycleObserver } from "@nifrajs/core/effect-lifecycle"
+import type { AnyServer, IdentityPlugin } from "@nifrajs/core/server"
+import { type ActiveObservation, createObservationLifecycle } from "./lifecycle.ts"
+import type { AttributeValue, ObservationAdapter } from "./span.ts"
+
+export interface EffectTracingOptions {
+  readonly exporter?: ObservationAdapter
+  readonly adapters?: readonly ObservationAdapter[]
+  /** Maximum unmatched started events retained at once. Default 10,000. */
+  readonly maxActive?: number
+  /** Opportunistically expire unmatched events older than this many milliseconds. Default 5 min. */
+  readonly maxActiveAgeMs?: number
+  /** Injectable wall clock for deterministic retention tests. */
+  readonly now?: () => number
+}
+
+export interface EffectTracingPlugin extends IdentityPlugin {
+  /** Pass the same observer to `createSagaEngine({ observer })` and reconciliation helpers. */
+  readonly observer: EffectLifecycleObserver
+}
+
+function attributesOf(event: EffectLifecycleEvent): Record<string, AttributeValue> {
+  const attributes: Record<string, AttributeValue> = {
+    "nifra.effect.id": event.effectId,
+    "nifra.effect.capability": event.capability,
+    "nifra.effect.stage": event.stage,
+    "nifra.effect.phase": event.phase,
+  }
+  if (event.target !== undefined) attributes["nifra.effect.target"] = event.target
+  if (event.digest !== undefined) attributes["nifra.effect.digest"] = event.digest
+  if (event.attempt !== undefined) attributes["nifra.effect.attempt"] = event.attempt
+  if (event.errorCode !== undefined) attributes["nifra.effect.error_code"] = event.errorCode
+  if (event.durationMs !== undefined) attributes["nifra.effect.duration_ms"] = event.durationMs
+  for (const [axis, value] of Object.entries(event.cost ?? {})) {
+    attributes[`nifra.effect.cost.${axis}`] = value
+  }
+  return attributes
+}
+
+/**
+ * Installs child effect spans on subsequent routes. The observer consumes only the constrained
+ * `EffectLifecycleEvent` contract; request/business payloads and error text cannot enter an export.
+ */
+export function effectTracing(options: EffectTracingOptions = {}): EffectTracingPlugin {
+  const adapters = [
+    ...(options.exporter === undefined ? [] : [options.exporter]),
+    ...(options.adapters ?? []),
+  ]
+  const maxActive = options.maxActive ?? 10_000
+  const maxActiveAgeMs = options.maxActiveAgeMs ?? 5 * 60_000
+  if (!Number.isSafeInteger(maxActive) || maxActive < 1) {
+    throw new RangeError("effect tracing maxActive must be a positive safe integer")
+  }
+  if (!Number.isSafeInteger(maxActiveAgeMs) || maxActiveAgeMs < 1) {
+    throw new RangeError("effect tracing maxActiveAgeMs must be a positive safe integer")
+  }
+  const now = options.now ?? Date.now
+  const lifecycle = createObservationLifecycle({ adapters })
+  const active = new Map<string, { readonly observation: ActiveObservation; readonly at: number }>()
+  let nextSweepAt = Number.POSITIVE_INFINITY
+  const keyOf = (event: EffectLifecycleEvent): string => `${event.effectId}\n${event.stage}`
+
+  const evict = (key: string, errorCode: "observation_evicted" | "observation_expired"): void => {
+    const entry = active.get(key)
+    if (entry === undefined) return
+    active.delete(key)
+    entry.observation.setAttributes({
+      "nifra.effect.phase": "ambiguous",
+      "nifra.effect.error_code": errorCode,
+    })
+    entry.observation.end({ status: "error" })
+  }
+
+  const sweep = (): number => {
+    const at = now()
+    if (!Number.isFinite(at) || at < nextSweepAt) return at
+    // `active` iterates in insertion order and entries carry a monotonic `at`, so the front is the
+    // oldest / earliest-expiring. Evict the expired prefix and stop at the first live entry: its expiry
+    // is the earliest remaining, i.e. the next sweep deadline. A sweep is therefore O(evicted), not
+    // O(active.size). (A backwards clock only defers an eviction to the size cap - the hard bound; age
+    // eviction is opportunistic.)
+    nextSweepAt = Number.POSITIVE_INFINITY
+    for (const [key, entry] of active) {
+      const expiresAt = entry.at + maxActiveAgeMs
+      if (at >= expiresAt) {
+        evict(key, "observation_expired")
+      } else {
+        nextSweepAt = expiresAt
+        break
+      }
+    }
+    return at
+  }
+
+  const observer: EffectLifecycleObserver = (event) => {
+    const at = sweep()
+    const key = keyOf(event)
+    if (event.phase === "started") {
+      if (active.has(key)) return
+      while (active.size >= maxActive) {
+        const oldest = active.keys().next().value as string | undefined
+        if (oldest === undefined) break
+        evict(oldest, "observation_evicted")
+      }
+      const startedAt = Number.isFinite(at) ? at : event.at
+      active.set(
+        key,
+        Object.freeze({
+          observation: lifecycle.start({
+            name: `nifra.effect.${event.stage}`,
+            parent: event.trace ?? null,
+            attributes: attributesOf(event),
+          }),
+          at: startedAt,
+        }),
+      )
+      nextSweepAt = Math.min(nextSweepAt, startedAt + maxActiveAgeMs)
+      return
+    }
+    const entry = active.get(key)
+    let observation: ActiveObservation
+    if (entry === undefined) {
+      observation = lifecycle.start({
+        name: `nifra.effect.${event.stage}`,
+        parent: event.trace ?? null,
+        attributes: attributesOf(event),
+      })
+    } else {
+      active.delete(key)
+      observation = entry.observation
+      observation.setAttributes(attributesOf(event))
+    }
+    observation.end({ status: event.phase === "succeeded" ? "ok" : "error" })
+  }
+
+  const apply = <S extends AnyServer>(app: S): S => {
+    app.observeCapability(observer)
+    return app
+  }
+  return Object.assign(apply, {
+    pluginName: "nifra:effect-tracing",
+    observer,
+  }) as EffectTracingPlugin
+}

package/src/index.ts

@@ -10,6 +10,11 @@
  */
 
 export { causalitySpanLink } from "./causality.ts"
+export {
+  type EffectTracingOptions,
+  type EffectTracingPlugin,
+  effectTracing,
+} from "./effects.ts"
 export {
   type ActiveObservation,
   createObservationLifecycle,