@nwire/telemetry-otel 0.7.0

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@nwire/telemetry-otel",
+  "version": "0.7.0",
+  "private": false,
+  "description": "OpenTelemetry bridge for the Nwire canonical telemetry stream. Translates every Telemetry record into OTLP spans + events. Plug in any OTEL exporter (Datadog, Honeycomb, Tempo, Vector → GreptimeDB).",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "main": "./dist/telemetry-otel.js",
+  "types": "./dist/telemetry-otel.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/telemetry-otel.js",
+      "types": "./dist/telemetry-otel.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nwire/forge": "0.7.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/__tests__/exporter.test.ts

@@ -0,0 +1,256 @@
+/**
+ * `@nwire/telemetry-otel` — exporter end-to-end against a fake tracer.
+ *
+ * Exercises real runtime dispatch + external call paths, then asserts the
+ * spans + events the bridge produced. The fake tracer records every
+ * startSpan / span method call so tests can inspect them.
+ */
+
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import * as forge from "@nwire/forge";
+import { attachOtelExporter } from "../telemetry-otel";
+import type { OtelTracer, OtelSpan } from "../telemetry-otel";
+
+interface RecordedSpan {
+  name: string;
+  attributes: Record<string, unknown>;
+  events: Array<{ name: string; attrs?: Record<string, unknown> }>;
+  status: { code: number; message?: string } | null;
+  ended: boolean;
+  endTime?: number | Date;
+  startTime?: number | Date;
+}
+
+function makeFakeTracer(): { tracer: OtelTracer; spans: RecordedSpan[] } {
+  const spans: RecordedSpan[] = [];
+  const tracer: OtelTracer = {
+    startSpan(name, options) {
+      const rec: RecordedSpan = {
+        name,
+        attributes: { ...(options?.attributes ?? {}) },
+        events: [],
+        status: null,
+        ended: false,
+        startTime: options?.startTime,
+      };
+      spans.push(rec);
+      const span: OtelSpan = {
+        setAttribute(k, v) {
+          rec.attributes[k] = v;
+        },
+        setAttributes(attrs) {
+          Object.assign(rec.attributes, attrs);
+        },
+        addEvent(eventName, attrs) {
+          rec.events.push({ name: eventName, attrs });
+        },
+        recordException() {
+          /* noop */
+        },
+        setStatus(s) {
+          rec.status = { ...s };
+        },
+        end(endTime) {
+          rec.ended = true;
+          rec.endTime = endTime;
+        },
+      };
+      return span;
+    },
+  };
+  return { tracer, spans };
+}
+
+const SubmitInput = z.object({ who: z.string() });
+
+const submit = forge.defineAction({
+  name: "demo.submit",
+  schema: SubmitInput,
+  emits: [],
+  handler: async () => ({ eventName: "demo.submitted", payload: { who: "Avi" } }),
+});
+
+const demoModule = forge.defineModule("demo", { actions: [submit] });
+const demoApp = forge.defineApp("demo-app", { modules: [demoModule] });
+
+describe("attachOtelExporter", () => {
+  it("opens + closes a span for a successful dispatch", async () => {
+    const app = demoApp.create();
+    await app.start();
+    const { tracer, spans } = makeFakeTracer();
+    const detach = attachOtelExporter(app.runtime, { tracer });
+
+    await app.runtime.dispatch(submit, { who: "Avi" });
+    detach();
+
+    const action = spans.find((s) => s.name.includes("action demo.submit"));
+    expect(action).toBeDefined();
+    expect(action!.ended).toBe(true);
+    expect(action!.status?.code).toBe(1); // OK
+    expect(action!.attributes["nwire.action"]).toBe("demo.submit");
+    expect(typeof action!.attributes["nwire.message_id"]).toBe("string");
+    expect(action!.attributes["nwire.action.emitted_events"]).toBe("demo.submitted");
+    // event.published should appear as a span event on the action span (default mode).
+    expect(action!.events.some((e) => e.name === "event.published")).toBe(true);
+  });
+
+  it("attaches event.published as a span event when eventsAsSpans=false", async () => {
+    const app = demoApp.create();
+    await app.start();
+    const { tracer, spans } = makeFakeTracer();
+    attachOtelExporter(app.runtime, { tracer });
+    await app.runtime.dispatch(submit, { who: "Avi" });
+
+    const actionSpans = spans.filter((s) => s.name.includes("action demo.submit"));
+    expect(actionSpans).toHaveLength(1);
+    // No standalone event span.
+    expect(spans.some((s) => s.name.includes("event demo.submitted"))).toBe(false);
+  });
+
+  it("opens a standalone span per event when eventsAsSpans=true", async () => {
+    const app = demoApp.create();
+    await app.start();
+    const { tracer, spans } = makeFakeTracer();
+    attachOtelExporter(app.runtime, { tracer, eventsAsSpans: true });
+    await app.runtime.dispatch(submit, { who: "Avi" });
+
+    expect(spans.some((s) => s.name.includes("event demo.submitted"))).toBe(true);
+  });
+
+  it("filters by kind when `kinds` is set", async () => {
+    const app = demoApp.create();
+    await app.start();
+    const { tracer, spans } = makeFakeTracer();
+    attachOtelExporter(app.runtime, {
+      tracer,
+      kinds: ["action.dispatched", "action.completed"],
+    });
+    await app.runtime.dispatch(submit, { who: "Avi" });
+
+    // No event-published span events should appear since we filtered them out.
+    const actionSpan = spans.find((s) => s.name.includes("action demo.submit"))!;
+    expect(actionSpan.events.some((e) => e.name === "event.published")).toBe(false);
+  });
+
+  it("emits ad-hoc spans for query.executed", async () => {
+    const SkillState = z.object({ items: z.array(z.string()).default([]) });
+    const Skills = forge.defineProjection<{ items: string[] }>("skills", {
+      listens: [],
+      initial: () => ({ items: [] }),
+      on: {},
+    });
+    const listSkills = forge.defineQuery(Skills, {
+      name: "skills.list",
+      schema: z.object({}),
+      execute: (state) => state.items,
+    });
+    void SkillState;
+    const queryModule = forge.defineModule("queries", {
+      projections: [Skills],
+      queries: [listSkills],
+    });
+    const queryApp = forge.defineApp("query-app", { modules: [queryModule] });
+    const app = queryApp.create();
+    await app.start();
+
+    const { tracer, spans } = makeFakeTracer();
+    attachOtelExporter(app.runtime, { tracer });
+    await app.runtime.query("skills.list", {}, "");
+
+    const querySpan = spans.find((s) => s.name.includes("query skills.list"));
+    expect(querySpan).toBeDefined();
+    expect(querySpan!.attributes["nwire.query.name"]).toBe("skills.list");
+    expect(typeof querySpan!.attributes["nwire.query.duration_ms"]).toBe("number");
+  });
+
+  it("traces external calls as child spans", async () => {
+    const Notify = forge.defineExternalCall({
+      name: "notify",
+      target: { provider: "x", endpoint: "/ping" },
+      request: z.object({ to: z.string() }),
+      response: z.object({ ok: z.boolean() }),
+    });
+    const send = forge.defineAction({
+      name: "ops.send",
+      schema: z.object({ to: z.string() }),
+      handler: async (input, ctx) => {
+        await ctx.externalCall(Notify, { to: input.to });
+        return undefined;
+      },
+    });
+    const opsModule = forge.defineModule("ops", {
+      actions: [send],
+      externalCalls: [Notify],
+    });
+    const opsApp = forge.defineApp("ops-app", { modules: [opsModule] });
+    const app = opsApp.create();
+    await app.start();
+    app.runtime.registerExternalCallExecutor(Notify, async () => ({ ok: true }));
+
+    const { tracer, spans } = makeFakeTracer();
+    attachOtelExporter(app.runtime, { tracer });
+
+    await app.runtime.dispatch(send, { to: "avi" });
+
+    const ext = spans.find((s) => s.name.includes("external notify"));
+    expect(ext).toBeDefined();
+    expect(ext!.ended).toBe(true);
+    expect(ext!.status?.code).toBe(1); // OK
+    expect(ext!.attributes["nwire.external.call"]).toBe("notify");
+    expect(ext!.attributes["nwire.external.target"]).toBe("x//ping");
+  });
+
+  it("closes external-call span with ERROR on failure", async () => {
+    const Notify = forge.defineExternalCall({
+      name: "flaky",
+      target: { provider: "x", endpoint: "/boom" },
+      request: z.object({}),
+    });
+    const send = forge.defineAction({
+      name: "ops.boom",
+      schema: z.object({}),
+      handler: async (_input, ctx) => {
+        try {
+          await ctx.externalCall(Notify, {});
+        } catch {
+          /* expected */
+        }
+        return undefined;
+      },
+    });
+    const opsModule = forge.defineModule("ops2", {
+      actions: [send],
+      externalCalls: [Notify],
+    });
+    const opsApp = forge.defineApp("ops2-app", { modules: [opsModule] });
+    const app = opsApp.create();
+    await app.start();
+    app.runtime.registerExternalCallExecutor(Notify, async () => {
+      throw new Error("nope");
+    });
+
+    const { tracer, spans } = makeFakeTracer();
+    attachOtelExporter(app.runtime, { tracer });
+    await app.runtime.dispatch(send, {});
+
+    const ext = spans.find((s) => s.name.includes("external flaky"));
+    expect(ext).toBeDefined();
+    expect(ext!.status?.code).toBe(2); // ERROR
+    expect(ext!.attributes["nwire.error.message"]).toBe("nope");
+  });
+
+  it("detach() unsubscribes and closes still-open spans", async () => {
+    const app = demoApp.create();
+    await app.start();
+    const { tracer, spans } = makeFakeTracer();
+    const detach = attachOtelExporter(app.runtime, { tracer });
+
+    // Detach mid-flight; the exporter should still flush.
+    detach();
+    // After detach, new events should NOT produce more spans.
+    const before = spans.length;
+    await app.runtime.dispatch(submit, { who: "Dina" });
+    expect(spans.length).toBe(before);
+  });
+});