@nifrajs/otel 3.5.0 → 4.0.2

package/src/events.ts

@@ -0,0 +1,170 @@
+/**
+ * Consumer spans for `@nifrajs/events` envelopes. nifra does not deliver events, so it cannot trace them
+ * on its own: wrap the consumer once and every envelope it receives gets a `process <type>` span, linked
+ * to the producer through the envelope's durable causality.
+ *
+ *   import { traceEventConsumer } from "@nifrajs/otel/events"
+ *   const consume = traceEventConsumer(orderPaid, async (event, ctx) => fulfil(event.payload), { exporter })
+ *   await consume(message.body)            // from a queue, an SSE frame, a webhook body
+ */
+
+import type { CausalityContext } from "@nifrajs/core/causality"
+import { causalitySpanLink } from "./causality.ts"
+import {
+  createObservationLifecycle,
+  type ObservationContext,
+  type ObservationScope,
+  type StartObservation,
+} from "./lifecycle.ts"
+import type { AttributeValue, ObservationAdapter } from "./span.ts"
+import { parseTraceparent } from "./traceparent.ts"
+
+/** The envelope fields a consumer span reads. `EventEnvelope` from `@nifrajs/events` has them. */
+export interface TracedEventEnvelope {
+  readonly id: string
+  readonly type: string
+  readonly version: number
+  readonly causality?: CausalityContext
+}
+
+/**
+ * An event contract or a registry from `@nifrajs/events`, declared structurally: anything whose
+ * `parse(input)` never throws and reports success with an envelope, or failure with `issues` (a contract)
+ * or a `reason` (a registry).
+ */
+export interface TracedEventSource<Envelope extends TracedEventEnvelope> {
+  /** A contract's own type, used to name the span of an envelope that failed to parse. */
+  readonly type?: string
+  parse(input: unknown):
+    | { readonly success: true; readonly envelope: Envelope }
+    | {
+        readonly success: false
+        readonly issues?: readonly unknown[]
+        readonly reason?: string
+      }
+}
+
+/** What the wrapped handler receives next to the envelope: the consumer span's trace context. */
+export interface EventConsumerContext {
+  readonly trace: ObservationContext
+}
+
+export type TracedEventResult<Value> =
+  | { readonly success: true; readonly value: Value }
+  | { readonly success: false; readonly issueCount: number }
+
+/** The traced consumer. `parent` is an ambient trace (`c.trace` in a webhook route), if there is one. */
+export type TracedEventConsumer<Value> = (
+  input: unknown,
+  parent?: ObservationContext,
+) => Promise<TracedEventResult<Value>>
+
+export interface EventTracingOptions {
+  readonly exporter?: ObservationAdapter
+  readonly adapters?: readonly ObservationAdapter[]
+  /** `messaging.system`: the transport the envelopes arrive on. Default `"nifra.events"`. */
+  readonly system?: string
+  /** Runs the handler with the consumer span active in an ambient context (see `ObservationScope`). */
+  readonly scope?: ObservationScope
+}
+
+const REGISTRY_REASONS: ReadonlySet<string> = new Set([
+  "not-an-object",
+  "unknown-contract",
+  "invalid-payload",
+])
+const TYPE_NAME = /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/
+
+/**
+ * Wrap an event consumer so each envelope is one `process <type>` span (kind consumer), linked to the
+ * producer's span through `causalitySpanLink(envelope.causality)`. With a `parent`, the span is that
+ * span's child; otherwise it starts its own trace. Attributes: `nifra.event.type`, `nifra.event.version`,
+ * `messaging.message.id` (the envelope id), and the messaging operation.
+ *
+ * Input that fails to parse never reaches the handler: it becomes an error span carrying only an issue
+ * count (and a registry's bounded reason), resolves `{ success: false }`, and exports no payload. A
+ * throwing handler ends its span as an error and rejects.
+ */
+export function traceEventConsumer<Envelope extends TracedEventEnvelope, Result>(
+  source: TracedEventSource<Envelope>,
+  handler: (envelope: Envelope, context: EventConsumerContext) => Result,
+  options: EventTracingOptions = {},
+): TracedEventConsumer<Awaited<Result>> {
+  const adapters = [
+    ...(options.exporter === undefined ? [] : [options.exporter]),
+    ...(options.adapters ?? []),
+  ]
+  const lifecycle = createObservationLifecycle({ adapters })
+  const system = options.system ?? "nifra.events"
+  const scope = options.scope
+  const sourceType =
+    typeof source.type === "string" && TYPE_NAME.test(source.type) ? source.type : undefined
+  const operation = {
+    "messaging.system": system,
+    "messaging.operation.type": "process",
+    "messaging.operation.name": "process",
+  }
+
+  return async (input, parent) => {
+    const ambient = parent === undefined ? null : parseTraceparent(parent.traceparent)
+    const name = sourceType === undefined ? "process" : `process ${sourceType}`
+    let parsed: ReturnType<TracedEventSource<Envelope>["parse"]>
+    try {
+      parsed = source.parse(input)
+    } catch (error) {
+      // A contract with an async payload schema throws here; that is a bug, not bad input.
+      lifecycle
+        .start({ name, kind: "consumer", parent: ambient, attributes: operation })
+        .end({ status: "error", attributes: { "error.type": "_OTHER" } })
+      throw error
+    }
+    if (!parsed.success) {
+      const attributes: Record<string, AttributeValue> = {
+        ...operation,
+        "nifra.event.issue_count": parsed.issues?.length ?? 1,
+        "error.type": "invalid_event",
+      }
+      if (parsed.reason !== undefined && REGISTRY_REASONS.has(parsed.reason))
+        attributes["nifra.event.parse_failure"] = parsed.reason
+      lifecycle
+        .start({
+          name,
+          kind: "consumer",
+          parent: ambient,
+          attributes,
+        })
+        .end({ status: "error" })
+      return { success: false, issueCount: parsed.issues?.length ?? 1 }
+    }
+
+    const envelope = parsed.envelope
+    const start: { -readonly [K in keyof StartObservation]: StartObservation[K] } = {
+      name: `process ${envelope.type}`,
+      kind: "consumer",
+      parent: ambient,
+      attributes: {
+        ...operation,
+        "messaging.message.id": envelope.id,
+        "nifra.event.type": envelope.type,
+        "nifra.event.version": envelope.version,
+      },
+    }
+    const link =
+      envelope.causality === undefined ? undefined : causalitySpanLink(envelope.causality)
+    if (link !== undefined) start.links = [link]
+    const span = lifecycle.start(start)
+    const context: EventConsumerContext = { trace: span.context }
+    try {
+      const value =
+        scope === undefined
+          ? await handler(envelope, context)
+          : await scope(span.context, () => handler(envelope, context))
+      span.end({ status: "ok" })
+      return { success: true, value }
+    } catch (error) {
+      span.recordError(error)
+      span.end({ status: "error", attributes: { "error.type": "_OTHER" } })
+      throw error
+    }
+  }
+}

package/src/index.ts

@@ -24,6 +24,7 @@ export {
   type ObservationLifecycle,
   type ObservationLifecycleOptions,
   type ObservationParent,
+  type ObservationScope,
   type StartObservation,
 } from "./lifecycle.ts"
 export { type OtlpExporter, type OtlpExporterOptions, otlpExporter } from "./otlp.ts"
@@ -34,6 +35,7 @@ export {
   type NifraSpan,
   type ObservationAdapter,
   type ObservationLink,
+  type SpanKind,
   type SpanStatus,
 } from "./span.ts"
 export {

package/src/jobs.ts

@@ -0,0 +1,141 @@
+/**
+ * Spans for `@nifrajs/jobs`, following the OpenTelemetry messaging conventions. `jobTracing()` is the
+ * queue's `instrument`: each enqueue is a `send <job>` producer span and each attempt a `process <job>`
+ * consumer span. The send span's context is stored with the job, and the process span is its CHILD
+ * (plus a link to it), so one trace runs from the request that enqueued the job through every attempt.
+ *
+ *   import { jobTracing } from "@nifrajs/otel/jobs"
+ *   const queue = createQueue({ store, instrument: jobTracing({ exporter }) })
+ *   await sendEmail.for(c).enqueue({ to })   // "send send-email", child of the request span
+ */
+
+import {
+  createObservationLifecycle,
+  type ObservationContext,
+  type ObservationScope,
+  type StartObservation,
+} from "./lifecycle.ts"
+import type { AttributeValue, ObservationAdapter } from "./span.ts"
+import { parseTraceparent } from "./traceparent.ts"
+
+/** `JobEnqueueInfo` from `@nifrajs/jobs`, declared structurally so this package does not depend on it. */
+export interface JobTracingEnqueueInfo {
+  readonly name: string
+  readonly traceparent: string | undefined
+}
+
+/** `JobRunInfo` from `@nifrajs/jobs`, declared structurally. */
+export interface JobTracingRunInfo {
+  readonly id: string
+  readonly name: string
+  readonly attempt: number
+  readonly maxAttempts: number
+  readonly traceparent: string | undefined
+}
+
+/** Structurally a `QueueInstrument` from `@nifrajs/jobs`: pass it as `createQueue({ instrument })`. */
+export interface JobTracingInstrument {
+  enqueue(
+    info: JobTracingEnqueueInfo,
+    next: (scope?: { readonly traceparent?: string }) => Promise<string>,
+  ): Promise<string>
+  run(
+    info: JobTracingRunInfo,
+    next: (scope?: { readonly trace?: ObservationContext }) => Promise<string>,
+  ): Promise<string>
+}
+
+export interface JobTracingOptions {
+  readonly exporter?: ObservationAdapter
+  readonly adapters?: readonly ObservationAdapter[]
+  /**
+   * Runs each attempt with its process span active in an ambient context. Pass `otelBridge().scope`
+   * from `@nifrajs/otel/sdk-bridge` so OpenTelemetry instrumentations (pg, undici) inside the handler
+   * nest under the process span.
+   */
+  readonly scope?: ObservationScope
+}
+
+const SYSTEM = "nifra.jobs"
+
+/**
+ * The queue instrument. Span names are `send <job name>` (kind producer) and `process <job name>` (kind
+ * consumer), with `messaging.system = "nifra.jobs"`, `messaging.operation.type`/`.name`,
+ * `messaging.destination.name` (the job name) and `messaging.message.id`. A process span also carries
+ * `nifra.job.attempt` and `nifra.job.outcome`; an attempt that failed is an error span, and one that
+ * dead-lettered the job adds `nifra.job.dead_lettered = true`. Error text is never exported.
+ *
+ * The stored traceparent is untrusted: a malformed one starts the process span as a new trace. The
+ * sampled flag travels with it.
+ */
+export function jobTracing(options: JobTracingOptions = {}): JobTracingInstrument {
+  const adapters = [
+    ...(options.exporter === undefined ? [] : [options.exporter]),
+    ...(options.adapters ?? []),
+  ]
+  const lifecycle = createObservationLifecycle({ adapters })
+  const scope = options.scope
+
+  return {
+    async enqueue(info, next) {
+      const span = lifecycle.start({
+        name: `send ${info.name}`,
+        kind: "producer",
+        parent: parseTraceparent(info.traceparent),
+        attributes: {
+          "messaging.system": SYSTEM,
+          "messaging.operation.type": "send",
+          "messaging.operation.name": "send",
+          "messaging.destination.name": info.name,
+        },
+      })
+      try {
+        const id = await next({ traceparent: span.context.traceparent })
+        span.end({ status: "ok", attributes: { "messaging.message.id": id } })
+        return id
+      } catch (error) {
+        span.recordError(error)
+        span.end({ status: "error", attributes: { "error.type": "_OTHER" } })
+        throw error
+      }
+    },
+    async run(info, next) {
+      const creation = parseTraceparent(info.traceparent)
+      const start: { -readonly [K in keyof StartObservation]: StartObservation[K] } = {
+        name: `process ${info.name}`,
+        kind: "consumer",
+        parent: creation,
+        attributes: {
+          "messaging.system": SYSTEM,
+          "messaging.operation.type": "process",
+          "messaging.operation.name": "process",
+          "messaging.destination.name": info.name,
+          "messaging.message.id": info.id,
+          "nifra.job.attempt": info.attempt,
+        },
+      }
+      if (creation !== null) start.links = [{ traceId: creation.traceId, spanId: creation.spanId }]
+      const span = lifecycle.start(start)
+      const trace = span.context
+      try {
+        const outcome =
+          scope === undefined ? await next({ trace }) : await scope(trace, () => next({ trace }))
+        if (outcome === "completed") {
+          span.end({ status: "ok", attributes: { "nifra.job.outcome": outcome } })
+        } else {
+          const attributes: Record<string, AttributeValue> = {
+            "nifra.job.outcome": outcome,
+            "error.type": "_OTHER",
+          }
+          if (outcome === "dead-lettered") attributes["nifra.job.dead_lettered"] = true
+          span.end({ status: "error", attributes })
+        }
+        return outcome
+      } catch (error) {
+        span.recordError(error)
+        span.end({ status: "error", attributes: { "error.type": "_OTHER" } })
+        throw error
+      }
+    },
+  }
+}

package/src/lifecycle.ts

@@ -9,6 +9,7 @@ import type {
   NifraSpan,
   ObservationAdapter,
   ObservationLink,
+  SpanKind,
   SpanStatus,
 } from "./span.ts"
 import {
@@ -27,6 +28,13 @@ export interface ObservationContext {
   readonly traceparent: string
 }
 
+/**
+ * Runs `run` with a span active in an ambient context (OpenTelemetry's, for one), so code that only
+ * sees that context - a pg or undici instrumentation - nests under the span. `otelBridge().scope` from
+ * `@nifrajs/otel/sdk-bridge` is one.
+ */
+export type ObservationScope = <T>(trace: ObservationContext, run: () => T) => T
+
 export interface ObservationParent {
   readonly traceId: string
   readonly spanId: string
@@ -35,6 +43,8 @@ export interface ObservationParent {
 
 export interface StartObservation {
   readonly name: string
+  /** OTel span kind. Omitted, the span exports as `server`. */
+  readonly kind?: SpanKind
   /** Explicit parent. `null` forces a root span; `undefined` falls back to `traceparent`. */
   readonly parent?: ObservationParent | null
   /** Inbound W3C header used when `parent` is undefined. */
@@ -42,6 +52,8 @@ export interface StartObservation {
   readonly attributes?: Readonly<Record<string, AttributeValue>>
   /** Non-parent causal relationships, for example an outbox event that resumed this workflow. */
   readonly links?: readonly ObservationLink[]
+  /** Epoch ms the work began, for work recorded after it settled. Default: now. */
+  readonly startTime?: number
 }
 
 export interface EndObservation {
@@ -49,6 +61,8 @@ export interface EndObservation {
   /** Explicit status wins over status-code and recorded-error classification. */
   readonly status?: Exclude<SpanStatus, "unset">
   readonly attributes?: Readonly<Record<string, AttributeValue>>
+  /** Measured duration in ms, for work recorded after it settled. The end time becomes start + duration. */
+  readonly durationMs?: number
 }
 
 export interface ActiveObservation {
@@ -139,7 +153,10 @@ export function createObservationLifecycle(
     const traceId = parent?.traceId ?? newTraceId()
     const spanId = newSpanId()
     const sampled = parent?.sampled ?? true
-    const startTime = clock.wallTime()
+    const startTime =
+      input.startTime !== undefined && Number.isFinite(input.startTime)
+        ? input.startTime
+        : clock.wallTime()
     const monotonicStart = clock.monotonicTime()
     const span: NifraSpan = {
       traceId,
@@ -147,6 +164,7 @@ export function createObservationLifecycle(
       ...(parent === null ? {} : { parentSpanId: parent.spanId }),
       sampled,
       name: input.name,
+      ...(input.kind === undefined ? {} : { kind: input.kind }),
       startTime,
       status: "unset",
       attributes: { ...input.attributes },
@@ -213,8 +231,13 @@ export function createObservationLifecycle(
         if (ended) return span
         ended = true
         Object.assign(span.attributes, endInput.attributes)
-        span.endTime = clock.wallTime()
-        span.durationMs = Math.max(0, clock.monotonicTime() - monotonicStart)
+        if (endInput.durationMs !== undefined && Number.isFinite(endInput.durationMs)) {
+          span.durationMs = Math.max(0, endInput.durationMs)
+          span.endTime = span.startTime + span.durationMs
+        } else {
+          span.endTime = clock.wallTime()
+          span.durationMs = Math.max(0, clock.monotonicTime() - monotonicStart)
+        }
         span.status =
           endInput.status ??
           (endInput.statusCode === undefined

package/src/otlp.ts

@@ -8,7 +8,7 @@
  * request); delivery failures reach `onError`.
  */
 
-import type { AttributeValue, NifraSpan, ObservationAdapter, SpanStatus } from "./span.ts"
+import type { AttributeValue, NifraSpan, ObservationAdapter, SpanKind, SpanStatus } from "./span.ts"
 
 export interface OtlpExporterOptions {
   /** The collector's traces endpoint, e.g. `http://localhost:4318/v1/traces`. */
@@ -40,6 +40,22 @@ export interface OtlpExporter extends ObservationAdapter {
 }
 
 const STATUS_CODE: Readonly<Record<SpanStatus, number>> = { unset: 0, ok: 1, error: 2 }
+// OTLP `Span.SpanKind`; 0 (UNSPECIFIED) is never sent. A kind is caller data, so anything unknown
+// exports as server, the kind of the spans that predate the field.
+function kindCode(kind: SpanKind | undefined): number {
+  switch (kind) {
+    case "internal":
+      return 1
+    case "client":
+      return 3
+    case "producer":
+      return 4
+    case "consumer":
+      return 5
+    default:
+      return 2
+  }
+}
 
 function assertPositiveSafeInteger(value: number, option: string): void {
   if (!Number.isSafeInteger(value) || value <= 0) {
@@ -69,7 +85,7 @@ function toOtlpSpan(span: NifraSpan): Record<string, unknown> {
     spanId: span.spanId,
     ...(span.parentSpanId !== undefined ? { parentSpanId: span.parentSpanId } : {}),
     name: span.name,
-    kind: 2, // SPAN_KIND_SERVER
+    kind: kindCode(span.kind),
     startTimeUnixNano: String(span.startTime * MS_TO_NANOS),
     endTimeUnixNano: String(end * MS_TO_NANOS),
     attributes: keyValues(span.attributes),

package/src/route-template.ts

@@ -0,0 +1,43 @@
+import { type Method, Router } from "@nifrajs/core/router"
+import type { RouteDescriptor } from "@nifrajs/core/server"
+
+const KNOWN_METHODS: ReadonlySet<string> = new Set([
+  "GET",
+  "HEAD",
+  "POST",
+  "PUT",
+  "DELETE",
+  "PATCH",
+  "OPTIONS",
+  "CONNECT",
+  "TRACE",
+])
+
+/** A method as a label or span name may carry it. Any other method a runtime accepts (Deno takes
+ * extension tokens) is `_OTHER`, as OpenTelemetry's HTTP conventions name it, so a client cannot
+ * mint a new series or span name per request. */
+export function methodLabel(method: string): string {
+  return KNOWN_METHODS.has(method) ? method : "_OTHER"
+}
+
+/**
+ * A request's matched route template (`/users/:id`, never `/users/42`), or `undefined` when no route
+ * serves it. The matcher is built on first use: by serving time every route is registered, so
+ * `app.routes()` is complete, where building it when the plugin is applied would miss later routes.
+ */
+export function routeTemplateOf(app: {
+  routes(): ReadonlyArray<RouteDescriptor>
+}): (method: string, path: string) => string | undefined {
+  let matcher: Router<string> | undefined
+  return (method, path) => {
+    if (matcher === undefined) {
+      matcher = new Router<string>()
+      for (const route of app.routes()) {
+        // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: every registered route's method is one this router already accepted when the app registered it.
+        matcher.add(route.method as Method, route.path, route.path)
+      }
+    }
+    const found = matcher.find(method, path)
+    return found.found ? found.payload : undefined
+  }
+}