@ayepi/otel 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Philip Diffenderfer
+
+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,112 @@
+# @ayepi/otel
+
+Telemetry middleware for [`@ayepi/core`](https://www.npmjs.com/package/@ayepi/core).
+It **enriches the [`@ayepi/log`](https://www.npmjs.com/package/@ayepi/log) trace
+context** so every inner `logger.*` call during a request carries the chosen fields,
+and **optionally logs a request and/or response line** with a configurable, per-set
+field selection.
+
+```sh
+pnpm add @ayepi/otel @ayepi/core @ayepi/log
+```
+
+`@ayepi/otel` ships as a **def / impl split**. The main entry is frontend-safe (no
+`node:crypto`, no `@ayepi/log`) and exports `telemetry(opts?)`, a middleware **def
+factory**. The server behaviour lives behind `@ayepi/otel/server`, which augments
+`telemetry` with `.server(def, opts)` — the only place that pulls in node deps.
+
+```ts
+// shared.ts — frontend-safe: only the def + the spec
+import { telemetry } from '@ayepi/otel'
+
+const tel = telemetry() // a no-context middleware def (contributes nothing to ctx)
+
+const api = spec({ endpoints: { ...tel.group({ getUser: { … } }) } })
+```
+
+```ts
+// server.ts — binds behaviour and imports node deps
+import { telemetry } from '@ayepi/otel/server'
+import { implement } from '@ayepi/core'
+
+const app = implement(api)
+  .middleware(telemetry.server(tel, { echoRequestId: true, request: { ip: true } }))
+  .server()
+```
+
+`telemetry()` provides **nothing** to the handler context; it only logs and establishes
+trace context. By default `.server` enriches every inner log with `{ requestId, method,
+path }`, logs a `request` line with `{ method, path, requestId }`, and a `response` line
+with `{ status, duration }`. The error path logs the serialized error + best-effort status
+and **rethrows** (it never swallows).
+
+## Def vs server
+
+- `telemetry(opts?)` (def factory, `@ayepi/otel`) — frontend-safe. `opts = { name?,
+  requires? }`. Declares the contract; carries no behaviour and no node deps. A spec that
+  imports only this entry is safe to bundle for the frontend.
+- `telemetry.server(def, opts)` (`@ayepi/otel/server`) — binds the implementation. **All**
+  behaviour options live here: `level, context, request, response, overrides, requestId,
+  echoRequestId, extra, logger, logWith, now`. Bind it with `implement(api).middleware(...)`.
+
+## Three independent field sets
+
+These move to `.server`:
+
+```ts
+telemetry.server(tel, {
+  context: { requestId: true, traceId: true },     // inherited by every inner log
+  request: { method: true, path: true, ip: true },  // the request line (or `false` to disable)
+  response: { status: true, duration: true, error: true }, // the response line (or `false`)
+  level: 'info',                                    // level of both lines
+})
+```
+
+Request fields: `name`, `requestId`, `method`, `path`, `ip`, `size`, `traceId`.
+Response fields: `status`, `duration`, `type`, `error`, `size`.
+
+## Request id
+
+Default precedence: the `X-Request-ID` header, else a generated UUID (`node:crypto`).
+Override with `requestId: (req) => string` on `.server`. A websocket **frame** id is not
+reachable from a middleware, so it is not a source — see `ayepi-otel.md`.
+
+## Per-endpoint overrides
+
+The matched endpoint name is not reachable from a middleware at runtime, so overrides are
+done the idiomatic ayepi way: attach a tailored `telemetry({...})` def to the specific
+endpoint or group, and bind a matching `.server` impl.
+
+```ts
+// shared.ts
+const base = telemetry()
+const noisy = telemetry({ name: 'upload' })
+
+spec({
+  endpoints: {
+    ...base.group({ getUser, listUsers }),
+    upload: noisy.endpoint({ … }),
+  },
+})
+
+// server.ts
+implement(api)
+  .middleware(telemetry.server(base, {}))
+  .middleware(telemetry.server(noisy, { request: { method: true, path: true, ip: true, size: true } }))
+```
+
+(You may also keep a single def and carry per-route tweaks in `.server`'s `overrides` map —
+see `ayepi-otel.md`.)
+
+## For AI coding agents
+
+This package ships dense, machine-oriented reference docs written for **AI coding agents**
+(Claude Code, Cursor, and the like) to understand and drive the package — point your agent at them:
+
+- [`ayepi-otel.md`](./ayepi-otel.md)
+
+They live next to the source in the [repo](https://github.com/ClickerMonkey/ayepi/tree/main/packages/otel) and are **not** shipped in the npm tarball.
+
+## License
+
+MIT © Philip Diffenderfer

package/dist/index.cjs

@@ -0,0 +1,43 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _ayepi_core = require("@ayepi/core");
+//#region src/index.ts
+/**
+* # @ayepi/otel
+*
+* A telemetry middleware **def** for `@ayepi/core`. This entry is **frontend-safe**:
+* it declares a no-context middleware (it logs and establishes trace context, but
+* contributes nothing to the handler payload) with no `node:crypto` and no
+* `@ayepi/log` runtime import. All behaviour — field selection, the request/response
+* lines, the trace context, the logger — is configured server-side when you bind it
+* with [`telemetry.server`](./server) from `@ayepi/otel/server`.
+*
+* ```ts
+* // shared.ts (frontend-safe)
+* import { telemetry } from '@ayepi/otel';
+* const tel = telemetry();
+* spec({ endpoints: { ...tel.group({ … }) } });
+*
+* // server.ts
+* import { telemetry } from '@ayepi/otel/server';
+* implement(api).middleware(telemetry.server(tel, { echoRequestId: true }));
+* ```
+*
+* @module
+*/
+/**
+* Create a telemetry middleware **def** — a no-context, frontend-safe contract.
+* Bind its behaviour with [`telemetry.server(def, opts)`](./server).
+*
+* @typeParam R - inferred from `requires`.
+*
+* @example
+* ```ts
+* const tel = telemetry();                              // default name 'otel'
+* spec({ endpoints: { ...tel.group({ getUser }) } });
+* ```
+*/
+function telemetry(opts) {
+	return (0, _ayepi_core.middleware)(opts?.name ?? "otel", { requires: opts?.requires ?? [] });
+}
+//#endregion
+exports.telemetry = telemetry;

package/dist/index.d.cts

@@ -0,0 +1,33 @@
+import { AnyMiddleware, EmptyObject, MiddlewareDef } from "@ayepi/core";
+
+//#region src/index.d.ts
+
+/**
+ * Options for the {@link telemetry} **def** — frontend-safe only.
+ *
+ * @typeParam R - middleware this one depends on (their context is typed in the
+ *   server-side `extra`).
+ */
+interface TelemetryDefOptions<R extends readonly AnyMiddleware[]> {
+  /** Middleware name for docs/debugging, and the default value for the `name` field (default `'otel'`). */
+  readonly name?: string;
+  /** Middleware this one depends on — their context is available (and typed) in the server-side `extra`. */
+  readonly requires?: R;
+}
+/**
+ * Create a telemetry middleware **def** — a no-context, frontend-safe contract.
+ * Bind its behaviour with [`telemetry.server(def, opts)`](./server).
+ *
+ * @typeParam R - inferred from `requires`.
+ *
+ * @example
+ * ```ts
+ * const tel = telemetry();                              // default name 'otel'
+ * spec({ endpoints: { ...tel.group({ getUser }) } });
+ * ```
+ */
+declare function telemetry<const R extends readonly AnyMiddleware[] = readonly []>(opts?: TelemetryDefOptions<R>): TelemetryDef<R>;
+/** The def type a {@link telemetry} call produces — what `telemetry.server` binds against. */
+type TelemetryDef<R extends readonly AnyMiddleware[] = readonly []> = MiddlewareDef<EmptyObject, R>;
+//#endregion
+export { TelemetryDef, TelemetryDefOptions, telemetry };

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import { AnyMiddleware, EmptyObject, MiddlewareDef } from "@ayepi/core";
+
+//#region src/index.d.ts
+
+/**
+ * Options for the {@link telemetry} **def** — frontend-safe only.
+ *
+ * @typeParam R - middleware this one depends on (their context is typed in the
+ *   server-side `extra`).
+ */
+interface TelemetryDefOptions<R extends readonly AnyMiddleware[]> {
+  /** Middleware name for docs/debugging, and the default value for the `name` field (default `'otel'`). */
+  readonly name?: string;
+  /** Middleware this one depends on — their context is available (and typed) in the server-side `extra`. */
+  readonly requires?: R;
+}
+/**
+ * Create a telemetry middleware **def** — a no-context, frontend-safe contract.
+ * Bind its behaviour with [`telemetry.server(def, opts)`](./server).
+ *
+ * @typeParam R - inferred from `requires`.
+ *
+ * @example
+ * ```ts
+ * const tel = telemetry();                              // default name 'otel'
+ * spec({ endpoints: { ...tel.group({ getUser }) } });
+ * ```
+ */
+declare function telemetry<const R extends readonly AnyMiddleware[] = readonly []>(opts?: TelemetryDefOptions<R>): TelemetryDef<R>;
+/** The def type a {@link telemetry} call produces — what `telemetry.server` binds against. */
+type TelemetryDef<R extends readonly AnyMiddleware[] = readonly []> = MiddlewareDef<EmptyObject, R>;
+//#endregion
+export { TelemetryDef, TelemetryDefOptions, telemetry };

package/dist/index.js

@@ -0,0 +1,42 @@
+import { middleware } from "@ayepi/core";
+//#region src/index.ts
+/**
+* # @ayepi/otel
+*
+* A telemetry middleware **def** for `@ayepi/core`. This entry is **frontend-safe**:
+* it declares a no-context middleware (it logs and establishes trace context, but
+* contributes nothing to the handler payload) with no `node:crypto` and no
+* `@ayepi/log` runtime import. All behaviour — field selection, the request/response
+* lines, the trace context, the logger — is configured server-side when you bind it
+* with [`telemetry.server`](./server) from `@ayepi/otel/server`.
+*
+* ```ts
+* // shared.ts (frontend-safe)
+* import { telemetry } from '@ayepi/otel';
+* const tel = telemetry();
+* spec({ endpoints: { ...tel.group({ … }) } });
+*
+* // server.ts
+* import { telemetry } from '@ayepi/otel/server';
+* implement(api).middleware(telemetry.server(tel, { echoRequestId: true }));
+* ```
+*
+* @module
+*/
+/**
+* Create a telemetry middleware **def** — a no-context, frontend-safe contract.
+* Bind its behaviour with [`telemetry.server(def, opts)`](./server).
+*
+* @typeParam R - inferred from `requires`.
+*
+* @example
+* ```ts
+* const tel = telemetry();                              // default name 'otel'
+* spec({ endpoints: { ...tel.group({ getUser }) } });
+* ```
+*/
+function telemetry(opts) {
+	return middleware(opts?.name ?? "otel", { requires: opts?.requires ?? [] });
+}
+//#endregion
+export { telemetry };

package/dist/server.cjs

@@ -0,0 +1,273 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_index = require("./index.cjs");
+let _ayepi_core = require("@ayepi/core");
+let _ayepi_log = require("@ayepi/log");
+let node_crypto = require("node:crypto");
+//#region src/server.ts
+/** Fallback HTTP status when a thrown error is not an {@link ApiError}. */
+const DEFAULT_ERROR_STATUS = 500;
+/** Default success status for a plain-object / void handler result. */
+const DEFAULT_OK_STATUS = 200;
+/** Header carrying a caller-supplied request id (the default requestId source). */
+const REQUEST_ID_HEADER = "x-request-id";
+/** Default header name used when {@link TelemetryServerOptions.echoRequestId} is `true`. */
+const DEFAULT_ECHO_HEADER = "x-request-id";
+/** Header carrying the upstream client ip (checked before `X-Real-IP`). */
+const FORWARDED_FOR_HEADER = "x-forwarded-for";
+/** Header carrying the client ip when there is no proxy chain. */
+const REAL_IP_HEADER = "x-real-ip";
+/** Header carrying a distributed-trace id (W3C `traceparent` or a bare id). */
+const TRACE_HEADER = "x-trace-id";
+/** Header carrying the request body size in bytes. */
+const CONTENT_LENGTH_HEADER = "content-length";
+/** Default log level for the request/response lines. */
+const DEFAULT_LEVEL = "info";
+/** Default message for the request log line. */
+const DEFAULT_REQUEST_MSG = "request";
+/** Default message for the response log line. */
+const DEFAULT_RESPONSE_MSG = "response";
+const DEFAULT_CONTEXT_FIELDS = {
+	requestId: true,
+	method: true,
+	path: true
+};
+const DEFAULT_REQUEST_FIELDS = {
+	method: true,
+	path: true,
+	requestId: true
+};
+const DEFAULT_RESPONSE_FIELDS = {
+	status: true,
+	duration: true
+};
+/** Resolve the per-call config for a route, applying its {@link TelemetryServerOptions.overrides} entry (if any). */
+function resolveCall(base, overrides, routeName) {
+	const o = overrides?.[routeName];
+	const merged = o ? {
+		...base,
+		...o
+	} : base;
+	const request = merged.request;
+	const response = merged.response;
+	return {
+		name: merged.name,
+		level: merged.level,
+		contextFlags: merged.context ?? DEFAULT_CONTEXT_FIELDS,
+		requestFlags: request === false ? null : request ?? DEFAULT_REQUEST_FIELDS,
+		responseFlags: response === false ? null : response ?? DEFAULT_RESPONSE_FIELDS,
+		echoRequestId: merged.echoRequestId ?? false
+	};
+}
+/**
+* Resolve the request id. Precedence: caller `override(req)` → the ws **frame id**
+* (`io.ws.id`, the real per-call id) → `X-Request-ID` header → a generated UUID.
+*/
+function resolveRequestId(io, override) {
+	if (override) return override(io.req);
+	if (io.ws) return io.ws.id;
+	const header = io.req.headers.get(REQUEST_ID_HEADER);
+	if (header) return header;
+	return (0, node_crypto.randomUUID)();
+}
+/** First-hop client ip from `X-Forwarded-For`, else `X-Real-IP`, else `undefined`. */
+function resolveIp(req) {
+	const fwd = req.headers.get(FORWARDED_FOR_HEADER);
+	if (fwd) return fwd.split(",")[0].trim();
+	return req.headers.get(REAL_IP_HEADER) ?? void 0;
+}
+/** Body size in bytes from `Content-Length`, if present and numeric. */
+function resolveSize(req) {
+	const raw = req.headers.get(CONTENT_LENGTH_HEADER);
+	if (raw === null) return;
+	const n = Number(raw);
+	return Number.isFinite(n) ? n : void 0;
+}
+/** The method/path for a route — present for endpoints, absent for events. */
+function routeMethodPath(route) {
+	if (route.kind === "endpoint") return {
+		method: route.method,
+		path: route.path
+	};
+	return {
+		method: void 0,
+		path: void 0
+	};
+}
+/** Compute every candidate request field for this invocation. */
+function deriveRequest(io, name, override) {
+	const { method, path } = routeMethodPath(io.route);
+	return {
+		name,
+		requestId: resolveRequestId(io, override),
+		method,
+		path,
+		transport: io.transport,
+		ip: resolveIp(io.req),
+		size: resolveSize(io.req),
+		traceId: io.req.headers.get(TRACE_HEADER) ?? void 0
+	};
+}
+/** Pick the toggled-on request fields, dropping any that are `undefined`. */
+function pickRequest(derived, flags) {
+	const out = {};
+	if (flags.name) out.name = derived.name;
+	if (flags.requestId) out.requestId = derived.requestId;
+	if (flags.method && derived.method !== void 0) out.method = derived.method;
+	if (flags.path && derived.path !== void 0) out.path = derived.path;
+	if (flags.transport) out.transport = derived.transport;
+	if (flags.ip && derived.ip !== void 0) out.ip = derived.ip;
+	if (flags.size && derived.size !== void 0) out.size = derived.size;
+	if (flags.traceId && derived.traceId !== void 0) out.traceId = derived.traceId;
+	return out;
+}
+/** Inspect a successful handler result for status + type + (rarely) size. */
+function inspectResult(result) {
+	if (result instanceof Response) {
+		const len = result.headers.get(CONTENT_LENGTH_HEADER);
+		const n = len === null ? void 0 : Number(len);
+		return {
+			status: result.status,
+			type: "response",
+			size: n !== void 0 && Number.isFinite(n) ? n : void 0
+		};
+	}
+	if (isMultiStatus(result)) return {
+		status: result.status,
+		type: "multi",
+		size: void 0
+	};
+	if (isAsyncIterable(result)) return {
+		status: DEFAULT_OK_STATUS,
+		type: "stream",
+		size: void 0
+	};
+	if (result === void 0 || result === null) return {
+		status: DEFAULT_OK_STATUS,
+		type: "empty",
+		size: void 0
+	};
+	return {
+		status: DEFAULT_OK_STATUS,
+		type: "json",
+		size: void 0
+	};
+}
+/** True for a multi-status handler result of the shape `{ status, data }`. */
+function isMultiStatus(v) {
+	return typeof v === "object" && v !== null && typeof v.status === "number" && "data" in v;
+}
+/** True for an async-iterable handler result (a typed/raw stream). */
+function isAsyncIterable(v) {
+	return typeof v === "object" && v !== null && typeof v[Symbol.asyncIterator] === "function";
+}
+/** Build the response log fields for the success path. */
+function pickResponseOk(result, duration, flags) {
+	const { status, type, size } = inspectResult(result);
+	const out = {};
+	if (flags.status) out.status = status;
+	if (flags.duration) out.duration = duration;
+	if (flags.type) out.type = type;
+	if (flags.size && size !== void 0) out.size = size;
+	return out;
+}
+/** Build the non-error response fields for the error path (the raw error is logged separately). */
+function pickResponseErr(err, duration, flags) {
+	const status = err instanceof _ayepi_core.ApiError ? err.status : DEFAULT_ERROR_STATUS;
+	const fields = {};
+	if (flags.status) fields.status = status;
+	if (flags.duration) fields.duration = duration;
+	if (flags.type) fields.type = "error";
+	return fields;
+}
+/** Resolve the echo header name, or `null` when echoing is off. */
+function echoHeaderName(echo) {
+	if (echo === false) return null;
+	if (echo === true) return DEFAULT_ECHO_HEADER;
+	return echo;
+}
+/** Bind a {@link telemetry} def to its runtime behaviour. */
+function telemetryServer(def, opts = {}) {
+	const name = def.name;
+	const log = opts.logger ?? _ayepi_log.logger;
+	const wrap = opts.logWith ?? _ayepi_log.logWith;
+	const now = opts.now ?? Date.now;
+	const overrides = opts.overrides;
+	const base = {
+		name,
+		level: opts.level ?? DEFAULT_LEVEL,
+		context: opts.context,
+		request: opts.request,
+		response: opts.response,
+		echoRequestId: opts.echoRequestId
+	};
+	const safely = (fn) => {
+		try {
+			fn();
+		} catch (err) {
+			try {
+				opts.onError?.(err);
+			} catch {}
+		}
+	};
+	const run = (io) => {
+		const call = resolveCall(base, overrides, io.route.name);
+		const derived = deriveRequest(io, call.name, opts.requestId);
+		const echoHeader = echoHeaderName(call.echoRequestId);
+		if (echoHeader) io.setHeader(echoHeader, derived.requestId);
+		let extra = {};
+		safely(() => {
+			extra = opts.extra ? opts.extra(io.ctx, io.req) : {};
+		});
+		let ctxFields = { ...extra };
+		safely(() => {
+			ctxFields = {
+				...extra,
+				...pickRequest(derived, call.contextFlags)
+			};
+		});
+		const body = () => {
+			safely(() => {
+				if (call.requestFlags) log.log(call.level, DEFAULT_REQUEST_MSG, {
+					...extra,
+					...pickRequest(derived, call.requestFlags)
+				});
+			});
+			const start = now();
+			return io.next().then((result) => {
+				safely(() => {
+					if (call.responseFlags) log.log(call.level, DEFAULT_RESPONSE_MSG, pickResponseOk(result, now() - start, call.responseFlags));
+				});
+				return result;
+			}, (err) => {
+				safely(() => {
+					if (call.responseFlags) {
+						const fields = pickResponseErr(err, now() - start, call.responseFlags);
+						if (call.responseFlags.error) log.error(DEFAULT_RESPONSE_MSG, fields, err);
+						else log.error(DEFAULT_RESPONSE_MSG, fields);
+					}
+				});
+				throw err;
+			});
+		};
+		try {
+			return wrap(ctxFields, body);
+		} catch (err) {
+			safely(() => {
+				throw err;
+			});
+			return body();
+		}
+	};
+	return {
+		def,
+		impl: run
+	};
+}
+/**
+* The {@link telemetry} def factory, augmented with a `.server(def, opts)` binder.
+* Import from `@ayepi/otel/server` in your server entry to bind a def created in a
+* frontend-safe spec.
+*/
+const telemetry = Object.assign(require_index.telemetry, { server: telemetryServer });
+//#endregion
+exports.telemetry = telemetry;

package/dist/server.d.cts

@@ -0,0 +1,141 @@
+import { telemetry as telemetry$1 } from "./index.cjs";
+import { AnyMiddleware, BoundMiddleware, StackCtx } from "@ayepi/core";
+import { Level, Logger } from "@ayepi/log";
+
+//#region src/server.d.ts
+
+/**
+ * Request-derived fields, each independently toggleable. A `true` includes the
+ * field (when derivable); a `false`/omitted excludes it.
+ */
+interface RequestFieldFlags {
+  /** The matched route name (`io.route.name`) — the endpoint/event label. */
+  readonly name?: boolean;
+  /** The resolved request id (see {@link TelemetryServerOptions.requestId}). */
+  readonly requestId?: boolean;
+  /** The HTTP method, from `io.route` (absent on an `event` route). */
+  readonly method?: boolean;
+  /** The route path, from `io.route` (absent on an `event` route). */
+  readonly path?: boolean;
+  /** The transport this invocation arrived on (`'http'` or `'ws'`), from `io.transport`. */
+  readonly transport?: boolean;
+  /** The client ip, from `X-Forwarded-For` (first hop) then `X-Real-IP`. */
+  readonly ip?: boolean;
+  /** The request body size in bytes, from `Content-Length`. */
+  readonly size?: boolean;
+  /** A distributed-trace id, from `X-Trace-Id` / `traceparent`. */
+  readonly traceId?: boolean;
+}
+/**
+ * Response-derived fields, each independently toggleable. `duration` and `error`
+ * are reliable; `status` is best-effort and `size` is rarely derivable from a
+ * middleware (see {@link ResponseFieldFlags.size}).
+ */
+interface ResponseFieldFlags {
+  /** The response status (best-effort: 200 / multi-status `{ status }` / `ApiError.status` / 500). */
+  readonly status?: boolean;
+  /** The wall-clock duration in milliseconds. */
+  readonly duration?: boolean;
+  /** The response "type" — `'json' | 'multi' | 'stream' | 'response' | 'empty' | 'error'`. */
+  readonly type?: boolean;
+  /** A serialized error on the failure path. */
+  readonly error?: boolean;
+  /**
+   * The response body size in bytes. Only derivable when a middleware
+   * short-circuits with a `Response` that carries `Content-Length`; omitted
+   * otherwise. Opt-in and honestly limited — see `ayepi-otel.md`.
+   */
+  readonly size?: boolean;
+}
+/**
+ * The subset of {@link TelemetryServerOptions} that can be overridden **per route**
+ * via {@link TelemetryServerOptions.overrides}. Everything here is per-call
+ * behaviour; the plumbing options (`logger`, `logWith`, `now`, `extra`) are not.
+ */
+interface PerCallOptions {
+  /** Override the emitted `name` field value for this route. */
+  readonly name?: string;
+  /** Override the log level for both lines on this route. */
+  readonly level?: Level;
+  /** Override the `context` (`logWith`) field selection on this route. */
+  readonly context?: RequestFieldFlags;
+  /** Override the request-line field selection on this route (`false` disables it). */
+  readonly request?: RequestFieldFlags | false;
+  /** Override the response-line field selection on this route (`false` disables it). */
+  readonly response?: ResponseFieldFlags | false;
+  /** Override the request-id echo behaviour on this route. */
+  readonly echoRequestId?: boolean | string;
+}
+/** The `requires` chain of a middleware def. */
+type ReqOf<M extends AnyMiddleware> = M['__req'];
+/**
+ * Server-side options for binding a {@link telemetry} def. Every field has a
+ * sensible default; the three field sets ({@link context}, {@link request},
+ * {@link response}) are configured independently.
+ *
+ * @typeParam M - the telemetry def being bound (its `requires` type the `extra`
+ *   callback reads).
+ */
+interface TelemetryServerOptions<M extends AnyMiddleware> {
+  /** Log level for the request/response lines (default `'info'`). */
+  readonly level?: Level;
+  /**
+   * Which request fields go into the `logWith` trace context inherited by every
+   * inner log. Default: `{ requestId: true, method: true, path: true }`.
+   */
+  readonly context?: RequestFieldFlags;
+  /**
+   * The request log line. `false` disables it; an object selects fields
+   * (default: `{ method: true, path: true, requestId: true }`).
+   */
+  readonly request?: RequestFieldFlags | false;
+  /**
+   * The response log line. `false` disables it; an object selects fields
+   * (default: `{ status: true, duration: true }`).
+   */
+  readonly response?: ResponseFieldFlags | false;
+  /**
+   * Per-route overrides, keyed by `io.route.name` (the endpoint/event key). The
+   * matching entry is shallow-merged over the base per-call config at call time.
+   */
+  readonly overrides?: Record<string, PerCallOptions>;
+  /**
+   * Resolve the request id from the upgrade/HTTP request. Highest precedence;
+   * default precedence when omitted is `io.ws?.id` (the ws frame id) →
+   * `X-Request-ID` header → a generated UUID.
+   */
+  readonly requestId?: (req: Request) => string;
+  /**
+   * Echo the resolved request id back on the response via `io.setHeader`. `false`
+   * (default) does nothing; `true` uses the `x-request-id` header; a string uses
+   * that header name.
+   */
+  readonly echoRequestId?: boolean | string;
+  /** Extra static/dynamic fields merged into every derived field bag (lowest precedence). */
+  readonly extra?: (ctx: StackCtx<ReqOf<M>>, req: Request) => Record<string, unknown>;
+  /** Logger used to emit the request/response lines (default the `@ayepi/log` default logger). */
+  readonly logger?: Logger;
+  /** `logWith` used to push the trace context (default the `@ayepi/log` default `logWith`). */
+  readonly logWith?: <T>(add: object, inner: () => T) => T;
+  /**
+   * Observe an error thrown by the telemetry itself — your `extra` callback, a log call, or
+   * the context push. Telemetry is **fail-open**: such an error never breaks the request (the
+   * handler runs and its result/error are returned untouched); this hook just lets you notice.
+   * Off by default. It must not throw; if it does, the throw is ignored.
+   */
+  readonly onError?: (err: unknown) => void;
+  /** Clock for durations, in ms (default `Date.now`). Inject for deterministic tests. */
+  readonly now?: () => number;
+}
+/** Bind a {@link telemetry} def to its runtime behaviour. */
+declare function telemetryServer<M extends AnyMiddleware>(def: M, opts?: TelemetryServerOptions<M>): BoundMiddleware<M>;
+/**
+ * The {@link telemetry} def factory, augmented with a `.server(def, opts)` binder.
+ * Import from `@ayepi/otel/server` in your server entry to bind a def created in a
+ * frontend-safe spec.
+ */
+declare const telemetry: typeof telemetry$1 & {
+  server: typeof telemetryServer;
+};
+//#endregion
+export { PerCallOptions, RequestFieldFlags, ResponseFieldFlags, TelemetryServerOptions, telemetry };

package/dist/server.d.ts

@@ -0,0 +1,141 @@
+import { telemetry as telemetry$1 } from "./index.js";
+import { AnyMiddleware, BoundMiddleware, StackCtx } from "@ayepi/core";
+import { Level, Logger } from "@ayepi/log";
+
+//#region src/server.d.ts
+
+/**
+ * Request-derived fields, each independently toggleable. A `true` includes the
+ * field (when derivable); a `false`/omitted excludes it.
+ */
+interface RequestFieldFlags {
+  /** The matched route name (`io.route.name`) — the endpoint/event label. */
+  readonly name?: boolean;
+  /** The resolved request id (see {@link TelemetryServerOptions.requestId}). */
+  readonly requestId?: boolean;
+  /** The HTTP method, from `io.route` (absent on an `event` route). */
+  readonly method?: boolean;
+  /** The route path, from `io.route` (absent on an `event` route). */
+  readonly path?: boolean;
+  /** The transport this invocation arrived on (`'http'` or `'ws'`), from `io.transport`. */
+  readonly transport?: boolean;
+  /** The client ip, from `X-Forwarded-For` (first hop) then `X-Real-IP`. */
+  readonly ip?: boolean;
+  /** The request body size in bytes, from `Content-Length`. */
+  readonly size?: boolean;
+  /** A distributed-trace id, from `X-Trace-Id` / `traceparent`. */
+  readonly traceId?: boolean;
+}
+/**
+ * Response-derived fields, each independently toggleable. `duration` and `error`
+ * are reliable; `status` is best-effort and `size` is rarely derivable from a
+ * middleware (see {@link ResponseFieldFlags.size}).
+ */
+interface ResponseFieldFlags {
+  /** The response status (best-effort: 200 / multi-status `{ status }` / `ApiError.status` / 500). */
+  readonly status?: boolean;
+  /** The wall-clock duration in milliseconds. */
+  readonly duration?: boolean;
+  /** The response "type" — `'json' | 'multi' | 'stream' | 'response' | 'empty' | 'error'`. */
+  readonly type?: boolean;
+  /** A serialized error on the failure path. */
+  readonly error?: boolean;
+  /**
+   * The response body size in bytes. Only derivable when a middleware
+   * short-circuits with a `Response` that carries `Content-Length`; omitted
+   * otherwise. Opt-in and honestly limited — see `ayepi-otel.md`.
+   */
+  readonly size?: boolean;
+}
+/**
+ * The subset of {@link TelemetryServerOptions} that can be overridden **per route**
+ * via {@link TelemetryServerOptions.overrides}. Everything here is per-call
+ * behaviour; the plumbing options (`logger`, `logWith`, `now`, `extra`) are not.
+ */
+interface PerCallOptions {
+  /** Override the emitted `name` field value for this route. */
+  readonly name?: string;
+  /** Override the log level for both lines on this route. */
+  readonly level?: Level;
+  /** Override the `context` (`logWith`) field selection on this route. */
+  readonly context?: RequestFieldFlags;
+  /** Override the request-line field selection on this route (`false` disables it). */
+  readonly request?: RequestFieldFlags | false;
+  /** Override the response-line field selection on this route (`false` disables it). */
+  readonly response?: ResponseFieldFlags | false;
+  /** Override the request-id echo behaviour on this route. */
+  readonly echoRequestId?: boolean | string;
+}
+/** The `requires` chain of a middleware def. */
+type ReqOf<M extends AnyMiddleware> = M['__req'];
+/**
+ * Server-side options for binding a {@link telemetry} def. Every field has a
+ * sensible default; the three field sets ({@link context}, {@link request},
+ * {@link response}) are configured independently.
+ *
+ * @typeParam M - the telemetry def being bound (its `requires` type the `extra`
+ *   callback reads).
+ */
+interface TelemetryServerOptions<M extends AnyMiddleware> {
+  /** Log level for the request/response lines (default `'info'`). */
+  readonly level?: Level;
+  /**
+   * Which request fields go into the `logWith` trace context inherited by every
+   * inner log. Default: `{ requestId: true, method: true, path: true }`.
+   */
+  readonly context?: RequestFieldFlags;
+  /**
+   * The request log line. `false` disables it; an object selects fields
+   * (default: `{ method: true, path: true, requestId: true }`).
+   */
+  readonly request?: RequestFieldFlags | false;
+  /**
+   * The response log line. `false` disables it; an object selects fields
+   * (default: `{ status: true, duration: true }`).
+   */
+  readonly response?: ResponseFieldFlags | false;
+  /**
+   * Per-route overrides, keyed by `io.route.name` (the endpoint/event key). The
+   * matching entry is shallow-merged over the base per-call config at call time.
+   */
+  readonly overrides?: Record<string, PerCallOptions>;
+  /**
+   * Resolve the request id from the upgrade/HTTP request. Highest precedence;
+   * default precedence when omitted is `io.ws?.id` (the ws frame id) →
+   * `X-Request-ID` header → a generated UUID.
+   */
+  readonly requestId?: (req: Request) => string;
+  /**
+   * Echo the resolved request id back on the response via `io.setHeader`. `false`
+   * (default) does nothing; `true` uses the `x-request-id` header; a string uses
+   * that header name.
+   */
+  readonly echoRequestId?: boolean | string;
+  /** Extra static/dynamic fields merged into every derived field bag (lowest precedence). */
+  readonly extra?: (ctx: StackCtx<ReqOf<M>>, req: Request) => Record<string, unknown>;
+  /** Logger used to emit the request/response lines (default the `@ayepi/log` default logger). */
+  readonly logger?: Logger;
+  /** `logWith` used to push the trace context (default the `@ayepi/log` default `logWith`). */
+  readonly logWith?: <T>(add: object, inner: () => T) => T;
+  /**
+   * Observe an error thrown by the telemetry itself — your `extra` callback, a log call, or
+   * the context push. Telemetry is **fail-open**: such an error never breaks the request (the
+   * handler runs and its result/error are returned untouched); this hook just lets you notice.
+   * Off by default. It must not throw; if it does, the throw is ignored.
+   */
+  readonly onError?: (err: unknown) => void;
+  /** Clock for durations, in ms (default `Date.now`). Inject for deterministic tests. */
+  readonly now?: () => number;
+}
+/** Bind a {@link telemetry} def to its runtime behaviour. */
+declare function telemetryServer<M extends AnyMiddleware>(def: M, opts?: TelemetryServerOptions<M>): BoundMiddleware<M>;
+/**
+ * The {@link telemetry} def factory, augmented with a `.server(def, opts)` binder.
+ * Import from `@ayepi/otel/server` in your server entry to bind a def created in a
+ * frontend-safe spec.
+ */
+declare const telemetry: typeof telemetry$1 & {
+  server: typeof telemetryServer;
+};
+//#endregion
+export { PerCallOptions, RequestFieldFlags, ResponseFieldFlags, TelemetryServerOptions, telemetry };

package/dist/server.js

@@ -0,0 +1,272 @@
+import { telemetry as telemetry$1 } from "./index.js";
+import { ApiError } from "@ayepi/core";
+import { logWith, logger } from "@ayepi/log";
+import { randomUUID } from "node:crypto";
+//#region src/server.ts
+/** Fallback HTTP status when a thrown error is not an {@link ApiError}. */
+const DEFAULT_ERROR_STATUS = 500;
+/** Default success status for a plain-object / void handler result. */
+const DEFAULT_OK_STATUS = 200;
+/** Header carrying a caller-supplied request id (the default requestId source). */
+const REQUEST_ID_HEADER = "x-request-id";
+/** Default header name used when {@link TelemetryServerOptions.echoRequestId} is `true`. */
+const DEFAULT_ECHO_HEADER = "x-request-id";
+/** Header carrying the upstream client ip (checked before `X-Real-IP`). */
+const FORWARDED_FOR_HEADER = "x-forwarded-for";
+/** Header carrying the client ip when there is no proxy chain. */
+const REAL_IP_HEADER = "x-real-ip";
+/** Header carrying a distributed-trace id (W3C `traceparent` or a bare id). */
+const TRACE_HEADER = "x-trace-id";
+/** Header carrying the request body size in bytes. */
+const CONTENT_LENGTH_HEADER = "content-length";
+/** Default log level for the request/response lines. */
+const DEFAULT_LEVEL = "info";
+/** Default message for the request log line. */
+const DEFAULT_REQUEST_MSG = "request";
+/** Default message for the response log line. */
+const DEFAULT_RESPONSE_MSG = "response";
+const DEFAULT_CONTEXT_FIELDS = {
+	requestId: true,
+	method: true,
+	path: true
+};
+const DEFAULT_REQUEST_FIELDS = {
+	method: true,
+	path: true,
+	requestId: true
+};
+const DEFAULT_RESPONSE_FIELDS = {
+	status: true,
+	duration: true
+};
+/** Resolve the per-call config for a route, applying its {@link TelemetryServerOptions.overrides} entry (if any). */
+function resolveCall(base, overrides, routeName) {
+	const o = overrides?.[routeName];
+	const merged = o ? {
+		...base,
+		...o
+	} : base;
+	const request = merged.request;
+	const response = merged.response;
+	return {
+		name: merged.name,
+		level: merged.level,
+		contextFlags: merged.context ?? DEFAULT_CONTEXT_FIELDS,
+		requestFlags: request === false ? null : request ?? DEFAULT_REQUEST_FIELDS,
+		responseFlags: response === false ? null : response ?? DEFAULT_RESPONSE_FIELDS,
+		echoRequestId: merged.echoRequestId ?? false
+	};
+}
+/**
+* Resolve the request id. Precedence: caller `override(req)` → the ws **frame id**
+* (`io.ws.id`, the real per-call id) → `X-Request-ID` header → a generated UUID.
+*/
+function resolveRequestId(io, override) {
+	if (override) return override(io.req);
+	if (io.ws) return io.ws.id;
+	const header = io.req.headers.get(REQUEST_ID_HEADER);
+	if (header) return header;
+	return randomUUID();
+}
+/** First-hop client ip from `X-Forwarded-For`, else `X-Real-IP`, else `undefined`. */
+function resolveIp(req) {
+	const fwd = req.headers.get(FORWARDED_FOR_HEADER);
+	if (fwd) return fwd.split(",")[0].trim();
+	return req.headers.get(REAL_IP_HEADER) ?? void 0;
+}
+/** Body size in bytes from `Content-Length`, if present and numeric. */
+function resolveSize(req) {
+	const raw = req.headers.get(CONTENT_LENGTH_HEADER);
+	if (raw === null) return;
+	const n = Number(raw);
+	return Number.isFinite(n) ? n : void 0;
+}
+/** The method/path for a route — present for endpoints, absent for events. */
+function routeMethodPath(route) {
+	if (route.kind === "endpoint") return {
+		method: route.method,
+		path: route.path
+	};
+	return {
+		method: void 0,
+		path: void 0
+	};
+}
+/** Compute every candidate request field for this invocation. */
+function deriveRequest(io, name, override) {
+	const { method, path } = routeMethodPath(io.route);
+	return {
+		name,
+		requestId: resolveRequestId(io, override),
+		method,
+		path,
+		transport: io.transport,
+		ip: resolveIp(io.req),
+		size: resolveSize(io.req),
+		traceId: io.req.headers.get(TRACE_HEADER) ?? void 0
+	};
+}
+/** Pick the toggled-on request fields, dropping any that are `undefined`. */
+function pickRequest(derived, flags) {
+	const out = {};
+	if (flags.name) out.name = derived.name;
+	if (flags.requestId) out.requestId = derived.requestId;
+	if (flags.method && derived.method !== void 0) out.method = derived.method;
+	if (flags.path && derived.path !== void 0) out.path = derived.path;
+	if (flags.transport) out.transport = derived.transport;
+	if (flags.ip && derived.ip !== void 0) out.ip = derived.ip;
+	if (flags.size && derived.size !== void 0) out.size = derived.size;
+	if (flags.traceId && derived.traceId !== void 0) out.traceId = derived.traceId;
+	return out;
+}
+/** Inspect a successful handler result for status + type + (rarely) size. */
+function inspectResult(result) {
+	if (result instanceof Response) {
+		const len = result.headers.get(CONTENT_LENGTH_HEADER);
+		const n = len === null ? void 0 : Number(len);
+		return {
+			status: result.status,
+			type: "response",
+			size: n !== void 0 && Number.isFinite(n) ? n : void 0
+		};
+	}
+	if (isMultiStatus(result)) return {
+		status: result.status,
+		type: "multi",
+		size: void 0
+	};
+	if (isAsyncIterable(result)) return {
+		status: DEFAULT_OK_STATUS,
+		type: "stream",
+		size: void 0
+	};
+	if (result === void 0 || result === null) return {
+		status: DEFAULT_OK_STATUS,
+		type: "empty",
+		size: void 0
+	};
+	return {
+		status: DEFAULT_OK_STATUS,
+		type: "json",
+		size: void 0
+	};
+}
+/** True for a multi-status handler result of the shape `{ status, data }`. */
+function isMultiStatus(v) {
+	return typeof v === "object" && v !== null && typeof v.status === "number" && "data" in v;
+}
+/** True for an async-iterable handler result (a typed/raw stream). */
+function isAsyncIterable(v) {
+	return typeof v === "object" && v !== null && typeof v[Symbol.asyncIterator] === "function";
+}
+/** Build the response log fields for the success path. */
+function pickResponseOk(result, duration, flags) {
+	const { status, type, size } = inspectResult(result);
+	const out = {};
+	if (flags.status) out.status = status;
+	if (flags.duration) out.duration = duration;
+	if (flags.type) out.type = type;
+	if (flags.size && size !== void 0) out.size = size;
+	return out;
+}
+/** Build the non-error response fields for the error path (the raw error is logged separately). */
+function pickResponseErr(err, duration, flags) {
+	const status = err instanceof ApiError ? err.status : DEFAULT_ERROR_STATUS;
+	const fields = {};
+	if (flags.status) fields.status = status;
+	if (flags.duration) fields.duration = duration;
+	if (flags.type) fields.type = "error";
+	return fields;
+}
+/** Resolve the echo header name, or `null` when echoing is off. */
+function echoHeaderName(echo) {
+	if (echo === false) return null;
+	if (echo === true) return DEFAULT_ECHO_HEADER;
+	return echo;
+}
+/** Bind a {@link telemetry} def to its runtime behaviour. */
+function telemetryServer(def, opts = {}) {
+	const name = def.name;
+	const log = opts.logger ?? logger;
+	const wrap = opts.logWith ?? logWith;
+	const now = opts.now ?? Date.now;
+	const overrides = opts.overrides;
+	const base = {
+		name,
+		level: opts.level ?? DEFAULT_LEVEL,
+		context: opts.context,
+		request: opts.request,
+		response: opts.response,
+		echoRequestId: opts.echoRequestId
+	};
+	const safely = (fn) => {
+		try {
+			fn();
+		} catch (err) {
+			try {
+				opts.onError?.(err);
+			} catch {}
+		}
+	};
+	const run = (io) => {
+		const call = resolveCall(base, overrides, io.route.name);
+		const derived = deriveRequest(io, call.name, opts.requestId);
+		const echoHeader = echoHeaderName(call.echoRequestId);
+		if (echoHeader) io.setHeader(echoHeader, derived.requestId);
+		let extra = {};
+		safely(() => {
+			extra = opts.extra ? opts.extra(io.ctx, io.req) : {};
+		});
+		let ctxFields = { ...extra };
+		safely(() => {
+			ctxFields = {
+				...extra,
+				...pickRequest(derived, call.contextFlags)
+			};
+		});
+		const body = () => {
+			safely(() => {
+				if (call.requestFlags) log.log(call.level, DEFAULT_REQUEST_MSG, {
+					...extra,
+					...pickRequest(derived, call.requestFlags)
+				});
+			});
+			const start = now();
+			return io.next().then((result) => {
+				safely(() => {
+					if (call.responseFlags) log.log(call.level, DEFAULT_RESPONSE_MSG, pickResponseOk(result, now() - start, call.responseFlags));
+				});
+				return result;
+			}, (err) => {
+				safely(() => {
+					if (call.responseFlags) {
+						const fields = pickResponseErr(err, now() - start, call.responseFlags);
+						if (call.responseFlags.error) log.error(DEFAULT_RESPONSE_MSG, fields, err);
+						else log.error(DEFAULT_RESPONSE_MSG, fields);
+					}
+				});
+				throw err;
+			});
+		};
+		try {
+			return wrap(ctxFields, body);
+		} catch (err) {
+			safely(() => {
+				throw err;
+			});
+			return body();
+		}
+	};
+	return {
+		def,
+		impl: run
+	};
+}
+/**
+* The {@link telemetry} def factory, augmented with a `.server(def, opts)` binder.
+* Import from `@ayepi/otel/server` in your server entry to bind a def created in a
+* frontend-safe spec.
+*/
+const telemetry = Object.assign(telemetry$1, { server: telemetryServer });
+//#endregion
+export { telemetry };

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@ayepi/otel",
+  "version": "0.1.0",
+  "description": "Observability middleware for @ayepi/core — request/response logging, trace-context enrichment, configurable fields, and per-endpoint overrides",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ClickerMonkey/ayepi.git",
+    "directory": "packages/otel"
+  },
+  "homepage": "https://github.com/ClickerMonkey/ayepi/tree/main/packages/otel#readme",
+  "bugs": {
+    "url": "https://github.com/ClickerMonkey/ayepi/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./server": {
+      "import": {
+        "types": "./dist/server.d.ts",
+        "default": "./dist/server.js"
+      },
+      "require": {
+        "types": "./dist/server.d.cts",
+        "default": "./dist/server.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "@ayepi/core": "^0.1.0",
+    "@ayepi/log": "^0.1.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.1.8",
+    "publint": "^0.3.0",
+    "tsdown": "^0.12.0",
+    "vitest": "^2.1.8",
+    "zod": "^4.4.3",
+    "@ayepi/core": "0.1.0",
+    "@ayepi/log": "0.1.0"
+  },
+  "keywords": [
+    "ayepi",
+    "observability",
+    "logging",
+    "telemetry",
+    "tracing",
+    "middleware"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --coverage",
+    "publint": "publint"
+  }
+}