autotel 4.2.1 → 4.2.2

package/README.md

@@ -1880,6 +1880,56 @@ try {
 }
 ```
 
+## Diagnostics Channels
+
+`autotel/diagnostics` bridges Node's built-in
+[`diagnostics_channel`](https://nodejs.org/api/diagnostics_channel.html) into
+autotel spans and events — no monkey-patching, no `import-in-the-middle`. Every
+entry point is opt-in and degrades to a no-op on runtimes (edge, old Node) that
+lack the underlying channels.
+
+**Capture `console.*` as correlated wide events** (the patch-free way to get
+`console.log` into your traces):
+
+```ts
+import { captureConsole } from 'autotel/diagnostics';
+
+const stop = captureConsole(); // every console.* → an OTel log record,
+// correlated to the active span by trace context
+```
+
+Each call becomes a log record (severity mapped from the method, printf-formatted
+body, `log.source`/`log.method` attributes). Pass `{ target: 'span-event' }` to
+add events to the active span instead, or `{ target: 'both' }`. Nothing patches
+the global `console`, so there's no load-order fragility.
+
+**Lightweight HTTP spans + W3C propagation** without `import-in-the-middle`:
+
+```ts
+import { instrumentHttp } from 'autotel/diagnostics';
+
+const stop = instrumentHttp(); // SERVER span per inbound request (parented to the
+// incoming traceparent) + CLIENT span per outbound
+// request (injects traceparent downstream)
+```
+
+This is an opt-in alternative to `@opentelemetry/instrumentation-http` for span
+coverage and propagation. Limitation: a plain channel can't wrap the request
+handler, so it does **not** set an ambient context for the handler's duration —
+application spans created inside a handler won't auto-nest under the SERVER span.
+Use `@opentelemetry/instrumentation-http` if you need that nesting.
+
+**Bridge any channel** with the shared primitive (also used by
+`autotel-genai`'s `ai:telemetry` subscriber):
+
+```ts
+import { subscribeChannel, subscribeTracingChannel } from 'autotel/diagnostics';
+
+const off = subscribeChannel('my-lib:event', (message) => {
+  /* turn message into a span/event */
+});
+```
+
 ## Auto Instrumentation & Advanced Configuration
 
 - `autoInstrumentations` : Enable OpenTelemetry auto-instrumentations (HTTP, Express, Fastify, Prisma, Pino…). Requires `@opentelemetry/auto-instrumentations-node`.

package/dist/diagnostics.cjs

@@ -0,0 +1,279 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_node_require = require('./node-require-CZ_PU448.cjs');
+let _opentelemetry_semantic_conventions = require("@opentelemetry/semantic-conventions");
+let _opentelemetry_api = require("@opentelemetry/api");
+let _opentelemetry_api_logs = require("@opentelemetry/api-logs");
+
+//#region src/diagnostics/channel.ts
+/**
+* Edge-safe wrappers over Node's `diagnostics_channel`.
+*
+* The module is loaded lazily through {@link safeRequire} — never a static
+* `node:` import — so merely importing this file is side-effect-free and bundles
+* cleanly for browser/edge targets, where every subscribe call degrades to a
+* no-op (returning an unsubscribe that does nothing). This is the shared
+* primitive behind autotel's diagnostics-channel integrations (console capture,
+* HTTP spans) and any app- or library-specific channel you want to bridge into
+* a span/event.
+*
+* `diagnostics_channel.subscribe` (Node 18.7+) and `tracingChannel` (Node 19+)
+* are used; autotel targets Node 22+, but on any runtime that lacks them the
+* loader returns `undefined` and the helpers no-op.
+*/
+let cached;
+function loadDiagnosticsChannel() {
+	if (cached !== void 0) return cached ?? void 0;
+	cached = require_node_require.safeRequire("node:diagnostics_channel") ?? null;
+	return cached ?? void 0;
+}
+/** Whether Node's `diagnostics_channel` is available in this runtime. */
+function diagnosticsChannelAvailable() {
+	return loadDiagnosticsChannel() !== void 0;
+}
+/**
+* Subscribe to a named diagnostics channel. Returns an idempotent unsubscribe
+* function; a no-op (that still returns a disposer) on unsupported runtimes.
+*/
+function subscribeChannel(name, handler) {
+	const dc = loadDiagnosticsChannel();
+	if (!dc?.subscribe) return () => {};
+	dc.subscribe(name, handler);
+	let active = true;
+	return () => {
+		if (!active) return;
+		active = false;
+		dc.unsubscribe?.(name, handler);
+	};
+}
+/**
+* Subscribe to a `tracingChannel` (the `tracing:${name}:{start,end,…}` set).
+* Returns an idempotent unsubscribe; a no-op on runtimes without
+* `tracingChannel` support.
+*/
+function subscribeTracingChannel(name, handlers) {
+	const channel = loadDiagnosticsChannel()?.tracingChannel?.(name);
+	if (!channel) return () => {};
+	channel.subscribe(handlers);
+	let active = true;
+	return () => {
+		if (!active) return;
+		active = false;
+		channel.unsubscribe(handlers);
+	};
+}
+
+//#endregion
+//#region src/diagnostics/console.ts
+/**
+* Capture `console.*` calls as wide events — without monkey-patching `console`.
+*
+* Node publishes every `console.log` / `info` / `debug` / `warn` / `error` call
+* on a built-in diagnostics channel. {@link captureConsole} subscribes to those
+* channels and turns each call into an OpenTelemetry **log record** (correlated
+* to the active span via trace context by the logs SDK) and/or a **span event**
+* on the active span. Nothing patches the global `console`, so there is no
+* load-order fragility and no interference with other tooling.
+*
+* Opt-in. Call once after `init()` and keep the returned disposer to stop:
+*
+* ```ts
+* import { captureConsole } from 'autotel/diagnostics';
+*
+* const stop = captureConsole();      // every console.* → correlated log record
+* // …later: stop();
+* ```
+*
+* The built-in `console.*` channels are a Stability-1 (experimental) Node API;
+* this module degrades to a no-op where they are unavailable.
+*/
+const ALL_LEVELS = [
+	"log",
+	"info",
+	"debug",
+	"warn",
+	"error"
+];
+const SEVERITY = {
+	debug: _opentelemetry_api_logs.SeverityNumber.DEBUG,
+	log: _opentelemetry_api_logs.SeverityNumber.INFO,
+	info: _opentelemetry_api_logs.SeverityNumber.INFO,
+	warn: _opentelemetry_api_logs.SeverityNumber.WARN,
+	error: _opentelemetry_api_logs.SeverityNumber.ERROR
+};
+const nodeUtil = require_node_require.safeRequire("node:util");
+/** Format console arguments the way `console` itself would (printf + inspect). */
+function formatArgs(args) {
+	if (nodeUtil?.format) return nodeUtil.format(...args);
+	return args.map((a) => typeof a === "string" ? a : safeStringify(a)).join(" ");
+}
+function safeStringify(value) {
+	try {
+		return JSON.stringify(value) ?? String(value);
+	} catch {
+		return String(value);
+	}
+}
+/**
+* Start capturing `console.*` calls as wide events. Returns a disposer that
+* stops capture. Safe to call on runtimes without the console channels (no-op).
+*/
+function captureConsole(options = {}) {
+	const levels = options.levels ?? ALL_LEVELS;
+	const target = options.target ?? "log";
+	const toLog = target === "log" || target === "both";
+	const toSpan = target === "span-event" || target === "both";
+	const logger = _opentelemetry_api_logs.logs.getLogger(options.loggerName ?? "autotel.console");
+	let recording = false;
+	const disposers = levels.map((level) => subscribeChannel(`console.${level}`, (message) => {
+		if (recording) return;
+		const body = formatArgs(message?.args ?? []);
+		recording = true;
+		try {
+			const attributes = {
+				"log.source": "console",
+				"log.method": level,
+				...options.attributes
+			};
+			if (toLog) logger.emit({
+				severityNumber: SEVERITY[level],
+				severityText: level.toUpperCase(),
+				body,
+				attributes
+			});
+			if (toSpan) _opentelemetry_api.trace.getActiveSpan()?.addEvent("log", {
+				"log.message": body,
+				...attributes
+			});
+		} finally {
+			recording = false;
+		}
+	}));
+	let active = true;
+	return () => {
+		if (!active) return;
+		active = false;
+		for (const dispose of disposers) dispose();
+	};
+}
+
+//#endregion
+//#region src/diagnostics/http.ts
+const SERVER_SPANS = /* @__PURE__ */ new WeakMap();
+const CLIENT_SPANS = /* @__PURE__ */ new WeakMap();
+function firstHeader(value) {
+	return Array.isArray(value) ? value[0] : value;
+}
+function splitHostPort(host) {
+	if (!host) return {};
+	const idx = host.lastIndexOf(":");
+	if (idx === -1) return { address: host };
+	const port = Number(host.slice(idx + 1));
+	return {
+		address: host.slice(0, idx),
+		port: Number.isFinite(port) ? port : void 0
+	};
+}
+/**
+* Start emitting HTTP server/client spans from Node's HTTP diagnostics
+* channels. Returns a disposer; a no-op on runtimes without the channels.
+*/
+function instrumentHttp(options = {}) {
+	const tracer = options.tracer ?? _opentelemetry_api.trace.getTracer("autotel.http-diagnostics");
+	const disposers = [];
+	if (options.server !== false) disposers.push(subscribeChannel("http.server.request.start", (message) => {
+		const request = message?.request;
+		if (!request) return;
+		const method = request.method ?? "HTTP";
+		const { address, port } = splitHostPort(firstHeader(request.headers.host));
+		const path = (request.url ?? "/").split("?", 1)[0];
+		const attributes = {
+			[_opentelemetry_semantic_conventions.ATTR_HTTP_REQUEST_METHOD]: method,
+			[_opentelemetry_semantic_conventions.ATTR_URL_PATH]: path,
+			[_opentelemetry_semantic_conventions.ATTR_URL_SCHEME]: "http",
+			[_opentelemetry_semantic_conventions.ATTR_NETWORK_PROTOCOL_VERSION]: request.httpVersion,
+			[_opentelemetry_semantic_conventions.ATTR_USER_AGENT_ORIGINAL]: firstHeader(request.headers["user-agent"]),
+			[_opentelemetry_semantic_conventions.ATTR_SERVER_ADDRESS]: address,
+			[_opentelemetry_semantic_conventions.ATTR_SERVER_PORT]: port
+		};
+		const parent = _opentelemetry_api.propagation.extract(_opentelemetry_api.context.active(), request.headers, _opentelemetry_api.defaultTextMapGetter);
+		const span = tracer.startSpan(method, {
+			kind: _opentelemetry_api.SpanKind.SERVER,
+			attributes
+		}, parent);
+		SERVER_SPANS.set(request, span);
+	}), subscribeChannel("http.server.response.finish", (message) => {
+		const { request, response } = message ?? {};
+		if (!request) return;
+		const span = SERVER_SPANS.get(request);
+		if (!span) return;
+		SERVER_SPANS.delete(request);
+		finishHttpSpan(span, response?.statusCode, 500);
+	}));
+	if (options.client !== false) disposers.push(subscribeChannel("http.client.request.start", (message) => {
+		const request = message?.request;
+		if (!request) return;
+		const method = request.method ?? "HTTP";
+		const req = request;
+		const { address, port } = splitHostPort(req.host);
+		const scheme = (req.protocol ?? "http:").replace(":", "");
+		const attributes = {
+			[_opentelemetry_semantic_conventions.ATTR_HTTP_REQUEST_METHOD]: method,
+			[_opentelemetry_semantic_conventions.ATTR_SERVER_ADDRESS]: address,
+			[_opentelemetry_semantic_conventions.ATTR_SERVER_PORT]: port,
+			[_opentelemetry_semantic_conventions.ATTR_URL_FULL]: address && req.path ? `${scheme}://${req.host}${req.path}` : void 0
+		};
+		const span = tracer.startSpan(method, {
+			kind: _opentelemetry_api.SpanKind.CLIENT,
+			attributes
+		});
+		CLIENT_SPANS.set(request, span);
+		if (!request.headersSent) {
+			const carrier = {};
+			_opentelemetry_api.propagation.inject(_opentelemetry_api.trace.setSpan(_opentelemetry_api.context.active(), span), carrier, _opentelemetry_api.defaultTextMapSetter);
+			for (const [key, value] of Object.entries(carrier)) try {
+				request.setHeader(key, value);
+			} catch {}
+		}
+	}), subscribeChannel("http.client.response.finish", (message) => {
+		const { request, response } = message ?? {};
+		if (!request) return;
+		const span = CLIENT_SPANS.get(request);
+		if (!span) return;
+		CLIENT_SPANS.delete(request);
+		finishHttpSpan(span, response?.statusCode, 400);
+	}), subscribeChannel("http.client.request.error", (message) => {
+		const { request, error } = message ?? {};
+		if (!request) return;
+		const span = CLIENT_SPANS.get(request);
+		if (!span) return;
+		CLIENT_SPANS.delete(request);
+		if (error instanceof Error) span.recordException(error);
+		span.setStatus({
+			code: _opentelemetry_api.SpanStatusCode.ERROR,
+			message: error instanceof Error ? error.message : void 0
+		});
+		span.end();
+	}));
+	let active = true;
+	return () => {
+		if (!active) return;
+		active = false;
+		for (const dispose of disposers) dispose();
+	};
+}
+/** Set status code + error status (when `>= errorAt`) and end the span. */
+function finishHttpSpan(span, statusCode, errorAt) {
+	if (statusCode !== void 0) {
+		span.setAttribute(_opentelemetry_semantic_conventions.ATTR_HTTP_RESPONSE_STATUS_CODE, statusCode);
+		if (statusCode >= errorAt) span.setStatus({ code: _opentelemetry_api.SpanStatusCode.ERROR });
+	}
+	span.end();
+}
+
+//#endregion
+exports.captureConsole = captureConsole;
+exports.diagnosticsChannelAvailable = diagnosticsChannelAvailable;
+exports.instrumentHttp = instrumentHttp;
+exports.subscribeChannel = subscribeChannel;
+exports.subscribeTracingChannel = subscribeTracingChannel;
+//# sourceMappingURL=diagnostics.cjs.map

package/dist/diagnostics.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.cjs","names":["safeRequire","SeverityNumber","safeRequire","logs","trace","ATTR_HTTP_REQUEST_METHOD","ATTR_URL_PATH","ATTR_URL_SCHEME","ATTR_NETWORK_PROTOCOL_VERSION","ATTR_USER_AGENT_ORIGINAL","ATTR_SERVER_ADDRESS","ATTR_SERVER_PORT","propagation","otelContext","defaultTextMapGetter","SpanKind","ATTR_URL_FULL","defaultTextMapSetter","SpanStatusCode","ATTR_HTTP_RESPONSE_STATUS_CODE"],"sources":["../src/diagnostics/channel.ts","../src/diagnostics/console.ts","../src/diagnostics/http.ts"],"sourcesContent":["/**\n * Edge-safe wrappers over Node's `diagnostics_channel`.\n *\n * The module is loaded lazily through {@link safeRequire} — never a static\n * `node:` import — so merely importing this file is side-effect-free and bundles\n * cleanly for browser/edge targets, where every subscribe call degrades to a\n * no-op (returning an unsubscribe that does nothing). This is the shared\n * primitive behind autotel's diagnostics-channel integrations (console capture,\n * HTTP spans) and any app- or library-specific channel you want to bridge into\n * a span/event.\n *\n * `diagnostics_channel.subscribe` (Node 18.7+) and `tracingChannel` (Node 19+)\n * are used; autotel targets Node 22+, but on any runtime that lacks them the\n * loader returns `undefined` and the helpers no-op.\n */\n\nimport { safeRequire } from '../node-require.js';\n\ntype DiagnosticsChannelModule = typeof import('node:diagnostics_channel');\n\nlet cached: DiagnosticsChannelModule | null | undefined;\n\nfunction loadDiagnosticsChannel(): DiagnosticsChannelModule | undefined {\n  if (cached !== undefined) return cached ?? undefined;\n  cached =\n    safeRequire<DiagnosticsChannelModule>('node:diagnostics_channel') ?? null;\n  return cached ?? undefined;\n}\n\n/** Whether Node's `diagnostics_channel` is available in this runtime. */\nexport function diagnosticsChannelAvailable(): boolean {\n  return loadDiagnosticsChannel() !== undefined;\n}\n\n/** Handler for a plain named channel. */\nexport type ChannelMessageHandler = (\n  message: unknown,\n  name: string | symbol,\n) => void;\n\n/**\n * Subscribe to a named diagnostics channel. Returns an idempotent unsubscribe\n * function; a no-op (that still returns a disposer) on unsupported runtimes.\n */\nexport function subscribeChannel(\n  name: string,\n  handler: ChannelMessageHandler,\n): () => void {\n  const dc = loadDiagnosticsChannel();\n  if (!dc?.subscribe) return () => {};\n  dc.subscribe(name, handler);\n  let active = true;\n  return () => {\n    if (!active) return;\n    active = false;\n    dc.unsubscribe?.(name, handler);\n  };\n}\n\n/** Subscriber set for a {@link https://nodejs.org/api/diagnostics_channel.html#class-tracingchannel TracingChannel}. */\nexport interface TracingChannelHandlers {\n  start?(message: unknown): void;\n  end?(message: unknown): void;\n  asyncStart?(message: unknown): void;\n  asyncEnd?(message: unknown): void;\n  error?(message: unknown): void;\n}\n\n/**\n * Subscribe to a `tracingChannel` (the `tracing:${name}:{start,end,…}` set).\n * Returns an idempotent unsubscribe; a no-op on runtimes without\n * `tracingChannel` support.\n */\nexport function subscribeTracingChannel(\n  name: string,\n  handlers: TracingChannelHandlers,\n): () => void {\n  const dc = loadDiagnosticsChannel();\n  const channel = dc?.tracingChannel?.(name);\n  if (!channel) return () => {};\n  // Node's typings want all five handlers; we pass the subset provided.\n  channel.subscribe(handlers as Parameters<typeof channel.subscribe>[0]);\n  let active = true;\n  return () => {\n    if (!active) return;\n    active = false;\n    channel.unsubscribe(handlers as Parameters<typeof channel.unsubscribe>[0]);\n  };\n}\n","/**\n * Capture `console.*` calls as wide events — without monkey-patching `console`.\n *\n * Node publishes every `console.log` / `info` / `debug` / `warn` / `error` call\n * on a built-in diagnostics channel. {@link captureConsole} subscribes to those\n * channels and turns each call into an OpenTelemetry **log record** (correlated\n * to the active span via trace context by the logs SDK) and/or a **span event**\n * on the active span. Nothing patches the global `console`, so there is no\n * load-order fragility and no interference with other tooling.\n *\n * Opt-in. Call once after `init()` and keep the returned disposer to stop:\n *\n * ```ts\n * import { captureConsole } from 'autotel/diagnostics';\n *\n * const stop = captureConsole();      // every console.* → correlated log record\n * // …later: stop();\n * ```\n *\n * The built-in `console.*` channels are a Stability-1 (experimental) Node API;\n * this module degrades to a no-op where they are unavailable.\n */\n\nimport { trace, type Attributes } from '@opentelemetry/api';\nimport { logs, SeverityNumber, type Logger } from '@opentelemetry/api-logs';\nimport { safeRequire } from '../node-require.js';\nimport { subscribeChannel } from './channel.js';\n\n/** Console methods that publish a diagnostics channel. */\nexport type ConsoleLevel = 'log' | 'info' | 'debug' | 'warn' | 'error';\n\nconst ALL_LEVELS: readonly ConsoleLevel[] = [\n  'log',\n  'info',\n  'debug',\n  'warn',\n  'error',\n];\n\nconst SEVERITY: Record<ConsoleLevel, SeverityNumber> = {\n  debug: SeverityNumber.DEBUG,\n  log: SeverityNumber.INFO,\n  info: SeverityNumber.INFO,\n  warn: SeverityNumber.WARN,\n  error: SeverityNumber.ERROR,\n};\n\nexport interface CaptureConsoleOptions {\n  /** Which console methods to capture. Defaults to all five. */\n  levels?: readonly ConsoleLevel[];\n  /**\n   * Where to record captured output:\n   * - `'log'` (default): emit an OpenTelemetry log record;\n   * - `'span-event'`: add an event to the active span (nothing if no active span);\n   * - `'both'`.\n   */\n  target?: 'log' | 'span-event' | 'both';\n  /** Logger name for emitted records. Defaults to `'autotel.console'`. */\n  loggerName?: string;\n  /** Static attributes merged onto every captured record/event. */\n  attributes?: Attributes;\n}\n\ntype ConsoleMessage = { args?: unknown[] };\n\nconst nodeUtil = safeRequire<typeof import('node:util')>('node:util');\n\n/** Format console arguments the way `console` itself would (printf + inspect). */\nfunction formatArgs(args: unknown[]): string {\n  if (nodeUtil?.format) return nodeUtil.format(...args);\n  return args\n    .map((a) => (typeof a === 'string' ? a : safeStringify(a)))\n    .join(' ');\n}\n\nfunction safeStringify(value: unknown): string {\n  try {\n    return JSON.stringify(value) ?? String(value);\n  } catch {\n    return String(value);\n  }\n}\n\n/**\n * Start capturing `console.*` calls as wide events. Returns a disposer that\n * stops capture. Safe to call on runtimes without the console channels (no-op).\n */\nexport function captureConsole(\n  options: CaptureConsoleOptions = {},\n): () => void {\n  const levels = options.levels ?? ALL_LEVELS;\n  const target = options.target ?? 'log';\n  const toLog = target === 'log' || target === 'both';\n  const toSpan = target === 'span-event' || target === 'both';\n  const logger: Logger = logs.getLogger(\n    options.loggerName ?? 'autotel.console',\n  );\n\n  // Guard against re-entrancy: if recording a captured call itself triggers a\n  // `console.*` (e.g. an exporter logging a warning), don't capture that.\n  let recording = false;\n\n  const disposers = levels.map((level) =>\n    subscribeChannel(`console.${level}`, (message) => {\n      if (recording) return;\n      const args = (message as ConsoleMessage)?.args ?? [];\n      const body = formatArgs(args as unknown[]);\n      recording = true;\n      try {\n        const attributes: Attributes = {\n          'log.source': 'console',\n          'log.method': level,\n          ...options.attributes,\n        };\n        if (toLog) {\n          logger.emit({\n            severityNumber: SEVERITY[level],\n            severityText: level.toUpperCase(),\n            body,\n            attributes,\n          });\n        }\n        if (toSpan) {\n          trace\n            .getActiveSpan()\n            ?.addEvent('log', { 'log.message': body, ...attributes });\n        }\n      } finally {\n        recording = false;\n      }\n    }),\n  );\n\n  let active = true;\n  return () => {\n    if (!active) return;\n    active = false;\n    for (const dispose of disposers) dispose();\n  };\n}\n","/**\n * Lightweight HTTP spans via Node's built-in `diagnostics_channel` — no\n * monkey-patching, no `import-in-the-middle`.\n *\n * Node publishes `http.server.request.start` / `http.server.response.finish`\n * and `http.client.request.start` / `http.client.response.finish` /\n * `http.client.request.error`. {@link instrumentHttp} subscribes to those and\n * emits a `SERVER` span per inbound request (parented to an incoming W3C\n * `traceparent`) and a `CLIENT` span per outbound request (whose context it\n * injects into the outgoing headers for downstream propagation).\n *\n * ```ts\n * import { instrumentHttp } from 'autotel/diagnostics';\n *\n * const stop = instrumentHttp();\n * ```\n *\n * Scope & limitation. This is an opt-in, low-overhead alternative to\n * `@opentelemetry/instrumentation-http` for HTTP span coverage + W3C\n * propagation. Client-side propagation works (the `traceparent` is injected on\n * the `ClientRequest` object directly). What it does **not** do is establish an\n * *ambient* OpenTelemetry context for the duration of a server request handler,\n * so application spans created inside a handler will not become children of the\n * `SERVER` span.\n *\n * This is structural, not a \"wait for a newer Node\" gap. Node publishes the\n * `http.*` channels with a plain `channel.publish()` — not `runStores` /\n * `tracingChannel` — so a subscriber has no scope to bind a store to. The only\n * ways to get handler nesting both defeat the purpose of using a channel:\n *   1. `AsyncLocalStorage.enterWith()` in the start handler — no scoped exit, so\n *      context leaks across requests sharing an event-loop tick / keep-alive\n *      connection and misattributes spans. Strictly worse than no nesting.\n *   2. Patching `http.Server.prototype.emit` to wrap the `'request'` listener in\n *      `context.with()` — monkey-patching, i.e. reimplementing\n *      `@opentelemetry/instrumentation-http`.\n * If you need handler nesting, use `@opentelemetry/instrumentation-http`.\n *\n * The `http.*` channels are a Stability-1 (experimental) Node API; this module\n * degrades to a no-op where they are unavailable.\n */\n\nimport type { ClientRequest, IncomingMessage, ServerResponse } from 'node:http';\nimport {\n  context as otelContext,\n  defaultTextMapGetter,\n  defaultTextMapSetter,\n  propagation,\n  SpanKind,\n  SpanStatusCode,\n  trace,\n  type Attributes,\n  type Span,\n  type Tracer,\n} from '@opentelemetry/api';\nimport {\n  ATTR_HTTP_REQUEST_METHOD,\n  ATTR_HTTP_RESPONSE_STATUS_CODE,\n  ATTR_NETWORK_PROTOCOL_VERSION,\n  ATTR_SERVER_ADDRESS,\n  ATTR_SERVER_PORT,\n  ATTR_URL_FULL,\n  ATTR_URL_PATH,\n  ATTR_URL_SCHEME,\n  ATTR_USER_AGENT_ORIGINAL,\n} from '@opentelemetry/semantic-conventions';\nimport { subscribeChannel } from './channel.js';\n\nexport interface InstrumentHttpOptions {\n  /** Instrument inbound (server) requests. Default `true`. */\n  server?: boolean;\n  /** Instrument outbound (client) requests. Default `true`. */\n  client?: boolean;\n  /** Tracer to use. Defaults to `trace.getTracer('autotel.http-diagnostics')`. */\n  tracer?: Tracer;\n}\n\ninterface ServerStartMessage {\n  request?: IncomingMessage;\n  response?: ServerResponse;\n}\ninterface ServerFinishMessage {\n  request?: IncomingMessage;\n  response?: ServerResponse;\n}\ninterface ClientStartMessage {\n  request?: ClientRequest;\n}\ninterface ClientFinishMessage {\n  request?: ClientRequest;\n  response?: IncomingMessage;\n}\ninterface ClientErrorMessage {\n  request?: ClientRequest;\n  error?: unknown;\n}\n\nconst SERVER_SPANS = new WeakMap<object, Span>();\nconst CLIENT_SPANS = new WeakMap<object, Span>();\n\nfunction firstHeader(value: string | string[] | undefined): string | undefined {\n  return Array.isArray(value) ? value[0] : value;\n}\n\nfunction splitHostPort(host: string | undefined): {\n  address?: string;\n  port?: number;\n} {\n  if (!host) return {};\n  const idx = host.lastIndexOf(':');\n  if (idx === -1) return { address: host };\n  const port = Number(host.slice(idx + 1));\n  return {\n    address: host.slice(0, idx),\n    port: Number.isFinite(port) ? port : undefined,\n  };\n}\n\n/**\n * Start emitting HTTP server/client spans from Node's HTTP diagnostics\n * channels. Returns a disposer; a no-op on runtimes without the channels.\n */\nexport function instrumentHttp(\n  options: InstrumentHttpOptions = {},\n): () => void {\n  const tracer = options.tracer ?? trace.getTracer('autotel.http-diagnostics');\n  const disposers: Array<() => void> = [];\n\n  if (options.server !== false) {\n    disposers.push(\n      subscribeChannel('http.server.request.start', (message) => {\n        const request = (message as ServerStartMessage)?.request;\n        if (!request) return;\n        const method = request.method ?? 'HTTP';\n        const host = firstHeader(request.headers.host);\n        const { address, port } = splitHostPort(host);\n        const path = (request.url ?? '/').split('?', 1)[0];\n        const attributes: Attributes = {\n          [ATTR_HTTP_REQUEST_METHOD]: method,\n          [ATTR_URL_PATH]: path,\n          [ATTR_URL_SCHEME]: 'http',\n          [ATTR_NETWORK_PROTOCOL_VERSION]: request.httpVersion,\n          [ATTR_USER_AGENT_ORIGINAL]: firstHeader(\n            request.headers['user-agent'],\n          ),\n          [ATTR_SERVER_ADDRESS]: address,\n          [ATTR_SERVER_PORT]: port,\n        };\n        const parent = propagation.extract(\n          otelContext.active(),\n          request.headers,\n          defaultTextMapGetter,\n        );\n        const span = tracer.startSpan(\n          method,\n          { kind: SpanKind.SERVER, attributes },\n          parent,\n        );\n        SERVER_SPANS.set(request, span);\n      }),\n      subscribeChannel('http.server.response.finish', (message) => {\n        const { request, response } = (message as ServerFinishMessage) ?? {};\n        if (!request) return;\n        const span = SERVER_SPANS.get(request);\n        if (!span) return;\n        SERVER_SPANS.delete(request);\n        finishHttpSpan(span, response?.statusCode, 500);\n      }),\n    );\n  }\n\n  if (options.client !== false) {\n    disposers.push(\n      subscribeChannel('http.client.request.start', (message) => {\n        const request = (message as ClientStartMessage)?.request;\n        if (!request) return;\n        const method = request.method ?? 'HTTP';\n        // `ClientRequest` exposes host/protocol/path on the public surface.\n        const req = request as ClientRequest & {\n          host?: string;\n          protocol?: string;\n          path?: string;\n        };\n        const { address, port } = splitHostPort(req.host);\n        const scheme = (req.protocol ?? 'http:').replace(':', '');\n        const attributes: Attributes = {\n          [ATTR_HTTP_REQUEST_METHOD]: method,\n          [ATTR_SERVER_ADDRESS]: address,\n          [ATTR_SERVER_PORT]: port,\n          [ATTR_URL_FULL]:\n            address && req.path\n              ? `${scheme}://${req.host}${req.path}`\n              : undefined,\n        };\n        const span = tracer.startSpan(method, {\n          kind: SpanKind.CLIENT,\n          attributes,\n        });\n        CLIENT_SPANS.set(request, span);\n\n        // Inject this span's context into the outbound headers so the\n        // downstream service continues the trace.\n        if (!request.headersSent) {\n          const carrier: Record<string, string> = {};\n          propagation.inject(\n            trace.setSpan(otelContext.active(), span),\n            carrier,\n            defaultTextMapSetter,\n          );\n          for (const [key, value] of Object.entries(carrier)) {\n            try {\n              request.setHeader(key, value);\n            } catch {\n              // Headers already sent / immutable — propagation best-effort.\n            }\n          }\n        }\n      }),\n      subscribeChannel('http.client.response.finish', (message) => {\n        const { request, response } = (message as ClientFinishMessage) ?? {};\n        if (!request) return;\n        const span = CLIENT_SPANS.get(request);\n        if (!span) return;\n        CLIENT_SPANS.delete(request);\n        finishHttpSpan(span, response?.statusCode, 400);\n      }),\n      subscribeChannel('http.client.request.error', (message) => {\n        const { request, error } = (message as ClientErrorMessage) ?? {};\n        if (!request) return;\n        const span = CLIENT_SPANS.get(request);\n        if (!span) return;\n        CLIENT_SPANS.delete(request);\n        if (error instanceof Error) span.recordException(error);\n        span.setStatus({\n          code: SpanStatusCode.ERROR,\n          message: error instanceof Error ? error.message : undefined,\n        });\n        span.end();\n      }),\n    );\n  }\n\n  let active = true;\n  return () => {\n    if (!active) return;\n    active = false;\n    for (const dispose of disposers) dispose();\n  };\n}\n\n/** Set status code + error status (when `>= errorAt`) and end the span. */\nfunction finishHttpSpan(\n  span: Span,\n  statusCode: number | undefined,\n  errorAt: number,\n): void {\n  if (statusCode !== undefined) {\n    span.setAttribute(ATTR_HTTP_RESPONSE_STATUS_CODE, statusCode);\n    if (statusCode >= errorAt) {\n      span.setStatus({ code: SpanStatusCode.ERROR });\n    }\n  }\n  span.end();\n}\n"],"mappings":"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"}

package/dist/diagnostics.d.cts

@@ -0,0 +1,83 @@
+import { Attributes, Tracer } from "@opentelemetry/api";
+
+//#region src/diagnostics/channel.d.ts
+/**
+ * Edge-safe wrappers over Node's `diagnostics_channel`.
+ *
+ * The module is loaded lazily through {@link safeRequire} — never a static
+ * `node:` import — so merely importing this file is side-effect-free and bundles
+ * cleanly for browser/edge targets, where every subscribe call degrades to a
+ * no-op (returning an unsubscribe that does nothing). This is the shared
+ * primitive behind autotel's diagnostics-channel integrations (console capture,
+ * HTTP spans) and any app- or library-specific channel you want to bridge into
+ * a span/event.
+ *
+ * `diagnostics_channel.subscribe` (Node 18.7+) and `tracingChannel` (Node 19+)
+ * are used; autotel targets Node 22+, but on any runtime that lacks them the
+ * loader returns `undefined` and the helpers no-op.
+ */
+/** Whether Node's `diagnostics_channel` is available in this runtime. */
+declare function diagnosticsChannelAvailable(): boolean;
+/** Handler for a plain named channel. */
+type ChannelMessageHandler = (message: unknown, name: string | symbol) => void;
+/**
+ * Subscribe to a named diagnostics channel. Returns an idempotent unsubscribe
+ * function; a no-op (that still returns a disposer) on unsupported runtimes.
+ */
+declare function subscribeChannel(name: string, handler: ChannelMessageHandler): () => void;
+/** Subscriber set for a {@link https://nodejs.org/api/diagnostics_channel.html#class-tracingchannel TracingChannel}. */
+interface TracingChannelHandlers {
+  start?(message: unknown): void;
+  end?(message: unknown): void;
+  asyncStart?(message: unknown): void;
+  asyncEnd?(message: unknown): void;
+  error?(message: unknown): void;
+}
+/**
+ * Subscribe to a `tracingChannel` (the `tracing:${name}:{start,end,…}` set).
+ * Returns an idempotent unsubscribe; a no-op on runtimes without
+ * `tracingChannel` support.
+ */
+declare function subscribeTracingChannel(name: string, handlers: TracingChannelHandlers): () => void;
+//#endregion
+//#region src/diagnostics/console.d.ts
+/** Console methods that publish a diagnostics channel. */
+type ConsoleLevel = 'log' | 'info' | 'debug' | 'warn' | 'error';
+interface CaptureConsoleOptions {
+  /** Which console methods to capture. Defaults to all five. */
+  levels?: readonly ConsoleLevel[];
+  /**
+   * Where to record captured output:
+   * - `'log'` (default): emit an OpenTelemetry log record;
+   * - `'span-event'`: add an event to the active span (nothing if no active span);
+   * - `'both'`.
+   */
+  target?: 'log' | 'span-event' | 'both';
+  /** Logger name for emitted records. Defaults to `'autotel.console'`. */
+  loggerName?: string;
+  /** Static attributes merged onto every captured record/event. */
+  attributes?: Attributes;
+}
+/**
+ * Start capturing `console.*` calls as wide events. Returns a disposer that
+ * stops capture. Safe to call on runtimes without the console channels (no-op).
+ */
+declare function captureConsole(options?: CaptureConsoleOptions): () => void;
+//#endregion
+//#region src/diagnostics/http.d.ts
+interface InstrumentHttpOptions {
+  /** Instrument inbound (server) requests. Default `true`. */
+  server?: boolean;
+  /** Instrument outbound (client) requests. Default `true`. */
+  client?: boolean;
+  /** Tracer to use. Defaults to `trace.getTracer('autotel.http-diagnostics')`. */
+  tracer?: Tracer;
+}
+/**
+ * Start emitting HTTP server/client spans from Node's HTTP diagnostics
+ * channels. Returns a disposer; a no-op on runtimes without the channels.
+ */
+declare function instrumentHttp(options?: InstrumentHttpOptions): () => void;
+//#endregion
+export { type CaptureConsoleOptions, type ChannelMessageHandler, type ConsoleLevel, type InstrumentHttpOptions, type TracingChannelHandlers, captureConsole, diagnosticsChannelAvailable, instrumentHttp, subscribeChannel, subscribeTracingChannel };
+//# sourceMappingURL=diagnostics.d.cts.map

package/dist/diagnostics.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.cts","names":[],"sources":["../src/diagnostics/channel.ts","../src/diagnostics/console.ts","../src/diagnostics/http.ts"],"mappings":";;;;;;AA8BA;;;;AAA2C;AAK3C;;;;AAEuB;AAOvB;;;iBAdgB,2BAAA;;KAKJ,qBAAA,IACV,OAAA,WACA,IAAqB;;;AASS;AAchC;iBAhBgB,gBAAA,CACd,IAAA,UACA,OAAA,EAAS,qBAAqB;;UAcf,sBAAA;EACf,KAAA,EAAO,OAAA;EACP,GAAA,EAAK,OAAA;EACL,UAAA,EAAY,OAAA;EACZ,QAAA,EAAU,OAAA;EACV,KAAA,EAAO,OAAA;AAAA;;;;;;iBAQO,uBAAA,CACd,IAAA,UACA,QAAA,EAAU,sBAAsB;;;;KC9CtB,YAAA;AAAA,UAkBK,qBAAA;EDcf;ECZA,MAAA,YAAkB,YAAA;EDalB;;;;;;ECNA,MAAA;EDSO;ECPP,UAAA;EDOuB;ECLvB,UAAA,GAAa,UAAU;AAAA;;;;;iBA2BT,cAAA,CACd,OAAmC,GAA1B,qBAA0B;;;UCrBpB,qBAAA;EFOf;EELA,MAAA;EFMA;EEJA,MAAA;EFIgC;EEFhC,MAAA,GAAS,MAAM;AAAA;;AD5CjB;;;iBC4FgB,cAAA,CACd,OAAmC,GAA1B,qBAA0B"}

package/dist/diagnostics.d.ts

@@ -0,0 +1,83 @@
+import { Attributes, Tracer } from "@opentelemetry/api";
+
+//#region src/diagnostics/channel.d.ts
+/**
+ * Edge-safe wrappers over Node's `diagnostics_channel`.
+ *
+ * The module is loaded lazily through {@link safeRequire} — never a static
+ * `node:` import — so merely importing this file is side-effect-free and bundles
+ * cleanly for browser/edge targets, where every subscribe call degrades to a
+ * no-op (returning an unsubscribe that does nothing). This is the shared
+ * primitive behind autotel's diagnostics-channel integrations (console capture,
+ * HTTP spans) and any app- or library-specific channel you want to bridge into
+ * a span/event.
+ *
+ * `diagnostics_channel.subscribe` (Node 18.7+) and `tracingChannel` (Node 19+)
+ * are used; autotel targets Node 22+, but on any runtime that lacks them the
+ * loader returns `undefined` and the helpers no-op.
+ */
+/** Whether Node's `diagnostics_channel` is available in this runtime. */
+declare function diagnosticsChannelAvailable(): boolean;
+/** Handler for a plain named channel. */
+type ChannelMessageHandler = (message: unknown, name: string | symbol) => void;
+/**
+ * Subscribe to a named diagnostics channel. Returns an idempotent unsubscribe
+ * function; a no-op (that still returns a disposer) on unsupported runtimes.
+ */
+declare function subscribeChannel(name: string, handler: ChannelMessageHandler): () => void;
+/** Subscriber set for a {@link https://nodejs.org/api/diagnostics_channel.html#class-tracingchannel TracingChannel}. */
+interface TracingChannelHandlers {
+  start?(message: unknown): void;
+  end?(message: unknown): void;
+  asyncStart?(message: unknown): void;
+  asyncEnd?(message: unknown): void;
+  error?(message: unknown): void;
+}
+/**
+ * Subscribe to a `tracingChannel` (the `tracing:${name}:{start,end,…}` set).
+ * Returns an idempotent unsubscribe; a no-op on runtimes without
+ * `tracingChannel` support.
+ */
+declare function subscribeTracingChannel(name: string, handlers: TracingChannelHandlers): () => void;
+//#endregion
+//#region src/diagnostics/console.d.ts
+/** Console methods that publish a diagnostics channel. */
+type ConsoleLevel = 'log' | 'info' | 'debug' | 'warn' | 'error';
+interface CaptureConsoleOptions {
+  /** Which console methods to capture. Defaults to all five. */
+  levels?: readonly ConsoleLevel[];
+  /**
+   * Where to record captured output:
+   * - `'log'` (default): emit an OpenTelemetry log record;
+   * - `'span-event'`: add an event to the active span (nothing if no active span);
+   * - `'both'`.
+   */
+  target?: 'log' | 'span-event' | 'both';
+  /** Logger name for emitted records. Defaults to `'autotel.console'`. */
+  loggerName?: string;
+  /** Static attributes merged onto every captured record/event. */
+  attributes?: Attributes;
+}
+/**
+ * Start capturing `console.*` calls as wide events. Returns a disposer that
+ * stops capture. Safe to call on runtimes without the console channels (no-op).
+ */
+declare function captureConsole(options?: CaptureConsoleOptions): () => void;
+//#endregion
+//#region src/diagnostics/http.d.ts
+interface InstrumentHttpOptions {
+  /** Instrument inbound (server) requests. Default `true`. */
+  server?: boolean;
+  /** Instrument outbound (client) requests. Default `true`. */
+  client?: boolean;
+  /** Tracer to use. Defaults to `trace.getTracer('autotel.http-diagnostics')`. */
+  tracer?: Tracer;
+}
+/**
+ * Start emitting HTTP server/client spans from Node's HTTP diagnostics
+ * channels. Returns a disposer; a no-op on runtimes without the channels.
+ */
+declare function instrumentHttp(options?: InstrumentHttpOptions): () => void;
+//#endregion
+export { type CaptureConsoleOptions, type ChannelMessageHandler, type ConsoleLevel, type InstrumentHttpOptions, type TracingChannelHandlers, captureConsole, diagnosticsChannelAvailable, instrumentHttp, subscribeChannel, subscribeTracingChannel };
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","names":[],"sources":["../src/diagnostics/channel.ts","../src/diagnostics/console.ts","../src/diagnostics/http.ts"],"mappings":";;;;;;AA8BA;;;;AAA2C;AAK3C;;;;AAEuB;AAOvB;;;iBAdgB,2BAAA;;KAKJ,qBAAA,IACV,OAAA,WACA,IAAqB;;;AASS;AAchC;iBAhBgB,gBAAA,CACd,IAAA,UACA,OAAA,EAAS,qBAAqB;;UAcf,sBAAA;EACf,KAAA,EAAO,OAAA;EACP,GAAA,EAAK,OAAA;EACL,UAAA,EAAY,OAAA;EACZ,QAAA,EAAU,OAAA;EACV,KAAA,EAAO,OAAA;AAAA;;;;;;iBAQO,uBAAA,CACd,IAAA,UACA,QAAA,EAAU,sBAAsB;;;;KC9CtB,YAAA;AAAA,UAkBK,qBAAA;EDcf;ECZA,MAAA,YAAkB,YAAA;EDalB;;;;;;ECNA,MAAA;EDSO;ECPP,UAAA;EDOuB;ECLvB,UAAA,GAAa,UAAU;AAAA;;;;;iBA2BT,cAAA,CACd,OAAmC,GAA1B,qBAA0B;;;UCrBpB,qBAAA;EFOf;EELA,MAAA;EFMA;EEJA,MAAA;EFIgC;EEFhC,MAAA,GAAS,MAAM;AAAA;;AD5CjB;;;iBC4FgB,cAAA,CACd,OAAmC,GAA1B,qBAA0B"}

package/dist/diagnostics.js

@@ -0,0 +1,274 @@
+import { n as safeRequire } from "./node-require-vROmTeJ8.js";
+import { ATTR_HTTP_REQUEST_METHOD, ATTR_HTTP_RESPONSE_STATUS_CODE, ATTR_NETWORK_PROTOCOL_VERSION, ATTR_SERVER_ADDRESS, ATTR_SERVER_PORT, ATTR_URL_FULL, ATTR_URL_PATH, ATTR_URL_SCHEME, ATTR_USER_AGENT_ORIGINAL } from "@opentelemetry/semantic-conventions";
+import { SpanKind, SpanStatusCode, context, defaultTextMapGetter, defaultTextMapSetter, propagation, trace } from "@opentelemetry/api";
+import { SeverityNumber, logs } from "@opentelemetry/api-logs";
+
+//#region src/diagnostics/channel.ts
+/**
+* Edge-safe wrappers over Node's `diagnostics_channel`.
+*
+* The module is loaded lazily through {@link safeRequire} — never a static
+* `node:` import — so merely importing this file is side-effect-free and bundles
+* cleanly for browser/edge targets, where every subscribe call degrades to a
+* no-op (returning an unsubscribe that does nothing). This is the shared
+* primitive behind autotel's diagnostics-channel integrations (console capture,
+* HTTP spans) and any app- or library-specific channel you want to bridge into
+* a span/event.
+*
+* `diagnostics_channel.subscribe` (Node 18.7+) and `tracingChannel` (Node 19+)
+* are used; autotel targets Node 22+, but on any runtime that lacks them the
+* loader returns `undefined` and the helpers no-op.
+*/
+let cached;
+function loadDiagnosticsChannel() {
+	if (cached !== void 0) return cached ?? void 0;
+	cached = safeRequire("node:diagnostics_channel") ?? null;
+	return cached ?? void 0;
+}
+/** Whether Node's `diagnostics_channel` is available in this runtime. */
+function diagnosticsChannelAvailable() {
+	return loadDiagnosticsChannel() !== void 0;
+}
+/**
+* Subscribe to a named diagnostics channel. Returns an idempotent unsubscribe
+* function; a no-op (that still returns a disposer) on unsupported runtimes.
+*/
+function subscribeChannel(name, handler) {
+	const dc = loadDiagnosticsChannel();
+	if (!dc?.subscribe) return () => {};
+	dc.subscribe(name, handler);
+	let active = true;
+	return () => {
+		if (!active) return;
+		active = false;
+		dc.unsubscribe?.(name, handler);
+	};
+}
+/**
+* Subscribe to a `tracingChannel` (the `tracing:${name}:{start,end,…}` set).
+* Returns an idempotent unsubscribe; a no-op on runtimes without
+* `tracingChannel` support.
+*/
+function subscribeTracingChannel(name, handlers) {
+	const channel = loadDiagnosticsChannel()?.tracingChannel?.(name);
+	if (!channel) return () => {};
+	channel.subscribe(handlers);
+	let active = true;
+	return () => {
+		if (!active) return;
+		active = false;
+		channel.unsubscribe(handlers);
+	};
+}
+
+//#endregion
+//#region src/diagnostics/console.ts
+/**
+* Capture `console.*` calls as wide events — without monkey-patching `console`.
+*
+* Node publishes every `console.log` / `info` / `debug` / `warn` / `error` call
+* on a built-in diagnostics channel. {@link captureConsole} subscribes to those
+* channels and turns each call into an OpenTelemetry **log record** (correlated
+* to the active span via trace context by the logs SDK) and/or a **span event**
+* on the active span. Nothing patches the global `console`, so there is no
+* load-order fragility and no interference with other tooling.
+*
+* Opt-in. Call once after `init()` and keep the returned disposer to stop:
+*
+* ```ts
+* import { captureConsole } from 'autotel/diagnostics';
+*
+* const stop = captureConsole();      // every console.* → correlated log record
+* // …later: stop();
+* ```
+*
+* The built-in `console.*` channels are a Stability-1 (experimental) Node API;
+* this module degrades to a no-op where they are unavailable.
+*/
+const ALL_LEVELS = [
+	"log",
+	"info",
+	"debug",
+	"warn",
+	"error"
+];
+const SEVERITY = {
+	debug: SeverityNumber.DEBUG,
+	log: SeverityNumber.INFO,
+	info: SeverityNumber.INFO,
+	warn: SeverityNumber.WARN,
+	error: SeverityNumber.ERROR
+};
+const nodeUtil = safeRequire("node:util");
+/** Format console arguments the way `console` itself would (printf + inspect). */
+function formatArgs(args) {
+	if (nodeUtil?.format) return nodeUtil.format(...args);
+	return args.map((a) => typeof a === "string" ? a : safeStringify(a)).join(" ");
+}
+function safeStringify(value) {
+	try {
+		return JSON.stringify(value) ?? String(value);
+	} catch {
+		return String(value);
+	}
+}
+/**
+* Start capturing `console.*` calls as wide events. Returns a disposer that
+* stops capture. Safe to call on runtimes without the console channels (no-op).
+*/
+function captureConsole(options = {}) {
+	const levels = options.levels ?? ALL_LEVELS;
+	const target = options.target ?? "log";
+	const toLog = target === "log" || target === "both";
+	const toSpan = target === "span-event" || target === "both";
+	const logger = logs.getLogger(options.loggerName ?? "autotel.console");
+	let recording = false;
+	const disposers = levels.map((level) => subscribeChannel(`console.${level}`, (message) => {
+		if (recording) return;
+		const body = formatArgs(message?.args ?? []);
+		recording = true;
+		try {
+			const attributes = {
+				"log.source": "console",
+				"log.method": level,
+				...options.attributes
+			};
+			if (toLog) logger.emit({
+				severityNumber: SEVERITY[level],
+				severityText: level.toUpperCase(),
+				body,
+				attributes
+			});
+			if (toSpan) trace.getActiveSpan()?.addEvent("log", {
+				"log.message": body,
+				...attributes
+			});
+		} finally {
+			recording = false;
+		}
+	}));
+	let active = true;
+	return () => {
+		if (!active) return;
+		active = false;
+		for (const dispose of disposers) dispose();
+	};
+}
+
+//#endregion
+//#region src/diagnostics/http.ts
+const SERVER_SPANS = /* @__PURE__ */ new WeakMap();
+const CLIENT_SPANS = /* @__PURE__ */ new WeakMap();
+function firstHeader(value) {
+	return Array.isArray(value) ? value[0] : value;
+}
+function splitHostPort(host) {
+	if (!host) return {};
+	const idx = host.lastIndexOf(":");
+	if (idx === -1) return { address: host };
+	const port = Number(host.slice(idx + 1));
+	return {
+		address: host.slice(0, idx),
+		port: Number.isFinite(port) ? port : void 0
+	};
+}
+/**
+* Start emitting HTTP server/client spans from Node's HTTP diagnostics
+* channels. Returns a disposer; a no-op on runtimes without the channels.
+*/
+function instrumentHttp(options = {}) {
+	const tracer = options.tracer ?? trace.getTracer("autotel.http-diagnostics");
+	const disposers = [];
+	if (options.server !== false) disposers.push(subscribeChannel("http.server.request.start", (message) => {
+		const request = message?.request;
+		if (!request) return;
+		const method = request.method ?? "HTTP";
+		const { address, port } = splitHostPort(firstHeader(request.headers.host));
+		const path = (request.url ?? "/").split("?", 1)[0];
+		const attributes = {
+			[ATTR_HTTP_REQUEST_METHOD]: method,
+			[ATTR_URL_PATH]: path,
+			[ATTR_URL_SCHEME]: "http",
+			[ATTR_NETWORK_PROTOCOL_VERSION]: request.httpVersion,
+			[ATTR_USER_AGENT_ORIGINAL]: firstHeader(request.headers["user-agent"]),
+			[ATTR_SERVER_ADDRESS]: address,
+			[ATTR_SERVER_PORT]: port
+		};
+		const parent = propagation.extract(context.active(), request.headers, defaultTextMapGetter);
+		const span = tracer.startSpan(method, {
+			kind: SpanKind.SERVER,
+			attributes
+		}, parent);
+		SERVER_SPANS.set(request, span);
+	}), subscribeChannel("http.server.response.finish", (message) => {
+		const { request, response } = message ?? {};
+		if (!request) return;
+		const span = SERVER_SPANS.get(request);
+		if (!span) return;
+		SERVER_SPANS.delete(request);
+		finishHttpSpan(span, response?.statusCode, 500);
+	}));
+	if (options.client !== false) disposers.push(subscribeChannel("http.client.request.start", (message) => {
+		const request = message?.request;
+		if (!request) return;
+		const method = request.method ?? "HTTP";
+		const req = request;
+		const { address, port } = splitHostPort(req.host);
+		const scheme = (req.protocol ?? "http:").replace(":", "");
+		const attributes = {
+			[ATTR_HTTP_REQUEST_METHOD]: method,
+			[ATTR_SERVER_ADDRESS]: address,
+			[ATTR_SERVER_PORT]: port,
+			[ATTR_URL_FULL]: address && req.path ? `${scheme}://${req.host}${req.path}` : void 0
+		};
+		const span = tracer.startSpan(method, {
+			kind: SpanKind.CLIENT,
+			attributes
+		});
+		CLIENT_SPANS.set(request, span);
+		if (!request.headersSent) {
+			const carrier = {};
+			propagation.inject(trace.setSpan(context.active(), span), carrier, defaultTextMapSetter);
+			for (const [key, value] of Object.entries(carrier)) try {
+				request.setHeader(key, value);
+			} catch {}
+		}
+	}), subscribeChannel("http.client.response.finish", (message) => {
+		const { request, response } = message ?? {};
+		if (!request) return;
+		const span = CLIENT_SPANS.get(request);
+		if (!span) return;
+		CLIENT_SPANS.delete(request);
+		finishHttpSpan(span, response?.statusCode, 400);
+	}), subscribeChannel("http.client.request.error", (message) => {
+		const { request, error } = message ?? {};
+		if (!request) return;
+		const span = CLIENT_SPANS.get(request);
+		if (!span) return;
+		CLIENT_SPANS.delete(request);
+		if (error instanceof Error) span.recordException(error);
+		span.setStatus({
+			code: SpanStatusCode.ERROR,
+			message: error instanceof Error ? error.message : void 0
+		});
+		span.end();
+	}));
+	let active = true;
+	return () => {
+		if (!active) return;
+		active = false;
+		for (const dispose of disposers) dispose();
+	};
+}
+/** Set status code + error status (when `>= errorAt`) and end the span. */
+function finishHttpSpan(span, statusCode, errorAt) {
+	if (statusCode !== void 0) {
+		span.setAttribute(ATTR_HTTP_RESPONSE_STATUS_CODE, statusCode);
+		if (statusCode >= errorAt) span.setStatus({ code: SpanStatusCode.ERROR });
+	}
+	span.end();
+}
+
+//#endregion
+export { captureConsole, diagnosticsChannelAvailable, instrumentHttp, subscribeChannel, subscribeTracingChannel };
+//# sourceMappingURL=diagnostics.js.map

package/dist/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","names":["otelContext"],"sources":["../src/diagnostics/channel.ts","../src/diagnostics/console.ts","../src/diagnostics/http.ts"],"sourcesContent":["/**\n * Edge-safe wrappers over Node's `diagnostics_channel`.\n *\n * The module is loaded lazily through {@link safeRequire} — never a static\n * `node:` import — so merely importing this file is side-effect-free and bundles\n * cleanly for browser/edge targets, where every subscribe call degrades to a\n * no-op (returning an unsubscribe that does nothing). This is the shared\n * primitive behind autotel's diagnostics-channel integrations (console capture,\n * HTTP spans) and any app- or library-specific channel you want to bridge into\n * a span/event.\n *\n * `diagnostics_channel.subscribe` (Node 18.7+) and `tracingChannel` (Node 19+)\n * are used; autotel targets Node 22+, but on any runtime that lacks them the\n * loader returns `undefined` and the helpers no-op.\n */\n\nimport { safeRequire } from '../node-require.js';\n\ntype DiagnosticsChannelModule = typeof import('node:diagnostics_channel');\n\nlet cached: DiagnosticsChannelModule | null | undefined;\n\nfunction loadDiagnosticsChannel(): DiagnosticsChannelModule | undefined {\n  if (cached !== undefined) return cached ?? undefined;\n  cached =\n    safeRequire<DiagnosticsChannelModule>('node:diagnostics_channel') ?? null;\n  return cached ?? undefined;\n}\n\n/** Whether Node's `diagnostics_channel` is available in this runtime. */\nexport function diagnosticsChannelAvailable(): boolean {\n  return loadDiagnosticsChannel() !== undefined;\n}\n\n/** Handler for a plain named channel. */\nexport type ChannelMessageHandler = (\n  message: unknown,\n  name: string | symbol,\n) => void;\n\n/**\n * Subscribe to a named diagnostics channel. Returns an idempotent unsubscribe\n * function; a no-op (that still returns a disposer) on unsupported runtimes.\n */\nexport function subscribeChannel(\n  name: string,\n  handler: ChannelMessageHandler,\n): () => void {\n  const dc = loadDiagnosticsChannel();\n  if (!dc?.subscribe) return () => {};\n  dc.subscribe(name, handler);\n  let active = true;\n  return () => {\n    if (!active) return;\n    active = false;\n    dc.unsubscribe?.(name, handler);\n  };\n}\n\n/** Subscriber set for a {@link https://nodejs.org/api/diagnostics_channel.html#class-tracingchannel TracingChannel}. */\nexport interface TracingChannelHandlers {\n  start?(message: unknown): void;\n  end?(message: unknown): void;\n  asyncStart?(message: unknown): void;\n  asyncEnd?(message: unknown): void;\n  error?(message: unknown): void;\n}\n\n/**\n * Subscribe to a `tracingChannel` (the `tracing:${name}:{start,end,…}` set).\n * Returns an idempotent unsubscribe; a no-op on runtimes without\n * `tracingChannel` support.\n */\nexport function subscribeTracingChannel(\n  name: string,\n  handlers: TracingChannelHandlers,\n): () => void {\n  const dc = loadDiagnosticsChannel();\n  const channel = dc?.tracingChannel?.(name);\n  if (!channel) return () => {};\n  // Node's typings want all five handlers; we pass the subset provided.\n  channel.subscribe(handlers as Parameters<typeof channel.subscribe>[0]);\n  let active = true;\n  return () => {\n    if (!active) return;\n    active = false;\n    channel.unsubscribe(handlers as Parameters<typeof channel.unsubscribe>[0]);\n  };\n}\n","/**\n * Capture `console.*` calls as wide events — without monkey-patching `console`.\n *\n * Node publishes every `console.log` / `info` / `debug` / `warn` / `error` call\n * on a built-in diagnostics channel. {@link captureConsole} subscribes to those\n * channels and turns each call into an OpenTelemetry **log record** (correlated\n * to the active span via trace context by the logs SDK) and/or a **span event**\n * on the active span. Nothing patches the global `console`, so there is no\n * load-order fragility and no interference with other tooling.\n *\n * Opt-in. Call once after `init()` and keep the returned disposer to stop:\n *\n * ```ts\n * import { captureConsole } from 'autotel/diagnostics';\n *\n * const stop = captureConsole();      // every console.* → correlated log record\n * // …later: stop();\n * ```\n *\n * The built-in `console.*` channels are a Stability-1 (experimental) Node API;\n * this module degrades to a no-op where they are unavailable.\n */\n\nimport { trace, type Attributes } from '@opentelemetry/api';\nimport { logs, SeverityNumber, type Logger } from '@opentelemetry/api-logs';\nimport { safeRequire } from '../node-require.js';\nimport { subscribeChannel } from './channel.js';\n\n/** Console methods that publish a diagnostics channel. */\nexport type ConsoleLevel = 'log' | 'info' | 'debug' | 'warn' | 'error';\n\nconst ALL_LEVELS: readonly ConsoleLevel[] = [\n  'log',\n  'info',\n  'debug',\n  'warn',\n  'error',\n];\n\nconst SEVERITY: Record<ConsoleLevel, SeverityNumber> = {\n  debug: SeverityNumber.DEBUG,\n  log: SeverityNumber.INFO,\n  info: SeverityNumber.INFO,\n  warn: SeverityNumber.WARN,\n  error: SeverityNumber.ERROR,\n};\n\nexport interface CaptureConsoleOptions {\n  /** Which console methods to capture. Defaults to all five. */\n  levels?: readonly ConsoleLevel[];\n  /**\n   * Where to record captured output:\n   * - `'log'` (default): emit an OpenTelemetry log record;\n   * - `'span-event'`: add an event to the active span (nothing if no active span);\n   * - `'both'`.\n   */\n  target?: 'log' | 'span-event' | 'both';\n  /** Logger name for emitted records. Defaults to `'autotel.console'`. */\n  loggerName?: string;\n  /** Static attributes merged onto every captured record/event. */\n  attributes?: Attributes;\n}\n\ntype ConsoleMessage = { args?: unknown[] };\n\nconst nodeUtil = safeRequire<typeof import('node:util')>('node:util');\n\n/** Format console arguments the way `console` itself would (printf + inspect). */\nfunction formatArgs(args: unknown[]): string {\n  if (nodeUtil?.format) return nodeUtil.format(...args);\n  return args\n    .map((a) => (typeof a === 'string' ? a : safeStringify(a)))\n    .join(' ');\n}\n\nfunction safeStringify(value: unknown): string {\n  try {\n    return JSON.stringify(value) ?? String(value);\n  } catch {\n    return String(value);\n  }\n}\n\n/**\n * Start capturing `console.*` calls as wide events. Returns a disposer that\n * stops capture. Safe to call on runtimes without the console channels (no-op).\n */\nexport function captureConsole(\n  options: CaptureConsoleOptions = {},\n): () => void {\n  const levels = options.levels ?? ALL_LEVELS;\n  const target = options.target ?? 'log';\n  const toLog = target === 'log' || target === 'both';\n  const toSpan = target === 'span-event' || target === 'both';\n  const logger: Logger = logs.getLogger(\n    options.loggerName ?? 'autotel.console',\n  );\n\n  // Guard against re-entrancy: if recording a captured call itself triggers a\n  // `console.*` (e.g. an exporter logging a warning), don't capture that.\n  let recording = false;\n\n  const disposers = levels.map((level) =>\n    subscribeChannel(`console.${level}`, (message) => {\n      if (recording) return;\n      const args = (message as ConsoleMessage)?.args ?? [];\n      const body = formatArgs(args as unknown[]);\n      recording = true;\n      try {\n        const attributes: Attributes = {\n          'log.source': 'console',\n          'log.method': level,\n          ...options.attributes,\n        };\n        if (toLog) {\n          logger.emit({\n            severityNumber: SEVERITY[level],\n            severityText: level.toUpperCase(),\n            body,\n            attributes,\n          });\n        }\n        if (toSpan) {\n          trace\n            .getActiveSpan()\n            ?.addEvent('log', { 'log.message': body, ...attributes });\n        }\n      } finally {\n        recording = false;\n      }\n    }),\n  );\n\n  let active = true;\n  return () => {\n    if (!active) return;\n    active = false;\n    for (const dispose of disposers) dispose();\n  };\n}\n","/**\n * Lightweight HTTP spans via Node's built-in `diagnostics_channel` — no\n * monkey-patching, no `import-in-the-middle`.\n *\n * Node publishes `http.server.request.start` / `http.server.response.finish`\n * and `http.client.request.start` / `http.client.response.finish` /\n * `http.client.request.error`. {@link instrumentHttp} subscribes to those and\n * emits a `SERVER` span per inbound request (parented to an incoming W3C\n * `traceparent`) and a `CLIENT` span per outbound request (whose context it\n * injects into the outgoing headers for downstream propagation).\n *\n * ```ts\n * import { instrumentHttp } from 'autotel/diagnostics';\n *\n * const stop = instrumentHttp();\n * ```\n *\n * Scope & limitation. This is an opt-in, low-overhead alternative to\n * `@opentelemetry/instrumentation-http` for HTTP span coverage + W3C\n * propagation. Client-side propagation works (the `traceparent` is injected on\n * the `ClientRequest` object directly). What it does **not** do is establish an\n * *ambient* OpenTelemetry context for the duration of a server request handler,\n * so application spans created inside a handler will not become children of the\n * `SERVER` span.\n *\n * This is structural, not a \"wait for a newer Node\" gap. Node publishes the\n * `http.*` channels with a plain `channel.publish()` — not `runStores` /\n * `tracingChannel` — so a subscriber has no scope to bind a store to. The only\n * ways to get handler nesting both defeat the purpose of using a channel:\n *   1. `AsyncLocalStorage.enterWith()` in the start handler — no scoped exit, so\n *      context leaks across requests sharing an event-loop tick / keep-alive\n *      connection and misattributes spans. Strictly worse than no nesting.\n *   2. Patching `http.Server.prototype.emit` to wrap the `'request'` listener in\n *      `context.with()` — monkey-patching, i.e. reimplementing\n *      `@opentelemetry/instrumentation-http`.\n * If you need handler nesting, use `@opentelemetry/instrumentation-http`.\n *\n * The `http.*` channels are a Stability-1 (experimental) Node API; this module\n * degrades to a no-op where they are unavailable.\n */\n\nimport type { ClientRequest, IncomingMessage, ServerResponse } from 'node:http';\nimport {\n  context as otelContext,\n  defaultTextMapGetter,\n  defaultTextMapSetter,\n  propagation,\n  SpanKind,\n  SpanStatusCode,\n  trace,\n  type Attributes,\n  type Span,\n  type Tracer,\n} from '@opentelemetry/api';\nimport {\n  ATTR_HTTP_REQUEST_METHOD,\n  ATTR_HTTP_RESPONSE_STATUS_CODE,\n  ATTR_NETWORK_PROTOCOL_VERSION,\n  ATTR_SERVER_ADDRESS,\n  ATTR_SERVER_PORT,\n  ATTR_URL_FULL,\n  ATTR_URL_PATH,\n  ATTR_URL_SCHEME,\n  ATTR_USER_AGENT_ORIGINAL,\n} from '@opentelemetry/semantic-conventions';\nimport { subscribeChannel } from './channel.js';\n\nexport interface InstrumentHttpOptions {\n  /** Instrument inbound (server) requests. Default `true`. */\n  server?: boolean;\n  /** Instrument outbound (client) requests. Default `true`. */\n  client?: boolean;\n  /** Tracer to use. Defaults to `trace.getTracer('autotel.http-diagnostics')`. */\n  tracer?: Tracer;\n}\n\ninterface ServerStartMessage {\n  request?: IncomingMessage;\n  response?: ServerResponse;\n}\ninterface ServerFinishMessage {\n  request?: IncomingMessage;\n  response?: ServerResponse;\n}\ninterface ClientStartMessage {\n  request?: ClientRequest;\n}\ninterface ClientFinishMessage {\n  request?: ClientRequest;\n  response?: IncomingMessage;\n}\ninterface ClientErrorMessage {\n  request?: ClientRequest;\n  error?: unknown;\n}\n\nconst SERVER_SPANS = new WeakMap<object, Span>();\nconst CLIENT_SPANS = new WeakMap<object, Span>();\n\nfunction firstHeader(value: string | string[] | undefined): string | undefined {\n  return Array.isArray(value) ? value[0] : value;\n}\n\nfunction splitHostPort(host: string | undefined): {\n  address?: string;\n  port?: number;\n} {\n  if (!host) return {};\n  const idx = host.lastIndexOf(':');\n  if (idx === -1) return { address: host };\n  const port = Number(host.slice(idx + 1));\n  return {\n    address: host.slice(0, idx),\n    port: Number.isFinite(port) ? port : undefined,\n  };\n}\n\n/**\n * Start emitting HTTP server/client spans from Node's HTTP diagnostics\n * channels. Returns a disposer; a no-op on runtimes without the channels.\n */\nexport function instrumentHttp(\n  options: InstrumentHttpOptions = {},\n): () => void {\n  const tracer = options.tracer ?? trace.getTracer('autotel.http-diagnostics');\n  const disposers: Array<() => void> = [];\n\n  if (options.server !== false) {\n    disposers.push(\n      subscribeChannel('http.server.request.start', (message) => {\n        const request = (message as ServerStartMessage)?.request;\n        if (!request) return;\n        const method = request.method ?? 'HTTP';\n        const host = firstHeader(request.headers.host);\n        const { address, port } = splitHostPort(host);\n        const path = (request.url ?? '/').split('?', 1)[0];\n        const attributes: Attributes = {\n          [ATTR_HTTP_REQUEST_METHOD]: method,\n          [ATTR_URL_PATH]: path,\n          [ATTR_URL_SCHEME]: 'http',\n          [ATTR_NETWORK_PROTOCOL_VERSION]: request.httpVersion,\n          [ATTR_USER_AGENT_ORIGINAL]: firstHeader(\n            request.headers['user-agent'],\n          ),\n          [ATTR_SERVER_ADDRESS]: address,\n          [ATTR_SERVER_PORT]: port,\n        };\n        const parent = propagation.extract(\n          otelContext.active(),\n          request.headers,\n          defaultTextMapGetter,\n        );\n        const span = tracer.startSpan(\n          method,\n          { kind: SpanKind.SERVER, attributes },\n          parent,\n        );\n        SERVER_SPANS.set(request, span);\n      }),\n      subscribeChannel('http.server.response.finish', (message) => {\n        const { request, response } = (message as ServerFinishMessage) ?? {};\n        if (!request) return;\n        const span = SERVER_SPANS.get(request);\n        if (!span) return;\n        SERVER_SPANS.delete(request);\n        finishHttpSpan(span, response?.statusCode, 500);\n      }),\n    );\n  }\n\n  if (options.client !== false) {\n    disposers.push(\n      subscribeChannel('http.client.request.start', (message) => {\n        const request = (message as ClientStartMessage)?.request;\n        if (!request) return;\n        const method = request.method ?? 'HTTP';\n        // `ClientRequest` exposes host/protocol/path on the public surface.\n        const req = request as ClientRequest & {\n          host?: string;\n          protocol?: string;\n          path?: string;\n        };\n        const { address, port } = splitHostPort(req.host);\n        const scheme = (req.protocol ?? 'http:').replace(':', '');\n        const attributes: Attributes = {\n          [ATTR_HTTP_REQUEST_METHOD]: method,\n          [ATTR_SERVER_ADDRESS]: address,\n          [ATTR_SERVER_PORT]: port,\n          [ATTR_URL_FULL]:\n            address && req.path\n              ? `${scheme}://${req.host}${req.path}`\n              : undefined,\n        };\n        const span = tracer.startSpan(method, {\n          kind: SpanKind.CLIENT,\n          attributes,\n        });\n        CLIENT_SPANS.set(request, span);\n\n        // Inject this span's context into the outbound headers so the\n        // downstream service continues the trace.\n        if (!request.headersSent) {\n          const carrier: Record<string, string> = {};\n          propagation.inject(\n            trace.setSpan(otelContext.active(), span),\n            carrier,\n            defaultTextMapSetter,\n          );\n          for (const [key, value] of Object.entries(carrier)) {\n            try {\n              request.setHeader(key, value);\n            } catch {\n              // Headers already sent / immutable — propagation best-effort.\n            }\n          }\n        }\n      }),\n      subscribeChannel('http.client.response.finish', (message) => {\n        const { request, response } = (message as ClientFinishMessage) ?? {};\n        if (!request) return;\n        const span = CLIENT_SPANS.get(request);\n        if (!span) return;\n        CLIENT_SPANS.delete(request);\n        finishHttpSpan(span, response?.statusCode, 400);\n      }),\n      subscribeChannel('http.client.request.error', (message) => {\n        const { request, error } = (message as ClientErrorMessage) ?? {};\n        if (!request) return;\n        const span = CLIENT_SPANS.get(request);\n        if (!span) return;\n        CLIENT_SPANS.delete(request);\n        if (error instanceof Error) span.recordException(error);\n        span.setStatus({\n          code: SpanStatusCode.ERROR,\n          message: error instanceof Error ? error.message : undefined,\n        });\n        span.end();\n      }),\n    );\n  }\n\n  let active = true;\n  return () => {\n    if (!active) return;\n    active = false;\n    for (const dispose of disposers) dispose();\n  };\n}\n\n/** Set status code + error status (when `>= errorAt`) and end the span. */\nfunction finishHttpSpan(\n  span: Span,\n  statusCode: number | undefined,\n  errorAt: number,\n): void {\n  if (statusCode !== undefined) {\n    span.setAttribute(ATTR_HTTP_RESPONSE_STATUS_CODE, statusCode);\n    if (statusCode >= errorAt) {\n      span.setStatus({ code: SpanStatusCode.ERROR });\n    }\n  }\n  span.end();\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autotel",
-  "version": "4.2.1",
+  "version": "4.2.2",
   "description": "Write Once, Observe Anywhere",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -15,6 +15,11 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./diagnostics": {
+      "types": "./dist/diagnostics.d.ts",
+      "import": "./dist/diagnostics.js",
+      "require": "./dist/diagnostics.cjs"
+    },
     "./instrumentation": {
       "types": "./dist/instrumentation.d.ts",
       "import": "./dist/instrumentation.js",

package/skills/review-otel-patterns/SKILL.md

@@ -393,28 +393,31 @@ autotel implements the **OTel gen-ai semantic conventions** out of the box. Toke
 ```typescript
 import { trace } from 'autotel';
 import { withAiTelemetry } from 'autotel-edge';
+import { registerTelemetry } from 'ai';
 import { streamText } from 'ai';
+import { autotelTelemetry } from 'autotel-genai/observer';
+
+registerTelemetry(autotelTelemetry()); // Node / server runtimes
 
 const handler = trace(async (req) => {
   const result = await streamText({
     model: withAiTelemetry('anthropic/claude-sonnet-4.6'),
     messages: req.messages,
-    experimental_telemetry: { isEnabled: true },
   });
   return result.toResponse();
 });
 ```
 
-Captured attributes per call: `gen_ai.provider.name`, `gen_ai.request.model`, `gen_ai.usage.input_tokens` / `output_tokens` / `reasoning.output_tokens` / `cache_read.input_tokens`, `gen_ai.response.finish_reasons`, `gen_ai.response.id`, plus per-tool spans with `gen_ai.tool.name`. Cost estimation (`gen_ai.usage.cost.usd`) comes for free if you pass a pricing map to `withAiTelemetry`.
+Captured attributes per call: `gen_ai.provider.name`, `gen_ai.request.model`, `gen_ai.usage.input_tokens` / `output_tokens` / `reasoning.output_tokens` / `cache_read.input_tokens`, `gen_ai.response.finish_reasons`, `gen_ai.response.id`, plus per-tool spans with `gen_ai.tool.name`. Cost estimation (`gen_ai.usage.cost.usd`) comes for free from `autotelTelemetry()` in Node runtimes or if you pass a pricing map to `withAiTelemetry`.
 
 Anti-patterns to detect:
 
-| Anti-pattern                          | Fix                                                       |
-| ------------------------------------- | --------------------------------------------------------- |
-| Manual `result.usage` printing        | `withAiTelemetry()` — captures via middleware             |
-| Custom `ai.tokens` attribute names    | Use OTel gen-ai conventions (`gen_ai.usage.input_tokens`) |
-| Tool calls as plain log lines         | Each tool call gets a child span automatically            |
-| No retry / partial-failure visibility | `experimental_telemetry: { isEnabled: true }` flips it on |
+| Anti-pattern                       | Fix                                                       |
+| ---------------------------------- | --------------------------------------------------------- |
+| Manual `result.usage` printing     | `autotelTelemetry()` or `withAiTelemetry()`               |
+| Custom `ai.tokens` attribute names | Use OTel gen-ai conventions (`gen_ai.usage.input_tokens`) |
+| Tool calls as plain log lines      | Each tool call gets a child span automatically            |
+| AI SDK not registered in Node      | `registerTelemetry(autotelTelemetry())`                   |
 
 ---
 

package/skills/review-otel-patterns/references/code-review.md

@@ -49,10 +49,11 @@ Run through this list when adding observability to a new service or auditing an
 
 ## AI / LLM
 
-- [ ] **`withAiTelemetry()` from `autotel-edge`.** Captures `gen_ai.*` semantic attributes automatically.
+- [ ] **Node/server runtimes register `autotelTelemetry()`.** `registerTelemetry(autotelTelemetry())` captures canonical `gen_ai.*`, tool spans, cost, and streaming timing.
+- [ ] **Edge runtimes use `withAiTelemetry()` from `autotel-edge`.** Captures `gen_ai.*` semantic attributes automatically.
 - [ ] **No bespoke `ai.tokens` attributes.** Use `gen_ai.usage.input_tokens`, etc.
-- [ ] **Cost tracking via the `cost` option** — outputs `gen_ai.cost.usd` on the span.
-- [ ] **Tool-call spans enabled.** `experimental_telemetry: { isEnabled: true }`.
+- [ ] **Cost tracking is canonical.** Use `gen_ai.usage.cost.usd`, not custom cost keys.
+- [ ] **Tool-call spans are emitted by the integration.** No plain log-only tool activity.
 
 ## Testing