pi-crew 0.2.2 → 0.2.4

package/src/observability/event-to-metric.ts

@@ -1,68 +1,68 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { MetricRegistry } from "./metric-registry.ts";
-
-function recordValue(value: unknown): Record<string, unknown> {
-	return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
-}
-
-function stringValue(value: unknown, fallback: string): string {
-	return typeof value === "string" && value.length > 0 ? value : fallback;
-}
-
-function numberValue(value: unknown, fallback = 0): number {
-	return typeof value === "number" && Number.isFinite(value) ? value : fallback;
-}
-
-const CANCELLATION_REASON_LABELS = new Set(["caller_cancelled", "leader_interrupted", "provider_timeout", "worker_timeout", "tool_timeout", "shutdown", "unknown"]);
-
-function cancellationReasonLabel(value: unknown): string {
-	const raw = stringValue(value, "unknown");
-	return CANCELLATION_REASON_LABELS.has(raw) ? raw : "unknown";
-}
-
-export interface EventToMetricSubscription {
-	dispose(): void;
-}
-
-export function wireEventToMetrics(events: ExtensionAPI["events"] | undefined, registry: MetricRegistry): EventToMetricSubscription {
-	const runCount = registry.counter("crew.run.count", "Total runs by status");
-	const taskCount = registry.counter("crew.task.count", "Total tasks by status");
-	const subagentCount = registry.counter("crew.subagent.count", "Total subagent records by status");
-	const mailboxCount = registry.counter("crew.mailbox.count", "Total mailbox messages by direction");
-	const retryAttemptCount = registry.counter("crew.task.retry_attempt_total", "Retry attempts by run and task");
-	const deadletterCount = registry.counter("crew.task.deadletter_total", "Deadletter triggers by reason");
-	const overflowCount = registry.counter("crew.task.overflow_phase_total", "Overflow recovery phase transitions");
-	const waitingCount = registry.counter("crew.task.waiting_total", "Tasks entering waiting state");
-	const supervisorContactCount = registry.counter("crew.task.supervisor_contact_total", "Supervisor contact requests by reason");
-	registry.gauge("crew.heartbeat.staleness_ms", "Heartbeat elapsed since last seen, milliseconds");
-	const runDuration = registry.histogram("crew.run.duration_ms", "Run end-to-end duration, milliseconds");
-	const taskDuration = registry.histogram("crew.task.duration_ms", "Task duration, milliseconds");
-	registry.histogram("crew.task.retry_count", "Retries per task", [0, 1, 2, 3, 5, 10]);
-	const tokenUsage = registry.histogram("crew.task.tokens_total", "Token usage per task");
-
-	const handlers: Array<[string, (data: unknown) => void]> = [
-		["crew.run.completed", (data) => { const item = recordValue(data); runCount.inc({ status: "completed" }); runDuration.observe({ team: stringValue(item.team, "unknown") }, numberValue(item.durationMs)); }],
-		["crew.run.failed", () => runCount.inc({ status: "failed" })],
-		["crew.run.cancelled", (data) => { const item = recordValue(data); runCount.inc({ status: "cancelled", reason: cancellationReasonLabel(item.reason) }); }],
-		["crew.task.completed", (data) => { const item = recordValue(data); taskCount.inc({ status: "completed" }); taskDuration.observe({ role: stringValue(item.role, "unknown") }, numberValue(item.durationMs)); tokenUsage.observe({ role: stringValue(item.role, "unknown") }, numberValue(item.tokens)); }],
-		["crew.task.failed", () => taskCount.inc({ status: "failed" })],
-		["crew.task.retry_attempt", (data) => { const item = recordValue(data); taskCount.inc({ status: "retry" }); retryAttemptCount.inc({ runId: stringValue(item.runId, "unknown"), taskId: stringValue(item.taskId, "unknown") }); }],
-		["crew.task.deadletter", (data) => { const item = recordValue(data); deadletterCount.inc({ reason: stringValue(item.reason, "unknown") }); }],
-		["crew.task.overflow", (data) => { const item = recordValue(data); overflowCount.inc({ phase: stringValue(item.phase, "unknown"), previous_phase: stringValue(item.previousPhase, "none") }); }],
-		["task.waiting", (data) => { const item = recordValue(data); waitingCount.inc({ taskId: stringValue(item.taskId, "unknown"), runId: stringValue(item.runId, "unknown") }); }],
-		["supervisor.contact", (data) => { const item = recordValue(data); supervisorContactCount.inc({ reason: stringValue(item.reason, "unknown"), taskId: stringValue(item.taskId, "unknown") }); }],
-		["crew.subagent.completed", (data) => { const item = recordValue(data); subagentCount.inc({ status: stringValue(item.status, "completed") }); }],
-		["crew.subagent.failed", () => subagentCount.inc({ status: "failed" })],
-		["crew.mailbox.message", (data) => { const item = recordValue(data); mailboxCount.inc({ direction: stringValue(item.direction, "unknown") }); }],
-	];
-
-	const unsubscribers: Array<() => void> = [];
-	for (const [event, handler] of handlers) {
-		const unsubscribe = events?.on?.(event, (data: unknown) => {
-			try { handler(data); } catch { /* metric handlers must never break event delivery */ }
-		});
-		if (typeof unsubscribe === "function") unsubscribers.push(unsubscribe);
-	}
-	let disposed = false;
-	return { dispose() { if (disposed) return; disposed = true; for (const unsubscribe of unsubscribers.splice(0)) unsubscribe(); } };
-}
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { MetricRegistry } from "./metric-registry.ts";
+
+function recordValue(value: unknown): Record<string, unknown> {
+	return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+function stringValue(value: unknown, fallback: string): string {
+	return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+
+function numberValue(value: unknown, fallback = 0): number {
+	return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+const CANCELLATION_REASON_LABELS = new Set(["caller_cancelled", "leader_interrupted", "provider_timeout", "worker_timeout", "tool_timeout", "shutdown", "unknown"]);
+
+function cancellationReasonLabel(value: unknown): string {
+	const raw = stringValue(value, "unknown");
+	return CANCELLATION_REASON_LABELS.has(raw) ? raw : "unknown";
+}
+
+export interface EventToMetricSubscription {
+	dispose(): void;
+}
+
+export function wireEventToMetrics(events: ExtensionAPI["events"] | undefined, registry: MetricRegistry): EventToMetricSubscription {
+	const runCount = registry.counter("crew.run.count", "Total runs by status");
+	const taskCount = registry.counter("crew.task.count", "Total tasks by status");
+	const subagentCount = registry.counter("crew.subagent.count", "Total subagent records by status");
+	const mailboxCount = registry.counter("crew.mailbox.count", "Total mailbox messages by direction");
+	const retryAttemptCount = registry.counter("crew.task.retry_attempt_total", "Retry attempts by run and task");
+	const deadletterCount = registry.counter("crew.task.deadletter_total", "Deadletter triggers by reason");
+	const overflowCount = registry.counter("crew.task.overflow_phase_total", "Overflow recovery phase transitions");
+	const waitingCount = registry.counter("crew.task.waiting_total", "Tasks entering waiting state");
+	const supervisorContactCount = registry.counter("crew.task.supervisor_contact_total", "Supervisor contact requests by reason");
+	registry.gauge("crew.heartbeat.staleness_ms", "Heartbeat elapsed since last seen, milliseconds");
+	const runDuration = registry.histogram("crew.run.duration_ms", "Run end-to-end duration, milliseconds", [1000, 5000, 15000, 30000, 60000, 300000, 600000, 1800000]);
+	const taskDuration = registry.histogram("crew.task.duration_ms", "Task duration, milliseconds", [50, 200, 500, 1000, 5000, 30000, 120000]);
+	registry.histogram("crew.task.retry_count", "Retries per task", [0, 1, 2, 3, 5, 10]);
+	const tokenUsage = registry.histogram("crew.task.tokens_total", "Token usage per task", [100, 500, 2000, 10000, 50000, 200000]);
+
+	const handlers: Array<[string, (data: unknown) => void]> = [
+		["crew.run.completed", (data) => { const item = recordValue(data); runCount.inc({ status: "completed" }); runDuration.observe({ team: stringValue(item.team, "unknown") }, numberValue(item.durationMs)); }],
+		["crew.run.failed", () => runCount.inc({ status: "failed" })],
+		["crew.run.cancelled", (data) => { const item = recordValue(data); runCount.inc({ status: "cancelled", reason: cancellationReasonLabel(item.reason) }); }],
+		["crew.task.completed", (data) => { const item = recordValue(data); taskCount.inc({ status: "completed" }); taskDuration.observe({ role: stringValue(item.role, "unknown") }, numberValue(item.durationMs)); tokenUsage.observe({ role: stringValue(item.role, "unknown") }, numberValue(item.tokens)); }],
+		["crew.task.failed", () => taskCount.inc({ status: "failed" })],
+		["crew.task.retry_attempt", (data) => { const item = recordValue(data); taskCount.inc({ status: "retry" }); retryAttemptCount.inc({ runId: stringValue(item.runId, "unknown"), taskId: stringValue(item.taskId, "unknown") }); }],
+		["crew.task.deadletter", (data) => { const item = recordValue(data); deadletterCount.inc({ reason: stringValue(item.reason, "unknown") }); }],
+		["crew.task.overflow", (data) => { const item = recordValue(data); overflowCount.inc({ phase: stringValue(item.phase, "unknown"), previous_phase: stringValue(item.previousPhase, "none") }); }],
+		["task.waiting", (data) => { const item = recordValue(data); waitingCount.inc({ taskId: stringValue(item.taskId, "unknown"), runId: stringValue(item.runId, "unknown") }); }],
+		["supervisor.contact", (data) => { const item = recordValue(data); supervisorContactCount.inc({ reason: stringValue(item.reason, "unknown"), taskId: stringValue(item.taskId, "unknown") }); }],
+		["crew.subagent.completed", (data) => { const item = recordValue(data); subagentCount.inc({ status: stringValue(item.status, "completed") }); }],
+		["crew.subagent.failed", () => subagentCount.inc({ status: "failed" })],
+		["crew.mailbox.message", (data) => { const item = recordValue(data); mailboxCount.inc({ direction: stringValue(item.direction, "unknown") }); }],
+	];
+
+	const unsubscribers: Array<() => void> = [];
+	for (const [event, handler] of handlers) {
+		const unsubscribe = events?.on?.(event, (data: unknown) => {
+			try { handler(data); } catch { /* metric handlers must never break event delivery */ }
+		});
+		if (typeof unsubscribe === "function") unsubscribers.push(unsubscribe);
+	}
+	let disposed = false;
+	return { dispose() { if (disposed) return; disposed = true; for (const unsubscribe of unsubscribers.splice(0)) unsubscribe(); } };
+}

package/src/observability/exporters/adapter.ts

@@ -1,30 +1,30 @@
-import type { MetricSnapshot } from "../metrics-primitives.ts";
-
-export interface MetricExporter {
-	name: string;
-	push(snapshots: MetricSnapshot[]): Promise<void>;
-	dispose(): void;
-}
-
-export class CompositeExporter implements MetricExporter {
-	name = "composite";
-	private readonly exporters: MetricExporter[];
-
-	constructor(exporters: MetricExporter[]) {
-		this.exporters = exporters;
-	}
-
-	async push(snapshots: MetricSnapshot[]): Promise<void> {
-		await Promise.allSettled(this.exporters.map((exporter) => exporter.push(snapshots)));
-	}
-
-	dispose(): void {
-		for (const exporter of this.exporters) {
-			try {
-				exporter.dispose();
-			} catch {
-				// Best-effort cleanup; one exporter failing shouldn't prevent others.
-			}
-		}
-	}
-}
+import type { MetricSnapshot } from "../metrics-primitives.ts";
+
+export interface MetricExporter {
+	name: string;
+	push(snapshots: MetricSnapshot[]): Promise<void>;
+	dispose(): void;
+}
+
+export class CompositeExporter implements MetricExporter {
+	name = "composite";
+	private readonly exporters: MetricExporter[];
+
+	constructor(exporters: MetricExporter[]) {
+		this.exporters = exporters;
+	}
+
+	async push(snapshots: MetricSnapshot[]): Promise<void> {
+		await Promise.allSettled(this.exporters.map((exporter) => exporter.push(snapshots)));
+	}
+
+	dispose(): void {
+		for (const exporter of this.exporters) {
+			try {
+				exporter.dispose();
+			} catch {
+				// Best-effort cleanup; one exporter failing shouldn't prevent others.
+			}
+		}
+	}
+}

package/src/observability/exporters/otlp-exporter.ts

@@ -1,92 +1,106 @@
-import { logInternalError } from "../../utils/internal-error.ts";
-import { redactSecrets } from "../../utils/redaction.ts";
-import type { MetricRegistry } from "../metric-registry.ts";
-import type { MetricSnapshot } from "../metrics-primitives.ts";
-import type { MetricExporter } from "./adapter.ts";
-
-export interface OTLPExporterOptions {
-	endpoint: string;
-	headers?: Record<string, string>;
-	intervalMs?: number;
-	timeoutMs?: number;
-}
-
-function pointValues(snapshot: MetricSnapshot): unknown[] {
-	const MAX_LABEL_LENGTH = 256;
-	if (snapshot.type === "histogram") {
-		return snapshot.values.map((value) => ({
-			attributes: Object.entries(value.labels).map(([key, item]) => {
-				const redacted = redactSecrets({ [key]: item }) as Record<string, string>;
-				const val = String(redacted[key] ?? item);
-				return { key, value: { stringValue: val.length > MAX_LABEL_LENGTH ? val.slice(0, MAX_LABEL_LENGTH) : val } };
-			}),
-			count: "count" in value ? value.count : undefined,
-			sum: "sum" in value ? value.sum : undefined,
-			bucketCounts: "counts" in value ? value.counts : undefined,
-			explicitBounds: "buckets" in value ? value.buckets : undefined,
-		}));
-	}
-	return snapshot.values.map((value) => ({
-		attributes: Object.entries(value.labels).map(([key, item]) => {
-			const redacted = redactSecrets({ [key]: item }) as Record<string, string>;
-			const val = String(redacted[key] ?? item);
-			return { key, value: { stringValue: val.length > MAX_LABEL_LENGTH ? val.slice(0, MAX_LABEL_LENGTH) : val } };
-		}),
-		asDouble: "value" in value ? value.value : undefined,
-		count: "count" in value ? value.count : undefined,
-		sum: "sum" in value ? value.sum : undefined,
-	}));
-}
-
-export function convertToOTLP(snapshots: MetricSnapshot[]): unknown {
-	return {
-		resourceMetrics: [{
-			resource: { attributes: [{ key: "service.name", value: { stringValue: "pi-crew" } }] },
-			scopeMetrics: [{
-				scope: { name: "pi-crew" },
-				metrics: snapshots.map((snapshot) => ({ name: snapshot.name, description: snapshot.description, [snapshot.type === "histogram" ? "histogram" : snapshot.type === "gauge" ? "gauge" : "sum"]: { dataPoints: pointValues(snapshot) } })),
-			}],
-		}],
-	};
-}
-
-export class OTLPExporter implements MetricExporter {
-	name = "otlp";
-	private timer?: ReturnType<typeof setInterval>;
-	private readonly opts: OTLPExporterOptions;
-	private readonly registry: MetricRegistry;
-
-	constructor(opts: OTLPExporterOptions, registry: MetricRegistry) {
-		this.opts = opts;
-		this.registry = registry;
-	}
-
-	start(): void {
-		this.dispose();
-		this.timer = setInterval(() => { void this.push(this.registry.snapshot()); }, this.opts.intervalMs ?? 60_000);
-		this.timer.unref();
-	}
-
-	async push(snapshots: MetricSnapshot[]): Promise<void> {
-		try {
-			const timeoutMs = this.opts.timeoutMs ?? 10_000;
-			const controller = new AbortController();
-			const timer = setTimeout(() => controller.abort(), timeoutMs);
-			try {
-				const response = await fetch(this.opts.endpoint, { method: "POST", headers: { "content-type": "application/json", ...(this.opts.headers ?? {}) }, body: JSON.stringify(convertToOTLP(snapshots)), signal: controller.signal });
-				if (!response.ok) {
-					logInternalError("otlp-export-http", new Error(`HTTP ${response.status}: ${response.statusText}`), `endpoint=${this.opts.endpoint}`);
-				}
-			} finally {
-				clearTimeout(timer);
-			}
-		} catch (error) {
-			logInternalError("otlp-export", error);
-		}
-	}
-
-	dispose(): void {
-		if (this.timer) clearInterval(this.timer);
-		this.timer = undefined;
-	}
-}
+import { gzip } from "node:zlib";
+import { promisify } from "node:util";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { redactSecrets } from "../../utils/redaction.ts";
+import type { MetricRegistry } from "../metric-registry.ts";
+import type { MetricSnapshot } from "../metrics-primitives.ts";
+import type { MetricExporter } from "./adapter.ts";
+
+const gzipAsync = promisify(gzip);
+
+export interface OTLPExporterOptions {
+	endpoint: string;
+	headers?: Record<string, string>;
+	intervalMs?: number;
+	timeoutMs?: number;
+}
+
+function pointValues(snapshot: MetricSnapshot): unknown[] {
+	const MAX_LABEL_LENGTH = 256;
+	if (snapshot.type === "histogram") {
+		return snapshot.values.map((value) => ({
+			attributes: Object.entries(value.labels).map(([key, item]) => {
+				const redacted = redactSecrets({ [key]: item }) as Record<string, string>;
+				const val = String(redacted[key] ?? item);
+				return { key, value: { stringValue: val.length > MAX_LABEL_LENGTH ? val.slice(0, MAX_LABEL_LENGTH) : val } };
+			}),
+			count: "count" in value ? value.count : undefined,
+			sum: "sum" in value ? value.sum : undefined,
+			bucketCounts: "counts" in value ? value.counts : undefined,
+			explicitBounds: "buckets" in value ? value.buckets : undefined,
+		}));
+	}
+	return snapshot.values.map((value) => ({
+		attributes: Object.entries(value.labels).map(([key, item]) => {
+			const redacted = redactSecrets({ [key]: item }) as Record<string, string>;
+			const val = String(redacted[key] ?? item);
+			return { key, value: { stringValue: val.length > MAX_LABEL_LENGTH ? val.slice(0, MAX_LABEL_LENGTH) : val } };
+		}),
+		asDouble: "value" in value ? value.value : undefined,
+		count: "count" in value ? value.count : undefined,
+		sum: "sum" in value ? value.sum : undefined,
+	}));
+}
+
+export function convertToOTLP(snapshots: MetricSnapshot[]): unknown {
+	return {
+		resourceMetrics: [{
+			resource: { attributes: [{ key: "service.name", value: { stringValue: "pi-crew" } }] },
+			scopeMetrics: [{
+				scope: { name: "pi-crew" },
+				metrics: snapshots.map((snapshot) => ({ name: snapshot.name, description: snapshot.description, [snapshot.type === "histogram" ? "histogram" : snapshot.type === "gauge" ? "gauge" : "sum"]: { dataPoints: pointValues(snapshot) } })),
+			}],
+		}],
+	};
+}
+
+export class OTLPExporter implements MetricExporter {
+	name = "otlp";
+	private timer?: ReturnType<typeof setInterval>;
+	private readonly opts: OTLPExporterOptions;
+	private readonly registry: MetricRegistry;
+
+	constructor(opts: OTLPExporterOptions, registry: MetricRegistry) {
+		this.opts = opts;
+		this.registry = registry;
+	}
+
+	start(): void {
+		this.dispose();
+		this.timer = setInterval(() => { void this.push(this.registry.snapshot()); }, this.opts.intervalMs ?? 60_000);
+		this.timer.unref();
+	}
+
+	async push(snapshots: MetricSnapshot[]): Promise<void> {
+		try {
+			const timeoutMs = this.opts.timeoutMs ?? 10_000;
+			const controller = new AbortController();
+			const timer = setTimeout(() => controller.abort(), timeoutMs);
+			try {
+				// 4.2: gzip body. OTLP HTTP exporters of every flavour accept
+				// `content-encoding: gzip`; collectors expect uncompressed JSON
+				// otherwise. Saves bandwidth on metric-heavy runs (often 3-5x).
+				const json = JSON.stringify(convertToOTLP(snapshots));
+				const body = await gzipAsync(Buffer.from(json));
+				const response = await fetch(this.opts.endpoint, {
+					method: "POST",
+					headers: { "content-type": "application/json", "content-encoding": "gzip", ...(this.opts.headers ?? {}) },
+					body,
+					signal: controller.signal,
+				});
+				if (!response.ok) {
+					logInternalError("otlp-export-http", new Error(`HTTP ${response.status}: ${response.statusText}`), `endpoint=${this.opts.endpoint}`);
+				}
+			} finally {
+				clearTimeout(timer);
+			}
+		} catch (error) {
+			logInternalError("otlp-export", error);
+		}
+	}
+
+	dispose(): void {
+		if (this.timer) clearInterval(this.timer);
+		this.timer = undefined;
+	}
+}

package/src/observability/exporters/prometheus-exporter.ts

@@ -1,54 +1,54 @@
-import type { HistogramPoint, MetricLabels, MetricPoint, MetricSnapshot } from "../metrics-primitives.ts";
-
-function prometheusName(name: string): string {
-	return name.replace(/[^a-zA-Z0-9_:]/g, "_").replace(/^[0-9]/, "_$&");
-}
-
-function escapeLabel(value: string): string {
-	return value.replace(/\\/g, "\\\\").replace(/\n/g, "\\n").replace(/"/g, "\\\"");
-}
-
-function labelsText(labels: MetricLabels): string {
-	const entries = Object.entries(labels);
-	if (!entries.length) return "";
-	return `{${entries.map(([key, value]) => `${key}="${escapeLabel(String(value))}"`).join(",")}}`;
-}
-
-function metricType(type: MetricSnapshot["type"]): string {
-	return type === "histogram" ? "histogram" : type === "gauge" ? "gauge" : "counter";
-}
-
-function isHistogramPoint(value: MetricPoint | HistogramPoint): value is HistogramPoint {
-	return "buckets" in value && "counts" in value;
-}
-
-function formatPrometheusValue(num: number): string {
-	if (Number.isNaN(num)) return "Nan";
-	if (num === Number.POSITIVE_INFINITY) return "+Inf";
-	if (num === Number.NEGATIVE_INFINITY) return "-Inf";
-	return String(num);
-}
-
-export function formatPrometheus(snapshots: MetricSnapshot[]): string {
-	const lines: string[] = [];
-	for (const snapshot of snapshots) {
-		const name = prometheusName(snapshot.name);
-		lines.push(`# HELP ${name} ${snapshot.description}`);
-		lines.push(`# TYPE ${name} ${metricType(snapshot.type)}`);
-		for (const value of snapshot.values) {
-			if (isHistogramPoint(value)) {
-				let cumulative = 0;
-				for (let index = 0; index < value.buckets.length; index += 1) {
-					cumulative += value.counts[index] ?? 0;
-					const le = Number.isFinite(value.buckets[index]) ? String(value.buckets[index]) : "+Inf";
-					lines.push(`${name}_bucket${labelsText({ ...value.labels, le })} ${cumulative}`);
-				}
-				lines.push(`${name}_sum${labelsText(value.labels)} ${value.sum}`);
-				lines.push(`${name}_count${labelsText(value.labels)} ${value.count}`);
-			} else {
-				lines.push(`${name}${labelsText(value.labels)} ${formatPrometheusValue(value.value)}`);
-			}
-		}
-	}
-	return `${lines.join("\n")}\n`;
-}
+import type { HistogramPoint, MetricLabels, MetricPoint, MetricSnapshot } from "../metrics-primitives.ts";
+
+function prometheusName(name: string): string {
+	return name.replace(/[^a-zA-Z0-9_:]/g, "_").replace(/^[0-9]/, "_$&");
+}
+
+function escapeLabel(value: string): string {
+	return value.replace(/\\/g, "\\\\").replace(/\n/g, "\\n").replace(/"/g, "\\\"");
+}
+
+function labelsText(labels: MetricLabels): string {
+	const entries = Object.entries(labels);
+	if (!entries.length) return "";
+	return `{${entries.map(([key, value]) => `${key}="${escapeLabel(String(value))}"`).join(",")}}`;
+}
+
+function metricType(type: MetricSnapshot["type"]): string {
+	return type === "histogram" ? "histogram" : type === "gauge" ? "gauge" : "counter";
+}
+
+function isHistogramPoint(value: MetricPoint | HistogramPoint): value is HistogramPoint {
+	return "buckets" in value && "counts" in value;
+}
+
+function formatPrometheusValue(num: number): string {
+	if (Number.isNaN(num)) return "Nan";
+	if (num === Number.POSITIVE_INFINITY) return "+Inf";
+	if (num === Number.NEGATIVE_INFINITY) return "-Inf";
+	return String(num);
+}
+
+export function formatPrometheus(snapshots: MetricSnapshot[]): string {
+	const lines: string[] = [];
+	for (const snapshot of snapshots) {
+		const name = prometheusName(snapshot.name);
+		lines.push(`# HELP ${name} ${snapshot.description}`);
+		lines.push(`# TYPE ${name} ${metricType(snapshot.type)}`);
+		for (const value of snapshot.values) {
+			if (isHistogramPoint(value)) {
+				let cumulative = 0;
+				for (let index = 0; index < value.buckets.length; index += 1) {
+					cumulative += value.counts[index] ?? 0;
+					const le = Number.isFinite(value.buckets[index]) ? String(value.buckets[index]) : "+Inf";
+					lines.push(`${name}_bucket${labelsText({ ...value.labels, le })} ${cumulative}`);
+				}
+				lines.push(`${name}_sum${labelsText(value.labels)} ${value.sum}`);
+				lines.push(`${name}_count${labelsText(value.labels)} ${value.count}`);
+			} else {
+				lines.push(`${name}${labelsText(value.labels)} ${formatPrometheusValue(value.value)}`);
+			}
+		}
+	}
+	return `${lines.join("\n")}\n`;
+}