@adhd/apigen-plugin-tracing 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# @adhd/apigen-plugin-tracing
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial release. A `Layer` capability that emits one OTel span per dispatched operation
+  (operation id, transport, outcome, duration) to the `@adhd/sox-telemetry` JSONL sink, correlated
+  by `trace_id`. Declares an empty `target` capability for interface parity (`--type tracing` is a
+  valid no-op).
+
+### Patch Changes
+
+- The span's `apigen.transport` is now supplied by the engine from the operation plan's own
+  transport rather than inferred, so every transport — `http`, `grpc`, `mcp`, `cli` — reports
+  its own transport, never `undefined`. Reserved span keys (`apigen.op`, `apigen.transport`,
+  `trace_id`) can no longer be shadowed by an `envelopeAttrs` key of the same name; the reserved keys
+  always win. Streaming operations are quarantined to a unary span (see README): per-chunk records
+  with a chunk count are no longer emitted under the current `Next` contract.

package/README.md

@@ -1,3 +1,113 @@
-# Temporary Holding Version
+# @adhd/apigen-plugin-tracing
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Layer plugin: one OTel span per dispatched operation, written as durable JSONL trace records.
+
+## What it does
+
+`@adhd/apigen-plugin-tracing` instruments **every operation dispatched through an apigen transport**
+— `http`, `grpc`, `mcp`, and `cli` — because all transports converge on a single composed invoker.
+For each dispatched operation it emits a span carrying the operation id, the transport, the outcome,
+and the duration, correlated by a `trace_id` that ties every span of one logical request together.
+
+Records are written through [`@adhd/sox-telemetry`](https://www.npmjs.com/package/@adhd/sox-telemetry)
+to the process's durable JSONL sink (`<dir>/<service>.<role>-<date>.jsonl`), so a second process — or
+the backlog graph — can reconstruct one request across transports.
+
+It is implemented as a **`Layer` capability** (one layer instruments all three transports). A
+`target` capability is declared for interface parity but emits nothing: `--type tracing` resolves to a
+valid no-op rather than an error. This mirrors `apigen-plugin-logger`.
+
+Tracing composes cleanly alongside the logger plugin — same seam, no coupling:
+
+```ts
+usePlugins: [tracingPlugin, loggerPlugin, batchPlugin];
+```
+
+## Install
+
+```bash
+pnpm add @adhd/apigen-plugin-tracing
+```
+
+## Usage
+
+### CLI — bare slug
+
+```bash
+apigen run --source ./api.ts --type mcp --use tracing
+```
+
+Also usable through the v2 multi-use option:
+
+```bash
+apigen run --source ./api.ts --type mcp --use @adhd/apigen-plugin-tracing
+# `--type tracing` is a valid no-op target (emits no files, throws no error)
+apigen run --source ./api.ts --type tracing
+```
+
+### Programmatic
+
+```ts
+import { tracingPlugin, makeTracingPlugin, TraceHandle } from '@adhd/apigen-plugin-tracing';
+
+// default plugin — span prefix `apigen` (zero-config)
+run({ usePlugins: [tracingPlugin] });
+
+// `makeTracingPlugin(...)` is the configured entry point — use it to set the span prefix and
+// copy declared envelope headers onto every span.
+
+// configured
+run({
+  usePlugins: [
+    makeTracingPlugin({
+      serviceName: 'checkout',
+      envelopeAttrs: ['x-request-id'],
+    }),
+  ],
+});
+```
+
+### Annotating the live span from domain code
+
+The layer seeds a `TraceHandle` into `call.ctx`; read it back and add attributes to the live span:
+
+```ts
+import { TraceHandle } from '@adhd/apigen-plugin-tracing';
+
+export async function placeOrder(call, ...args) {
+  const trace = call.ctx.get(TraceHandle);
+  trace?.annotate({ 'order.region': region });
+  // …
+}
+```
+
+`annotate` is a no-op when the operation is not currently inside a unary span (e.g. before the
+downstream resolved, or for a streaming call, which is logged rather than spanned).
+
+## Records
+
+| Event | Level | Carries |
+|---|---|---|
+| `<serviceName>.<op>.start` | info | `apigen.op`, `apigen.transport`, `trace_id` |
+| `<serviceName>.<op>.finish` | info | the above + `duration_ms` |
+| `<serviceName>.<op>.error` | error | the above + `error` (the thrown message) |
+| `apigen.op.error` | error | `apigen.op`, `apigen.transport`, `trace_id`, `span`, `duration_ms`, `err` |
+
+Streaming operations are **quarantined**: under the current `Next` contract
+(`() => Promise<LayerResult>`), an `AsyncIterable` can only be a *resolved* value, never an
+unresolved one, so the layer spans a streaming op only up to the point the stream is obtained — as a
+unary span. Per-chunk `.{start,finish,error}` records with a chunk count are **not** emitted. The
+`traceStream` helper remains in the package (directly unit-tested) behind a quarantine banner for a
+future reopen-span follow-up; `traceUnary` is the only layer path.
+
+## Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `serviceName` | `string` | `'apigen'` | Span / record name prefix. |
+| `envelopeAttrs` | `string[]` | `[]` | Extra `call.envelope` keys copied verbatim onto each span. |
+
+## Part of the apigen toolchain
+
+See [`@adhd/apigen-cli`](https://www.npmjs.com/package/@adhd/apigen-cli) for the full
+TypeScript-to-API system and the list of available plugins.

package/index.d.ts

@@ -0,0 +1,3 @@
+export type { TracingOptions } from './lib/plugin';
+export { TraceHandle, tracingPlugin, makeTracingPlugin } from './lib/plugin';
+export { default } from './lib/plugin';

package/index.js

@@ -0,0 +1 @@
+Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});let e=require("@adhd/sox-telemetry");var t=class{constructor(e,t,n){this.traceId=e,this.spanName=t,this.startedAt=n}annotate(e){let t=n.get(this);t!==void 0&&t.setAttributes(r(e))}},n=new WeakMap;function r(e){let t={};for(let[n,r]of Object.entries(e))(typeof r==`string`||typeof r==`number`||typeof r==`boolean`)&&(t[n]=r);return t}function i(e,t){let n={};for(let r of t){let t=e[r];t!==void 0&&(n[r]=t)}return n}function a(e){return e instanceof Error?e.message:typeof e==`string`?e:typeof e==`object`&&e&&`message`in e&&typeof e.message==`string`?e.message:String(e)}function o(t,i,o,s){return(0,e.withSpan)(i,r(o),async r=>{n.set(s,r);try{return await t}catch(t){throw e.log.error(`apigen.op.error`,{...o,span:i,duration_ms:Date.now()-s.startedAt,err:a(t)}),t}finally{n.delete(s)}})}function s(n={}){let r=n.serviceName??`apigen`,a=n.envelopeAttrs??[];return(n,s)=>{let c=`${r}.${n.operation.id}`,l=(0,e.currentTraceId)()??(0,e.newTraceId)(),u=new t(l,c,Date.now());n.ctx.set(t,u);let d={...i(n.envelope,a),"apigen.op":n.operation.id,"apigen.transport":n.transport,trace_id:l};return(0,e.withTrace)(l,()=>o(Promise.resolve(s()),c,d,u))}}var c={id:`tracing`,description:`Layer plugin: emits one OTel span per dispatched operation (op id, transport, outcome, duration) to the sox-telemetry JSONL sink, correlated by trace_id.`,language:`ts`,optionsSchema:{type:`object`,properties:{serviceName:{type:`string`,description:`Span / record name prefix. Default: apigen.`},envelopeAttrs:{type:`array`,items:{type:`string`},description:`Extra envelope keys copied verbatim onto each span. Default: [].`}},additionalProperties:!1},capabilities:{target:{name:`tracing`,generate(){return[]}},layer:{layer:s()}}};function l(e={}){return{...c,capabilities:{...c.capabilities,layer:{layer:s(e)}}}}exports.TraceHandle=t,exports.default=c,exports.tracingPlugin=c,exports.makeTracingPlugin=l;

package/index.mjs

@@ -0,0 +1,98 @@
+import { currentTraceId as e, log as t, newTraceId as n, withSpan as r, withTrace as i } from "@adhd/sox-telemetry";
+//#region src/lib/plugin.ts
+var a = class {
+	constructor(e, t, n) {
+		this.traceId = e, this.spanName = t, this.startedAt = n;
+	}
+	annotate(e) {
+		let t = o.get(this);
+		t !== void 0 && t.setAttributes(s(e));
+	}
+}, o = /* @__PURE__ */ new WeakMap();
+function s(e) {
+	let t = {};
+	for (let [n, r] of Object.entries(e)) (typeof r == "string" || typeof r == "number" || typeof r == "boolean") && (t[n] = r);
+	return t;
+}
+function c(e, t) {
+	let n = {};
+	for (let r of t) {
+		let t = e[r];
+		t !== void 0 && (n[r] = t);
+	}
+	return n;
+}
+function l(e) {
+	return e instanceof Error ? e.message : typeof e == "string" ? e : typeof e == "object" && e && "message" in e && typeof e.message == "string" ? e.message : String(e);
+}
+function u(e, n, i, a) {
+	return r(n, s(i), async (r) => {
+		o.set(a, r);
+		try {
+			return await e;
+		} catch (e) {
+			throw t.error("apigen.op.error", {
+				...i,
+				span: n,
+				duration_ms: Date.now() - a.startedAt,
+				err: l(e)
+			}), e;
+		} finally {
+			o.delete(a);
+		}
+	});
+}
+function d(t = {}) {
+	let r = t.serviceName ?? "apigen", o = t.envelopeAttrs ?? [];
+	return (t, s) => {
+		let l = `${r}.${t.operation.id}`, d = e() ?? n(), f = new a(d, l, Date.now());
+		t.ctx.set(a, f);
+		let p = {
+			...c(t.envelope, o),
+			"apigen.op": t.operation.id,
+			"apigen.transport": t.transport,
+			trace_id: d
+		};
+		return i(d, () => u(Promise.resolve(s()), l, p, f));
+	};
+}
+var f = {
+	id: "tracing",
+	description: "Layer plugin: emits one OTel span per dispatched operation (op id, transport, outcome, duration) to the sox-telemetry JSONL sink, correlated by trace_id.",
+	language: "ts",
+	optionsSchema: {
+		type: "object",
+		properties: {
+			serviceName: {
+				type: "string",
+				description: "Span / record name prefix. Default: apigen."
+			},
+			envelopeAttrs: {
+				type: "array",
+				items: { type: "string" },
+				description: "Extra envelope keys copied verbatim onto each span. Default: []."
+			}
+		},
+		additionalProperties: !1
+	},
+	capabilities: {
+		target: {
+			name: "tracing",
+			generate() {
+				return [];
+			}
+		},
+		layer: { layer: d() }
+	}
+};
+function p(e = {}) {
+	return {
+		...f,
+		capabilities: {
+			...f.capabilities,
+			layer: { layer: d(e) }
+		}
+	};
+}
+//#endregion
+export { a as TraceHandle, f as default, f as tracingPlugin, p as makeTracingPlugin };

package/lib/plugin.d.ts

@@ -0,0 +1,80 @@
+import { Plugin, Call, Next, Result, Chunk } from '@adhd/apigen-core-client';
+
+/**
+ * Options for {@link makeTracingPlugin}.
+ *
+ * Layer plugins receive no opts at call time — `LayerCapability.layer` is invoked with only
+ * `(call, next)` — so configuration is a factory, exactly as `makeLoggerPlugin` does it.
+ */
+export interface TracingOptions {
+    /** Span / record name prefix. Default: `'apigen'`. */
+    serviceName?: string;
+    /**
+     * Extra attribute keys copied verbatim from `call.envelope` onto each span. Default: `[]`
+     * (only the built-in attrs `apigen.op`, `apigen.transport`, `trace_id` are emitted).
+     */
+    envelopeAttrs?: readonly string[];
+}
+/**
+ * Per-call trace handle, seeded into `call.ctx`. The class is the ctx token: domain code reads
+ * it back with `call.ctx.get(TraceHandle)`.
+ */
+export declare class TraceHandle {
+    /** Correlation id shared by every span of one logical request. */
+    readonly traceId: string;
+    /** Span name — `${serviceName}.${operation.id}`. */
+    readonly spanName: string;
+    /** Epoch millis at which the span opened. */
+    readonly startedAt: number;
+    constructor(
+    /** Correlation id shared by every span of one logical request. */
+    traceId: string, 
+    /** Span name — `${serviceName}.${operation.id}`. */
+    spanName: string, 
+    /** Epoch millis at which the span opened. */
+    startedAt: number);
+    /**
+     * Add attributes to the live span from domain code — opt-in. A no-op when the operation is
+     * not currently inside a unary span (e.g. before the downstream resolved, or for a streaming
+     * call, which is logged rather than spanned).
+     */
+    annotate(fields: Record<string, unknown>): void;
+}
+/**
+ * QUARANTINED — unreachable under the current `Next` contract; see CONTRACT-FIX §4.
+ * Exported only so the streaming branch can be exercised by a direct unit test; no layer
+ * path reaches it (a `Next` resolves to a `LayerResult`, so this detector can never be
+ * true for the unresolved `next()` promise). Retained — never deleted — pending a `Next`
+ * that can yield an iterable before resolution.
+ */
+export declare function isAsyncIterable(value: unknown): value is AsyncIterable<Chunk>;
+/**
+ * QUARANTINED — unreachable under the current `Next` contract; see CONTRACT-FIX §4.
+ * The layer no longer branches on `next()` (an `AsyncIterable` can only be a *resolved*
+ * value, never the unresolved promise), so this is retained with its body intact and
+ * exported solely for a direct unit test. Do NOT re-wire it into the layer by awaiting
+ * `next()` first — that would destroy the span-before-body invariant guarded by
+ * `plugin.spec.ts` (the hang-visibility test).
+ *
+ * Streaming branch — `withSpan` cannot await an iterable, so the `.start` record is emitted
+ * synchronously on entry and an async-generator wrapper yields each chunk unchanged, then
+ * emits `.finish` with the chunk count (or `.error` and re-throws).
+ */
+export declare function traceStream(downstream: AsyncIterable<Chunk>, spanName: string, attrs: Record<string, unknown>): AsyncIterable<Chunk>;
+/**
+ * Build the tracing layer for a given configuration. The returned layer calls `next()` exactly
+ * once and returns its resolved value (or iterable) unchanged, wrapping it in a span.
+ */
+export declare function makeTraceLayer(opts?: TracingOptions): (call: Call, next: Next) => Promise<Result> | AsyncIterable<Chunk>;
+/**
+ * Tracing plugin.
+ *
+ * Implemented as a **Layer** capability — a single layer instruments every transport (http, grpc,
+ * mcp, cli) because they all dispatch through one composed invoker. The `target` capability is
+ * declared but emits nothing (`generate()` returns `[]`), so `--type tracing` resolves to a valid
+ * no-op rather than an error — the same precedent as `apigen-plugin-logger`.
+ */
+export declare const tracingPlugin: Plugin<TracingOptions>;
+/** Configured factory — rebuilds the layer with `opts` (logger precedent). */
+export declare function makeTracingPlugin(opts?: TracingOptions): Plugin<TracingOptions>;
+export default tracingPlugin;

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@adhd/apigen-plugin-tracing",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "dependencies": {
+    "@adhd/apigen-core-client": "^0.3.3",
+    "@adhd/sox-telemetry": "^0.3.2"
+  },
+  "main": "./index.js",
+  "module": "./index.mjs",
+  "types": "./index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Tracing plugin for apigen servers",
+  "keywords": [
+    "tracing",
+    "telemetry",
+    "otel",
+    "apigen",
+    "plugin",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PseudoSky/adhd.git",
+    "directory": "packages/apigen/apigen-plugin-tracing"
+  },
+  "homepage": "https://github.com/PseudoSky/adhd/tree/main/packages/apigen/apigen-plugin-tracing#readme",
+  "bugs": {
+    "url": "https://github.com/PseudoSky/adhd/issues"
+  }
+}