feat(telemetry): add OTLP export writer

.prettierignore

@@ -9,4 +9,7 @@
 flake.lock
 pnpm-debug.log
 pnpm-lock.yaml
-/storybook-static/
+/storybook-static/
+
+# Golden snapshots are written verbatim; prettier would drift them out of sync.
+**/__golden__/

package.json

@@ -676,6 +676,8 @@
 	],
 	"dependencies": {
 		"@abraham/reflection": "^0.13.0",
+		"@opentelemetry/api": "^1.9.1",
+		"@opentelemetry/api-logs": "^0.218.0",
 		"@peculiar/x509": "^2.0.0",
 		"@repo/shared": "workspace:*",
 		"axios": "^1.16.1",

src/error/errorUtils.ts

@@ -23,3 +23,10 @@ export const getErrorDetail = (error: unknown): string | undefined | null => {
 export function toError(value: unknown, defaultMsg?: string): Error {
 	return baseToError(value, defaultMsg, util.inspect);
 }
+
+/** Wrap `cause` as `Failed to <verb> <target>: <cause.message>`, preserving the chain. */
+export function wrapError(verb: string, target: string, cause: unknown): Error {
+	return new Error(`Failed to ${verb} ${target}: ${toError(cause).message}`, {
+		cause,
+	});
+}

src/telemetry/export/metrics.ts

@@ -0,0 +1,77 @@
+import type { TelemetryEvent } from "../event";
+
+export interface MetricMeasurement {
+	readonly name: string;
+	readonly value: number;
+	readonly kind: "gauge" | "counter";
+	/** OTel/UCUM unit (e.g. "ms", "Mbit/s", "{request}", "1"). */
+	readonly unit: string;
+}
+
+/**
+ * `windowSeconds` is set on windowed events (`http.requests`) and absent on
+ * point-in-time samples; exporters use it to stamp gauge start times and
+ * anchor cumulative counters.
+ */
+export interface MetricDescriptor {
+	readonly windowSeconds?: number;
+	readonly measurements: readonly MetricMeasurement[];
+}
+
+const METRIC_EVENT_NAMES: ReadonlySet<string> = new Set([
+	"http.requests",
+	"ssh.network.sampled",
+]);
+
+const UNIT_SUFFIXES: ReadonlyArray<readonly [string, string]> = [
+	["_ms", "ms"],
+	["Ms", "ms"],
+	["Mbits", "Mbit/s"],
+];
+
+export function isMetricEvent(event: TelemetryEvent): boolean {
+	return METRIC_EVENT_NAMES.has(event.eventName);
+}
+
+export function describeMetricEvent(
+	event: TelemetryEvent,
+): MetricDescriptor | undefined {
+	if (!isMetricEvent(event)) {
+		return undefined;
+	}
+	if (event.eventName === "http.requests") {
+		return describeHttpRequests(event);
+	}
+	return {
+		measurements: Object.entries(event.measurements).map(([name, value]) => ({
+			name,
+			value,
+			kind: "gauge",
+			unit: measurementUnit(name),
+		})),
+	};
+}
+
+function describeHttpRequests(event: TelemetryEvent): MetricDescriptor {
+	let windowSeconds = 0;
+	const measurements: MetricMeasurement[] = [];
+	for (const [name, value] of Object.entries(event.measurements)) {
+		if (name === "window_seconds") {
+			windowSeconds = value;
+		} else if (name.startsWith("count.")) {
+			measurements.push({ name, value, kind: "counter", unit: "{request}" });
+		} else {
+			measurements.push({
+				name,
+				value,
+				kind: "gauge",
+				unit: measurementUnit(name),
+			});
+		}
+	}
+	return { windowSeconds, measurements };
+}
+
+function measurementUnit(name: string): string {
+	return UNIT_SUFFIXES.find(([suffix]) => name.endsWith(suffix))?.[1] ?? "1";
+}

src/telemetry/export/writers/otlp/envelope.ts

@@ -0,0 +1,77 @@
+import { createWriteStream } from "node:fs";
+
+import { wrapError } from "../../../../error/errorUtils";
+
+/** `append` is not re-entrant. */
+export interface EnvelopeFile {
+	append(value: unknown): Promise<void>;
+	close(): Promise<void>;
+}
+
+/** Streams `<prefix>v1,v2,...<suffix>` JSON into `filePath`. */
+export async function openEnvelopeFile(
+	filePath: string,
+	prefix: string,
+	suffix: string,
+): Promise<EnvelopeFile> {
+	const stream = createWriteStream(filePath, { encoding: "utf8" });
+	// Open failures (ENOENT/EACCES) surface as 'error' events, not write
+	// callbacks; capture them so pending operations reject instead of hanging.
+	const errRef: { current?: Error } = {};
+	stream.once("error", (err) => {
+		errRef.current ??= err;
+	});
+
+	const awaitOp = (op: (cb: (err?: Error | null) => void) => void) =>
+		new Promise<void>((resolve, reject) => {
+			if (errRef.current) {
+				reject(errRef.current);
+				return;
+			}
+			op((err) => {
+				const failure = err ?? errRef.current;
+				if (failure) {
+					reject(failure);
+				} else {
+					resolve();
+				}
+			});
+		});
+
+	const writeChunk = (chunk: string) =>
+		awaitOp((cb) => stream.write(chunk, "utf8", cb));
+
+	try {
+		await writeChunk(prefix);
+	} catch (err) {
+		stream.destroy();
+		throw wrapError("write", filePath, err);
+	}
+	let written = 0;
+	let closed = false;
+	return {
+		async append(value) {
+			try {
+				await writeChunk((written === 0 ? "" : ",") + JSON.stringify(value));
+			} catch (err) {
+				throw wrapError("write", filePath, err);
+			}
+			written += 1;
+		},
+		async close() {
+			if (closed) {
+				return;
+			}
+			closed = true;
+			try {
+				await writeChunk(suffix);
+				await awaitOp((cb) => stream.end(cb));
+			} catch (err) {
+				// destroy() never throws synchronously, so it can't mask the
+				// rethrown error; any teardown failure routes to the 'error' event.
+				stream.destroy();
+				throw wrapError("close", filePath, err);
+			}
+		},
+	};
+}