@nwire/telemetry-otel 0.7.0

package/src/exporter.ts

@@ -0,0 +1,416 @@
+/**
+ * `attachOtelExporter(runtime, options)` — translates the canonical
+ * Nwire telemetry stream into OpenTelemetry spans + events.
+ *
+ *   import { trace } from "@opentelemetry/api";
+ *   import { attachOtelExporter } from "@nwire/telemetry-otel";
+ *
+ *   const tracer = trace.getTracer("amit");
+ *   const detach = attachOtelExporter(app.runtime, { tracer });
+ *
+ * Every Telemetry kind gets a sensible OTel mapping:
+ *
+ *   action.dispatched           → open span  "action {name}"      (parent for the dispatch)
+ *   action.completed            → close that span with ok status
+ *   action.failed               → addEvent  "action.failed" (attempt + error)
+ *   dlq.recorded                → close span with error status + dlq event
+ *   event.published             → addEvent  "event.published" on the open action span
+ *                                  OR ad-hoc span if no open parent
+ *   actor.transitioned          → addEvent  "actor.transitioned"
+ *   projection.folded           → addEvent  "projection.folded"
+ *   reaction.fired              → child span "reaction {sourceEvent}"
+ *   reaction.failed             → addEvent on the parent + recordException
+ *   query.executed              → ad-hoc span "query {name}"
+ *   timer.scheduled / .fired    → addEvent
+ *   external.call.started       → open child span "external {call}"
+ *   external.call.completed     → close it with ok
+ *   external.call.failed        → close it with error + addEvent per attempt
+ *   inbound.webhook.received    → ad-hoc span "webhook {name}"
+ *   outbox.flushed              → addEvent (could become a metric later)
+ *   inbox.dedup.hit             → addEvent
+ *   queue.job.{enqueued,started,completed}  → ad-hoc span "queue {queue}/{jobId}"
+ *   cron.fired                  → ad-hoc span "cron {name}"
+ *
+ * Spans are correlated by `envelope.messageId` (when present) — open spans
+ * are tracked in a Map so completion records can look them up. If a
+ * close-record arrives with no matching open span (e.g. listener attached
+ * mid-flight), we emit an orphan span with `{ status: ERROR, orphan: true }`.
+ *
+ * Returns a detach function — calling it unsubscribes and closes any
+ * still-open spans with an `unsubscribed` event.
+ */
+
+import type { Runtime, Telemetry, SerializedError } from "@nwire/forge";
+import type { OtelTracer, OtelSpan, SpanStatusCode } from "./otel-types";
+
+export interface AttachOtelExporterOptions {
+  /** OTel Tracer instance from `trace.getTracer(name, version?)`. */
+  readonly tracer: OtelTracer;
+  /**
+   * Prefix to apply to span names. Default `'nwire.'` so traces in OTLP
+   * backends stand out. Pass empty string to disable.
+   */
+  readonly spanNamePrefix?: string;
+  /**
+   * Custom event-published handling. By default, we attach published
+   * events as span events on the open action span. If you prefer each
+   * event as its own span, set `eventsAsSpans: true`.
+   */
+  readonly eventsAsSpans?: boolean;
+  /**
+   * Filter which telemetry kinds to forward. Default: all. Pass an array
+   * to opt in to specific kinds (e.g. for high-volume production traffic
+   * you might keep only action.* + external.call.*).
+   */
+  readonly kinds?: readonly Telemetry["kind"][];
+}
+
+const OK: SpanStatusCode = 1;
+const ERROR: SpanStatusCode = 2;
+
+interface OpenSpan {
+  readonly span: OtelSpan;
+  readonly startedAt: number;
+}
+
+export function attachOtelExporter(
+  runtime: Runtime,
+  options: AttachOtelExporterOptions,
+): () => void {
+  const tracer = options.tracer;
+  const prefix = options.spanNamePrefix ?? "nwire.";
+  const eventsAsSpans = options.eventsAsSpans ?? false;
+  const allowed: ReadonlySet<string> | null = options.kinds ? new Set(options.kinds) : null;
+
+  // Open spans, keyed by envelope.messageId (action) or call+messageId
+  // pair (external call). When the matching completion arrives we close.
+  const actionSpans = new Map<string, OpenSpan>();
+  const externalCallSpans = new Map<string, OpenSpan>();
+
+  const unsubscribe = runtime.onTelemetry((rec) => {
+    if (allowed && !allowed.has(rec.kind)) return;
+    try {
+      route(rec);
+    } catch (err) {
+      // Don't let exporter errors break the runtime — the framework's
+      // emit() already guards listener throws, but we add explicit
+      // logging here too.
+      // eslint-disable-next-line no-console
+      console.error("[telemetry-otel] export failed:", err);
+    }
+  });
+
+  function route(rec: Telemetry): void {
+    switch (rec.kind) {
+      case "action.dispatched":
+        openActionSpan(rec);
+        return;
+      case "action.completed":
+        closeActionSpan(rec, OK, undefined, {
+          "nwire.action.duration_ms": rec.durationMs,
+          "nwire.action.emitted_events": rec.emittedEvents.join(","),
+        });
+        return;
+      case "action.failed":
+        addEventToActionSpan(rec.envelope.messageId, "action.failed", {
+          "nwire.action.attempt": rec.attempt,
+          "nwire.action.max_attempts": rec.maxAttempts,
+          "nwire.action.will_retry": rec.willRetry,
+          ...errorAttrs(rec.error),
+        });
+        return;
+      case "dlq.recorded":
+        closeActionSpan(rec, ERROR, rec.error.message, {
+          "nwire.dlq.attempts": rec.attempts,
+          ...errorAttrs(rec.error),
+        });
+        return;
+      case "event.published":
+        if (eventsAsSpans) {
+          adhocSpan(`event ${rec.event.eventName}`, rec.ts, {
+            "nwire.event.name": rec.event.eventName,
+            "nwire.event.source": rec.source,
+            ...envelopeAttrs(rec.envelope),
+          });
+        } else {
+          // Event records carry a DERIVED envelope: messageId is the
+          // event's own, causationId is the action that emitted it. So
+          // we look up the action span by causationId.
+          addEventToActionSpan(rec.envelope.causationId, "event.published", {
+            "nwire.event.name": rec.event.eventName,
+            "nwire.event.source": rec.source,
+          });
+        }
+        return;
+      case "actor.transitioned":
+        addEventToActionSpan(rec.envelope.causationId, "actor.transitioned", {
+          "nwire.actor": rec.actor,
+          "nwire.actor.key": rec.key,
+          "nwire.actor.from": rec.from,
+          "nwire.actor.to": rec.to,
+          "nwire.actor.event": rec.triggeringEvent,
+        });
+        return;
+      case "projection.folded":
+        addEventToActionSpan(rec.envelope.causationId, "projection.folded", {
+          "nwire.projection": rec.projection,
+          "nwire.event.name": rec.event,
+          "nwire.projection.duration_ms": rec.durationMs,
+        });
+        return;
+      case "reaction.fired":
+        adhocSpan(`reaction ${rec.sourceEvent}`, rec.ts, {
+          "nwire.reaction.source_event": rec.sourceEvent,
+          "nwire.reaction.duration_ms": rec.durationMs,
+          ...envelopeAttrs(rec.envelope),
+        });
+        return;
+      case "reaction.failed":
+        addEventToActionSpan(rec.envelope.causationId, "reaction.failed", {
+          "nwire.reaction.source_event": rec.sourceEvent,
+          ...errorAttrs(rec.error),
+        });
+        return;
+      case "query.executed":
+        adhocSpan(`query ${rec.query}`, rec.ts, {
+          "nwire.query.name": rec.query,
+          "nwire.query.duration_ms": rec.durationMs,
+          "nwire.tenant": rec.tenant,
+        });
+        return;
+      case "timer.scheduled":
+      case "timer.fired":
+        adhocSpan(rec.kind, rec.ts, {
+          "nwire.actor": rec.actor,
+          "nwire.actor.key": rec.key,
+          "nwire.timer.name": rec.timer,
+          "nwire.timer.action": rec.action,
+          "nwire.tenant": rec.tenant,
+          ...(rec.kind === "timer.fired"
+            ? { "nwire.timer.late_by_ms": rec.lateByMs }
+            : { "nwire.timer.fire_at": rec.fireAt }),
+        });
+        return;
+      case "external.call.started":
+        openExternalCallSpan(rec);
+        return;
+      case "external.call.completed":
+        closeExternalCallSpan(rec, OK, undefined, {
+          "nwire.external.duration_ms": rec.durationMs,
+          ...(rec.status !== undefined ? { "nwire.external.status": rec.status } : {}),
+        });
+        return;
+      case "external.call.failed":
+        closeExternalCallSpan(rec, ERROR, rec.error.message, {
+          "nwire.external.attempt": rec.attempt,
+          "nwire.external.will_retry": rec.willRetry,
+          ...errorAttrs(rec.error),
+        });
+        return;
+      case "inbound.webhook.received":
+        adhocSpan(`webhook ${rec.webhook}`, rec.ts, {
+          "nwire.webhook.name": rec.webhook,
+          "nwire.webhook.source": rec.source,
+          "nwire.webhook.signature_valid": rec.signatureValid,
+          "nwire.webhook.dedup_hit": rec.dedupHit,
+          ...(rec.routedTo ? { "nwire.webhook.routed_to": rec.routedTo } : {}),
+        });
+        return;
+      case "outbox.flushed":
+        adhocSpan(`outbox ${rec.outbox} flush`, rec.ts, {
+          "nwire.outbox.name": rec.outbox,
+          "nwire.outbox.events": rec.events,
+          "nwire.outbox.failed": rec.failed,
+          "nwire.outbox.duration_ms": rec.durationMs,
+        });
+        return;
+      case "inbox.dedup.hit":
+        adhocSpan(`inbox ${rec.inbox} dedup`, rec.ts, {
+          "nwire.inbox.name": rec.inbox,
+          "nwire.inbox.message_id": rec.messageId,
+          "nwire.inbox.first_seen_at": rec.firstSeenAt,
+        });
+        return;
+      case "queue.job.enqueued":
+      case "queue.job.started":
+      case "queue.job.completed":
+        adhocSpan(`queue ${rec.queue}/${rec.kind.replace("queue.job.", "")}`, rec.ts, {
+          "nwire.queue.name": rec.queue,
+          "nwire.queue.job_id": rec.jobId,
+          ...(rec.kind === "queue.job.enqueued" && rec.delay !== undefined
+            ? { "nwire.queue.delay": rec.delay }
+            : {}),
+          ...(rec.kind === "queue.job.started" ? { "nwire.queue.waited_ms": rec.waitedMs } : {}),
+          ...(rec.kind === "queue.job.completed"
+            ? { "nwire.queue.duration_ms": rec.durationMs, "nwire.queue.ok": rec.ok }
+            : {}),
+        });
+        return;
+      case "cron.fired":
+        adhocSpan(`cron ${rec.cronName}`, rec.ts, {
+          "nwire.cron.name": rec.cronName,
+          "nwire.cron.schedule": rec.schedule,
+          "nwire.cron.expected": rec.expected,
+          "nwire.cron.actual": rec.actual,
+          "nwire.cron.late_by_ms": rec.lateByMs,
+        });
+        return;
+    }
+  }
+
+  function openActionSpan(rec: Extract<Telemetry, { kind: "action.dispatched" }>): void {
+    const span = tracer.startSpan(`${prefix}action ${rec.action}`, {
+      startTime: new Date(rec.ts),
+      attributes: {
+        "nwire.action": rec.action,
+        ...envelopeAttrs(rec.envelope),
+        "nwire.app": rec.appName,
+      },
+    });
+    actionSpans.set(rec.envelope.messageId, { span, startedAt: Date.now() });
+  }
+
+  function closeActionSpan(
+    rec: { ts: string; envelope: { messageId: string }; appName: string },
+    status: SpanStatusCode,
+    msg: string | undefined,
+    attrs: Record<string, unknown>,
+  ): void {
+    const open = actionSpans.get(rec.envelope.messageId);
+    if (!open) {
+      // Orphan — close-record without an open span. Emit an ad-hoc record
+      // so we don't silently drop data.
+      adhocSpan(`${prefix}action.orphan`, rec.ts, {
+        "nwire.orphan": true,
+        "nwire.app": rec.appName,
+        ...attrs,
+      });
+      return;
+    }
+    actionSpans.delete(rec.envelope.messageId);
+    setAttrs(open.span, attrs);
+    open.span.setStatus({ code: status, message: msg });
+    open.span.end(new Date(rec.ts));
+  }
+
+  function addEventToActionSpan(
+    messageId: string,
+    name: string,
+    attrs: Record<string, unknown>,
+  ): void {
+    const open = actionSpans.get(messageId);
+    if (open) {
+      open.span.addEvent(name, attrs);
+      return;
+    }
+    // No parent — emit standalone ad-hoc.
+    adhocSpan(name, new Date().toISOString(), attrs);
+  }
+
+  function openExternalCallSpan(rec: Extract<Telemetry, { kind: "external.call.started" }>): void {
+    const span = tracer.startSpan(`${prefix}external ${rec.call}`, {
+      startTime: new Date(rec.ts),
+      attributes: {
+        "nwire.external.call": rec.call,
+        "nwire.external.target": rec.target,
+        ...(rec.idempotencyKey ? { "nwire.external.idempotency_key": rec.idempotencyKey } : {}),
+        ...(rec.envelope ? envelopeAttrs(rec.envelope) : {}),
+        "nwire.app": rec.appName,
+      },
+    });
+    // Key by call + correlation; multiple concurrent calls with same name
+    // would collide, so include messageId if available.
+    const key = externalCallKey(rec.call, rec.envelope?.messageId);
+    externalCallSpans.set(key, { span, startedAt: Date.now() });
+  }
+
+  function closeExternalCallSpan(
+    rec:
+      | Extract<Telemetry, { kind: "external.call.completed" }>
+      | Extract<Telemetry, { kind: "external.call.failed" }>,
+    status: SpanStatusCode,
+    msg: string | undefined,
+    attrs: Record<string, unknown>,
+  ): void {
+    const key = externalCallKey(rec.call, rec.envelope?.messageId);
+    const open = externalCallSpans.get(key);
+    if (!open) {
+      adhocSpan(`${prefix}external.orphan ${rec.call}`, rec.ts, {
+        "nwire.orphan": true,
+        "nwire.external.call": rec.call,
+        "nwire.external.target": rec.target,
+        ...attrs,
+      });
+      return;
+    }
+    externalCallSpans.delete(key);
+    setAttrs(open.span, attrs);
+    open.span.setStatus({ code: status, message: msg });
+    open.span.end(new Date(rec.ts));
+  }
+
+  function externalCallKey(call: string, messageId: string | undefined): string {
+    return `${call}::${messageId ?? "no-envelope"}`;
+  }
+
+  function adhocSpan(name: string, ts: string, attrs: Record<string, unknown>): void {
+    const startTime = new Date(ts);
+    const span = tracer.startSpan(name.startsWith(prefix) ? name : `${prefix}${name}`, {
+      startTime,
+      attributes: attrs,
+    });
+    span.end(startTime);
+  }
+
+  return () => {
+    unsubscribe();
+    // Close any still-open spans so the exporter flushes them.
+    for (const { span } of actionSpans.values()) {
+      span.addEvent("nwire.unsubscribed");
+      span.end();
+    }
+    for (const { span } of externalCallSpans.values()) {
+      span.addEvent("nwire.unsubscribed");
+      span.end();
+    }
+    actionSpans.clear();
+    externalCallSpans.clear();
+  };
+}
+
+function envelopeAttrs(envelope: {
+  messageId: string;
+  correlationId: string;
+  causationId: string;
+  tenant?: string;
+  userId?: string;
+  timestamp: string;
+}): Record<string, unknown> {
+  return {
+    "nwire.message_id": envelope.messageId,
+    "nwire.correlation_id": envelope.correlationId,
+    "nwire.causation_id": envelope.causationId,
+    ...(envelope.tenant ? { "nwire.tenant": envelope.tenant } : {}),
+    ...(envelope.userId ? { "nwire.user_id": envelope.userId } : {}),
+  };
+}
+
+function errorAttrs(err: SerializedError): Record<string, unknown> {
+  return {
+    "nwire.error.name": err.name,
+    "nwire.error.message": err.message,
+    ...(err.stack ? { "nwire.error.stack": err.stack } : {}),
+  };
+}
+
+function setAttrs(span: OtelSpan, attrs: Record<string, unknown>): void {
+  if (span.setAttributes) {
+    span.setAttributes(attrs);
+    return;
+  }
+  for (const [k, v] of Object.entries(attrs)) {
+    if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
+      span.setAttribute(k, v);
+    }
+  }
+}

package/src/otel-types.ts

@@ -0,0 +1,42 @@
+/**
+ * Minimal duck-typed surface of `@opentelemetry/api`'s Tracer + Span. We
+ * never import the package — consumers bring their own version and pass a
+ * `Tracer` in. This keeps `@nwire/telemetry-otel` zero-dep at runtime
+ * (only `@nwire/forge` for the Telemetry type).
+ *
+ * The fields are the subset we actually use. If a consumer passes a real
+ * `@opentelemetry/api` Tracer, structural typing makes it compatible.
+ */
+
+export type SpanKind = 0 | 1 | 2 | 3 | 4 | 5;
+export type SpanStatusCode = 0 | 1 | 2;
+
+export interface SpanContext {
+  traceId: string;
+  spanId: string;
+}
+
+export interface OtelSpan {
+  spanContext?(): SpanContext;
+  setAttribute(key: string, value: string | number | boolean): OtelSpan | void;
+  setAttributes?(attrs: Record<string, unknown>): OtelSpan | void;
+  addEvent(
+    name: string,
+    attrs?: Record<string, unknown>,
+    timestamp?: number | Date,
+  ): OtelSpan | void;
+  recordException(err: unknown): OtelSpan | void;
+  setStatus(status: { code: SpanStatusCode; message?: string }): OtelSpan | void;
+  end(endTime?: number | Date): void;
+}
+
+export interface OtelTracer {
+  startSpan(
+    name: string,
+    options?: {
+      attributes?: Record<string, unknown>;
+      kind?: SpanKind;
+      startTime?: number | Date;
+    },
+  ): OtelSpan;
+}

package/src/telemetry-otel.ts

@@ -0,0 +1,18 @@
+/**
+ * `@nwire/telemetry-otel` — OpenTelemetry bridge for the canonical Nwire
+ * telemetry stream. Subscribes to `runtime.onTelemetry` and translates
+ * every record into OTel spans + events.
+ *
+ *   import { trace } from "@opentelemetry/api";
+ *   import { attachOtelExporter } from "@nwire/telemetry-otel";
+ *
+ *   const detach = attachOtelExporter(app.runtime, {
+ *     tracer: trace.getTracer("amit"),
+ *   });
+ *
+ * Pairs cleanly with Vector → GreptimeDB (and any other OTLP backend —
+ * Datadog, Honeycomb, Tempo, Jaeger).
+ */
+
+export { attachOtelExporter, type AttachOtelExporterOptions } from "./exporter";
+export type { OtelTracer, OtelSpan, SpanContext, SpanKind, SpanStatusCode } from "./otel-types";