@nwire/observability 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Gefter / 200apps Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# @nwire/observability
+
+> Dispatch tracing — logger-backed by default, OTEL bridge when `@opentelemetry/api` is present.
+
+## What it does
+
+Wraps every dispatch in a span. By default emits two structured log lines per dispatch (`dispatch.start` / `dispatch.end` with `durationMs` + ok/error) because `ctx.logger` already carries envelope ids. If consumers pass an OTEL `tracer` the middleware ALSO opens a span around `next()` — `@opentelemetry/api` stays an optional peer.
+
+## Install
+
+```bash
+pnpm add @nwire/observability
+# optional:
+pnpm add @opentelemetry/api
+```
+
+## Quick start
+
+```ts
+import { tracingPlugin } from "@nwire/observability";
+import { defineApp } from "@nwire/forge";
+import { trace } from "@opentelemetry/api"; // optional
+
+defineApp("my-app", {
+  plugins: [tracingPlugin({ tracer: trace.getTracer("my-app") })],
+});
+```
+
+Or as middleware:
+
+```ts
+import { tracingMiddleware } from "@nwire/observability";
+app.runtime.use(tracingMiddleware());
+```
+
+## API surface
+
+- `tracingPlugin({ tracer?, alwaysLog? })` — `PluginDefinition` form.
+- `tracingMiddleware({ tracer?, alwaysLog? })` — `DispatchMiddleware` form for ad-hoc wiring.
+
+## When to use
+
+Every production app. Fits L2 and up. Pair with `@nwire/telemetry-otel` for OTLP export to Tempo/Honeycomb/Datadog/GreptimeDB.
+
+## Standalone use
+
+For developers using `@nwire/observability` **without the rest of Nwire** — pair it with any TypeScript project, any container, any HTTP framework.
+
+```ts
+// See the package's main entry (src/) for the standalone surface.
+// The exports below work without @nwire/app or @nwire/forge.
+import {} from /* ...standalone exports... */ "@nwire/observability";
+```
+
+## Within nwire-app
+
+For developers using this package as part of the Nwire stack — register it via `app.use(...)` or it auto-wires when you compose `createApp({ modules })`.
+
+```ts
+import { createApp } from "@nwire/forge";
+
+const app = createApp({
+  /* ...config... */
+});
+// Adapter/plugin wiring happens here when applicable.
+```
+
+## See also
+
+- [Architecture sketch §05 — Adapters tier](../../architecture-sketch.html#packages)
+- Sibling packages: [@nwire/logger-pino](../nwire-logger-pino), [@nwire/telemetry-otel](../nwire-telemetry-otel)

package/dist/__tests__/observability.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * tracingMiddleware contract — logs start/end per dispatch, surfaces errors,
+ * runs once per dispatch even with retries, and bridges to an OTEL tracer
+ * when one is provided.
+ */
+export {};
+//# sourceMappingURL=observability.test.d.ts.map

package/dist/__tests__/observability.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/observability.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/__tests__/observability.test.js

@@ -0,0 +1,110 @@
+/**
+ * tracingMiddleware contract — logs start/end per dispatch, surfaces errors,
+ * runs once per dispatch even with retries, and bridges to an OTEL tracer
+ * when one is provided.
+ */
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { defineAction, defineHandler, Runtime } from "@nwire/forge";
+import { tracingMiddleware } from "../observability.js";
+class CapturingLogger {
+    entries = [];
+    debug(message, fields) {
+        this.entries.push({ level: "debug", message, fields });
+    }
+    info(message, fields) {
+        this.entries.push({ level: "info", message, fields });
+    }
+    warn(message, fields) {
+        this.entries.push({ level: "warn", message, fields });
+    }
+    error(message, fields) {
+        this.entries.push({ level: "error", message, fields });
+    }
+    child() {
+        return this;
+    }
+}
+describe("tracingMiddleware", () => {
+    it("logs dispatch.start and dispatch.end with durationMs on success", async () => {
+        const logger = new CapturingLogger();
+        const action = defineAction({ name: "obs.ok", schema: z.object({}) });
+        const handler = defineHandler(action, async () => undefined);
+        const runtime = new Runtime({ logger });
+        runtime.registerHandler(handler);
+        runtime.use(tracingMiddleware());
+        await runtime.dispatch(action, {});
+        const obs = logger.entries.filter((e) => e.message.startsWith("dispatch."));
+        expect(obs.map((e) => e.message)).toEqual(["dispatch.start", "dispatch.end"]);
+        expect(obs[1]?.fields?.ok).toBe(true);
+        expect(typeof obs[1]?.fields?.durationMs).toBe("number");
+        expect(obs[0]?.fields?.action).toBe("obs.ok");
+    });
+    it("logs dispatch.end with ok:false and rethrows on handler error", async () => {
+        const logger = new CapturingLogger();
+        const action = defineAction({ name: "obs.boom", schema: z.object({}) });
+        const handler = defineHandler(action, async () => {
+            throw new Error("kaboom");
+        });
+        const runtime = new Runtime({ logger });
+        runtime.registerHandler(handler);
+        runtime.use(tracingMiddleware());
+        await expect(runtime.dispatch(action, {})).rejects.toThrow(/kaboom/);
+        const end = logger.entries.find((e) => e.message === "dispatch.end");
+        expect(end?.level).toBe("error");
+        expect(end?.fields?.ok).toBe(false);
+        expect(end?.fields?.error).toBe("kaboom");
+    });
+    it("runs exactly once per dispatch despite retries", async () => {
+        const logger = new CapturingLogger();
+        const action = defineAction({
+            name: "obs.retry",
+            schema: z.object({}),
+            retry: { max: 2, backoff: "fixed", baseDelayMs: 1 },
+        });
+        let calls = 0;
+        const handler = defineHandler(action, async () => {
+            calls++;
+            if (calls < 3)
+                throw new Error("flake");
+            return undefined;
+        });
+        const runtime = new Runtime({ logger });
+        runtime.registerHandler(handler);
+        runtime.use(tracingMiddleware());
+        await runtime.dispatch(action, {});
+        expect(calls).toBe(3);
+        const starts = logger.entries.filter((e) => e.message === "dispatch.start");
+        const ends = logger.entries.filter((e) => e.message === "dispatch.end");
+        expect(starts).toHaveLength(1);
+        expect(ends).toHaveLength(1);
+        expect(ends[0]?.fields?.ok).toBe(true);
+    });
+    it("opens an OTEL span when a tracer is provided", async () => {
+        const logger = new CapturingLogger();
+        const action = defineAction({ name: "obs.otel", schema: z.object({}) });
+        const handler = defineHandler(action, async () => undefined);
+        const spanCalls = [];
+        const fakeTracer = {
+            startActiveSpan: async (name, fn) => {
+                spanCalls.push(`start:${name}`);
+                const span = {
+                    setAttribute: (k, v) => spanCalls.push(`attr:${k}=${String(v)}`),
+                    recordException: () => spanCalls.push("exception"),
+                    setStatus: (s) => spanCalls.push(`status:${s.code}`),
+                    end: () => spanCalls.push("end"),
+                };
+                return fn(span);
+            },
+        };
+        const runtime = new Runtime({ logger });
+        runtime.registerHandler(handler);
+        runtime.use(tracingMiddleware({ tracer: fakeTracer }));
+        await runtime.dispatch(action, {});
+        expect(spanCalls[0]).toBe("start:dispatch obs.otel");
+        expect(spanCalls).toContain("attr:nwire.action=obs.otel");
+        expect(spanCalls).toContain("status:1");
+        expect(spanCalls[spanCalls.length - 1]).toBe("end");
+    });
+});
+//# sourceMappingURL=observability.test.js.map

package/dist/__tests__/observability.test.js.map

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

package/dist/observability.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `@nwire/observability` — dispatch tracing.
+ *
+ * Wraps every dispatch in a logger-backed span (entry + exit + durationMs
+ * + ok/error). If consumers pass an OTEL `tracer` the middleware ALSO
+ * opens an OTEL span — `@opentelemetry/api` stays an optional peer.
+ * Plugin and middleware forms both ship.
+ *
+ * See: architecture-sketch.html §05 (Adapters tier).
+ */
+import type { DispatchMiddleware, PluginDefinition } from "@nwire/forge";
+export interface TracingOptions {
+    /**
+     * If true (default), logs `dispatch.start` and `dispatch.end` per
+     * dispatch. Set false to emit only on errors.
+     */
+    readonly logEachDispatch?: boolean;
+    /**
+     * Optional OTEL `Tracer` instance. When provided, an OTEL span wraps
+     * `next()`. We type it as `unknown` and probe at runtime so
+     * @opentelemetry/api stays optional.
+     */
+    readonly tracer?: unknown;
+    /** Span name builder. Default: `dispatch <action.name>`. */
+    readonly spanName?: (actionName: string) => string;
+}
+export declare function tracingMiddleware(options?: TracingOptions): DispatchMiddleware;
+/**
+ * Plugin form — the recommended shape for new code.
+ *   createApp({ plugins: [tracingPlugin({ tracer })] })
+ */
+export declare function tracingPlugin(options?: TracingOptions): PluginDefinition;
+//# sourceMappingURL=observability.d.ts.map

package/dist/observability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../src/observability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGzE,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;CACpD;AAYD,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,cAAmB,GAAG,kBAAkB,CAwDlF;AASD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,cAAmB,GAAG,gBAAgB,CAI5E"}

package/dist/observability.js

@@ -0,0 +1,85 @@
+/**
+ * `@nwire/observability` — dispatch tracing.
+ *
+ * Wraps every dispatch in a logger-backed span (entry + exit + durationMs
+ * + ok/error). If consumers pass an OTEL `tracer` the middleware ALSO
+ * opens an OTEL span — `@opentelemetry/api` stays an optional peer.
+ * Plugin and middleware forms both ship.
+ *
+ * See: architecture-sketch.html §05 (Adapters tier).
+ */
+import { definePlugin } from "@nwire/forge";
+export function tracingMiddleware(options = {}) {
+    const logEach = options.logEachDispatch ?? true;
+    const spanName = options.spanName ?? ((name) => `dispatch ${name}`);
+    const tracer = options.tracer;
+    return async (next, action, _input, ctx) => {
+        const start = nowMs();
+        if (logEach) {
+            ctx.logger.info("dispatch.start", { action: action.name });
+        }
+        const run = async () => {
+            try {
+                const result = await next();
+                if (logEach) {
+                    ctx.logger.info("dispatch.end", {
+                        action: action.name,
+                        durationMs: nowMs() - start,
+                        ok: true,
+                    });
+                }
+                return result;
+            }
+            catch (err) {
+                ctx.logger.error("dispatch.end", {
+                    action: action.name,
+                    durationMs: nowMs() - start,
+                    ok: false,
+                    error: err?.message,
+                });
+                throw err;
+            }
+        };
+        if (!tracer || typeof tracer.startActiveSpan !== "function") {
+            return run();
+        }
+        return tracer.startActiveSpan(spanName(action.name), async (span) => {
+            try {
+                span.setAttribute("nwire.action", action.name);
+                if (ctx.envelope.tenant)
+                    span.setAttribute("nwire.tenant", ctx.envelope.tenant);
+                if (ctx.envelope.userId)
+                    span.setAttribute("nwire.user_id", ctx.envelope.userId);
+                span.setAttribute("nwire.message_id", ctx.envelope.messageId);
+                span.setAttribute("nwire.correlation_id", ctx.envelope.correlationId);
+                const result = await run();
+                span.setStatus({ code: 1 /* OK */ });
+                return result;
+            }
+            catch (err) {
+                span.recordException(err);
+                span.setStatus({ code: 2 /* ERROR */, message: err?.message });
+                throw err;
+            }
+            finally {
+                span.end();
+            }
+        });
+    };
+}
+function nowMs() {
+    if (typeof performance !== "undefined" && typeof performance.now === "function") {
+        return performance.now();
+    }
+    return Date.now();
+}
+/**
+ * Plugin form — the recommended shape for new code.
+ *   createApp({ plugins: [tracingPlugin({ tracer })] })
+ */
+export function tracingPlugin(options = {}) {
+    return definePlugin("observability", {
+        middleware: [tracingMiddleware(options)],
+    });
+}
+//# sourceMappingURL=observability.js.map

package/dist/observability.js.map

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

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@nwire/observability",
+  "version": "0.7.0",
+  "description": "Nwire — dispatch tracing middleware. Logger-backed by default, with optional bridge to @opentelemetry/api (declared by the consumer, not by us).",
+  "keywords": [
+    "middleware",
+    "nwire",
+    "observability",
+    "otel",
+    "tracing"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/observability.js",
+  "types": "./dist/observability.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/observability.js",
+      "types": "./dist/observability.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nwire/forge": "0.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.9",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc && node ../../scripts/fix-dist-extensions.mjs dist",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}