pi-crew 0.2.2 → 0.2.4

package/src/observability/metric-registry.ts

@@ -1,87 +1,87 @@
-import { Counter, Gauge, Histogram, type Metric, type MetricSnapshot } from "./metrics-primitives.ts";
-
-const METRIC_NAME_PATTERN = /^crew\.[a-z]+\.[a-z][a-z_]*$/;
-
-function assertMetricName(name: string): void {
-	if (!METRIC_NAME_PATTERN.test(name)) throw new Error(`Invalid metric name '${name}'. Expected crew.<domain>.<measure>.`);
-}
-
-export class MetricRegistry {
-	private metrics = new Map<string, Metric>();
-
-	registerCounter(name: string, description: string): Counter {
-		assertMetricName(name);
-		if (this.metrics.has(name)) throw new Error(`Metric '${name}' is already registered.`);
-		const metric = new Counter(name, description);
-		this.metrics.set(name, metric);
-		return metric;
-	}
-
-	registerGauge(name: string, description: string): Gauge {
-		assertMetricName(name);
-		if (this.metrics.has(name)) throw new Error(`Metric '${name}' is already registered.`);
-		const metric = new Gauge(name, description);
-		this.metrics.set(name, metric);
-		return metric;
-	}
-
-	registerHistogram(name: string, description: string, buckets?: number[]): Histogram {
-		assertMetricName(name);
-		if (this.metrics.has(name)) throw new Error(`Metric '${name}' is already registered.`);
-		const metric = new Histogram(name, description, buckets);
-		this.metrics.set(name, metric);
-		return metric;
-	}
-
-	counter(name: string, description: string): Counter {
-		const existing = this.metrics.get(name);
-		if (existing instanceof Counter) {
-			if (existing.description !== description) {
-				process.stderr.write(`[pi-crew] metric-registry: counter '${name}' description changed; using original: '${existing.description}'\n`);
-			}
-			return existing;
-		}
-		if (existing) throw new Error(`Metric '${name}' is not a counter.`);
-		return this.registerCounter(name, description);
-	}
-
-	gauge(name: string, description: string): Gauge {
-		const existing = this.metrics.get(name);
-		if (existing instanceof Gauge) {
-			if (existing.description !== description) {
-				process.stderr.write(`[pi-crew] metric-registry: gauge '${name}' description changed; using original: '${existing.description}'\n`);
-			}
-			return existing;
-		}
-		if (existing) throw new Error(`Metric '${name}' is not a gauge.`);
-		return this.registerGauge(name, description);
-	}
-
-	histogram(name: string, description: string, buckets?: number[]): Histogram {
-		const existing = this.metrics.get(name);
-		if (existing instanceof Histogram) {
-			if (existing.description !== description) {
-				process.stderr.write(`[pi-crew] metric-registry: histogram '${name}' description changed; using original: '${existing.description}'\n`);
-			}
-			return existing;
-		}
-		if (existing) throw new Error(`Metric '${name}' is not a histogram.`);
-		return this.registerHistogram(name, description, buckets);
-	}
-
-	get(name: string): Metric | undefined {
-		return this.metrics.get(name);
-	}
-
-	snapshot(): MetricSnapshot[] {
-		return [...this.metrics.values()].map((metric) => metric.snapshot());
-	}
-
-	dispose(): void {
-		this.metrics.clear();
-	}
-}
-
-export function createMetricRegistry(): MetricRegistry {
-	return new MetricRegistry();
-}
+import { Counter, Gauge, Histogram, type Metric, type MetricSnapshot } from "./metrics-primitives.ts";
+
+const METRIC_NAME_PATTERN = /^crew\.[a-z]+\.[a-z][a-z_]*$/;
+
+function assertMetricName(name: string): void {
+	if (!METRIC_NAME_PATTERN.test(name)) throw new Error(`Invalid metric name '${name}'. Expected crew.<domain>.<measure>.`);
+}
+
+export class MetricRegistry {
+	private metrics = new Map<string, Metric>();
+
+	registerCounter(name: string, description: string): Counter {
+		assertMetricName(name);
+		if (this.metrics.has(name)) throw new Error(`Metric '${name}' is already registered.`);
+		const metric = new Counter(name, description);
+		this.metrics.set(name, metric);
+		return metric;
+	}
+
+	registerGauge(name: string, description: string): Gauge {
+		assertMetricName(name);
+		if (this.metrics.has(name)) throw new Error(`Metric '${name}' is already registered.`);
+		const metric = new Gauge(name, description);
+		this.metrics.set(name, metric);
+		return metric;
+	}
+
+	registerHistogram(name: string, description: string, buckets?: number[]): Histogram {
+		assertMetricName(name);
+		if (this.metrics.has(name)) throw new Error(`Metric '${name}' is already registered.`);
+		const metric = new Histogram(name, description, buckets);
+		this.metrics.set(name, metric);
+		return metric;
+	}
+
+	counter(name: string, description: string): Counter {
+		const existing = this.metrics.get(name);
+		if (existing instanceof Counter) {
+			if (existing.description !== description) {
+				process.stderr.write(`[pi-crew] metric-registry: counter '${name}' description changed; using original: '${existing.description}'\n`);
+			}
+			return existing;
+		}
+		if (existing) throw new Error(`Metric '${name}' is not a counter.`);
+		return this.registerCounter(name, description);
+	}
+
+	gauge(name: string, description: string): Gauge {
+		const existing = this.metrics.get(name);
+		if (existing instanceof Gauge) {
+			if (existing.description !== description) {
+				process.stderr.write(`[pi-crew] metric-registry: gauge '${name}' description changed; using original: '${existing.description}'\n`);
+			}
+			return existing;
+		}
+		if (existing) throw new Error(`Metric '${name}' is not a gauge.`);
+		return this.registerGauge(name, description);
+	}
+
+	histogram(name: string, description: string, buckets?: number[]): Histogram {
+		const existing = this.metrics.get(name);
+		if (existing instanceof Histogram) {
+			if (existing.description !== description) {
+				process.stderr.write(`[pi-crew] metric-registry: histogram '${name}' description changed; using original: '${existing.description}'\n`);
+			}
+			return existing;
+		}
+		if (existing) throw new Error(`Metric '${name}' is not a histogram.`);
+		return this.registerHistogram(name, description, buckets);
+	}
+
+	get(name: string): Metric | undefined {
+		return this.metrics.get(name);
+	}
+
+	snapshot(): MetricSnapshot[] {
+		return [...this.metrics.values()].map((metric) => metric.snapshot());
+	}
+
+	dispose(): void {
+		this.metrics.clear();
+	}
+}
+
+export function createMetricRegistry(): MetricRegistry {
+	return new MetricRegistry();
+}

package/src/observability/metric-retention.ts

@@ -1,54 +1,54 @@
-import { labelKey, type MetricLabels } from "./metrics-primitives.ts";
-
-interface WindowEvent {
-	timestamp: number;
-	labels: MetricLabels;
-	delta: number;
-}
-
-export class TimeWindowedCounter {
-	private events: WindowEvent[] = [];
-	private readonly windowMs: number;
-	private readonly now: () => number;
-	private static readonly MAX_EVENTS = 100_000;
-
-	constructor(windowMs = 3_600_000, now: () => number = () => Date.now()) {
-		this.windowMs = windowMs;
-		this.now = now;
-	}
-
-	inc(labels: MetricLabels = {}, delta = 1): void {
-		if (!Number.isFinite(delta)) return;
-		// Cap the event array to prevent unbounded memory growth.
-		if (this.events.length >= TimeWindowedCounter.MAX_EVENTS) this.prune();
-		this.events.push({ timestamp: this.now(), labels: { ...labels }, delta });
-		this.prune();
-	}
-
-	count(labels: MetricLabels = {}, durationMs = this.windowMs): number {
-		const now = this.now();
-		this.pruneAt(now);
-		const key = labelKey(labels);
-		const cutoff = now - durationMs;
-		return this.events.filter((event) => event.timestamp >= cutoff && labelKey(event.labels) === key).reduce((sum, event) => sum + event.delta, 0);
-	}
-
-	rate(labels: MetricLabels = {}, durationMs = this.windowMs): number {
-		if (durationMs <= 0) return 0;
-		return this.count(labels, durationMs) / (durationMs / 1000);
-	}
-
-	size(): number {
-		this.prune();
-		return this.events.length;
-	}
-
-	private prune(): void {
-		this.pruneAt(this.now());
-	}
-
-	private pruneAt(now: number): void {
-		const cutoff = now - this.windowMs;
-		this.events = this.events.filter((event) => event.timestamp >= cutoff);
-	}
-}
+import { labelKey, type MetricLabels } from "./metrics-primitives.ts";
+
+interface WindowEvent {
+	timestamp: number;
+	labels: MetricLabels;
+	delta: number;
+}
+
+export class TimeWindowedCounter {
+	private events: WindowEvent[] = [];
+	private readonly windowMs: number;
+	private readonly now: () => number;
+	private static readonly MAX_EVENTS = 100_000;
+
+	constructor(windowMs = 3_600_000, now: () => number = () => Date.now()) {
+		this.windowMs = windowMs;
+		this.now = now;
+	}
+
+	inc(labels: MetricLabels = {}, delta = 1): void {
+		if (!Number.isFinite(delta)) return;
+		// Cap the event array to prevent unbounded memory growth.
+		if (this.events.length >= TimeWindowedCounter.MAX_EVENTS) this.prune();
+		this.events.push({ timestamp: this.now(), labels: { ...labels }, delta });
+		this.prune();
+	}
+
+	count(labels: MetricLabels = {}, durationMs = this.windowMs): number {
+		const now = this.now();
+		this.pruneAt(now);
+		const key = labelKey(labels);
+		const cutoff = now - durationMs;
+		return this.events.filter((event) => event.timestamp >= cutoff && labelKey(event.labels) === key).reduce((sum, event) => sum + event.delta, 0);
+	}
+
+	rate(labels: MetricLabels = {}, durationMs = this.windowMs): number {
+		if (durationMs <= 0) return 0;
+		return this.count(labels, durationMs) / (durationMs / 1000);
+	}
+
+	size(): number {
+		this.prune();
+		return this.events.length;
+	}
+
+	private prune(): void {
+		this.pruneAt(this.now());
+	}
+
+	private pruneAt(now: number): void {
+		const cutoff = now - this.windowMs;
+		this.events = this.events.filter((event) => event.timestamp >= cutoff);
+	}
+}

package/src/observability/metric-sink.ts

@@ -1,56 +1,81 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { redactSecrets } from "../utils/redaction.ts";
-import { logInternalError } from "../utils/internal-error.ts";
-import type { MetricRegistry } from "./metric-registry.ts";
-import type { MetricSnapshot } from "./metrics-primitives.ts";
-
-export interface MetricSink {
-	writeSnapshot(snapshots: MetricSnapshot[]): void;
-	dispose(): void;
-}
-
-export interface MetricFileSinkOptions {
-	crewRoot: string;
-	registry: MetricRegistry;
-	retentionDays?: number;
-	intervalMs?: number;
-}
-
-function rotateOldFiles(dir: string, retentionDays: number, now = Date.now()): void {
-	if (!fs.existsSync(dir)) return;
-	const maxAge = retentionDays * 24 * 60 * 60 * 1000;
-	for (const file of fs.readdirSync(dir)) {
-		if (!file.endsWith(".jsonl")) continue;
-		const fullPath = path.join(dir, file);
-		try {
-			if (now - fs.statSync(fullPath).mtimeMs > maxAge) fs.unlinkSync(fullPath);
-		} catch (error) {
-			logInternalError("metric-sink.rotate", error, fullPath);
-		}
-	}
-}
-
-export function createMetricFileSink(opts: MetricFileSinkOptions): MetricSink {
-	const dir = path.join(opts.crewRoot, "state", "metrics");
-	const retentionDays = opts.retentionDays ?? 7;
-	const writeSnapshot = (snapshots: MetricSnapshot[]): void => {
-		try {
-			const now = new Date();
-			const date = now.toISOString().slice(0, 10);
-			fs.mkdirSync(dir, { recursive: true });
-			rotateOldFiles(dir, retentionDays);
-			const redacted = redactSecrets(snapshots);
-			if (!Array.isArray(redacted)) {
-				logInternalError("metric-sink.type", new Error("redactSecrets did not return an array"), `got=${typeof redacted}`);
-				return;
-			}
-			fs.appendFileSync(path.join(dir, `${date}.jsonl`), `${JSON.stringify({ exportedAt: now.toISOString(), snapshots: redacted as MetricSnapshot[] })}\n`, "utf-8");
-		} catch (error) {
-			logInternalError("metric-sink.write", error);
-		}
-	};
-	const timer = setInterval(() => writeSnapshot(opts.registry.snapshot()), opts.intervalMs ?? 60_000);
-	timer.unref();
-	return { writeSnapshot, dispose: () => clearInterval(timer) };
-}
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { redactSecrets } from "../utils/redaction.ts";
+import { logInternalError } from "../utils/internal-error.ts";
+import type { MetricRegistry } from "./metric-registry.ts";
+import type { MetricSnapshot } from "./metrics-primitives.ts";
+
+export interface MetricSink {
+	writeSnapshot(snapshots: MetricSnapshot[]): void;
+	dispose(): void;
+}
+
+export interface MetricFileSinkOptions {
+	crewRoot: string;
+	registry: MetricRegistry;
+	retentionDays?: number;
+	intervalMs?: number;
+}
+
+function rotateOldFiles(dir: string, retentionDays: number, now = Date.now()): void {
+	if (!fs.existsSync(dir)) return;
+	const maxAge = retentionDays * 24 * 60 * 60 * 1000;
+	for (const file of fs.readdirSync(dir)) {
+		if (!file.endsWith(".jsonl")) continue;
+		const fullPath = path.join(dir, file);
+		try {
+			if (now - fs.statSync(fullPath).mtimeMs > maxAge) fs.unlinkSync(fullPath);
+		} catch (error) {
+			logInternalError("metric-sink.rotate", error, fullPath);
+		}
+	}
+}
+
+export function createMetricFileSink(opts: MetricFileSinkOptions): MetricSink {
+	const dir = path.join(opts.crewRoot, "state", "metrics");
+	const retentionDays = opts.retentionDays ?? 7;
+	// 4.1: hold a single open fd per UTC date instead of `appendFileSync` per
+	// snapshot. Avoids open/close syscalls each tick and keeps the
+	// synchronous write semantics that callers (and tests) expect.
+	let fd: number | undefined;
+	let fdDate: string | undefined;
+	const ensureFd = (date: string): number => {
+		if (fd !== undefined && fdDate === date) return fd;
+		if (fd !== undefined) {
+			try { fs.closeSync(fd); } catch (error) { logInternalError("metric-sink.closeFd", error); }
+		}
+		fs.mkdirSync(dir, { recursive: true });
+		rotateOldFiles(dir, retentionDays);
+		fd = fs.openSync(path.join(dir, `${date}.jsonl`), "a");
+		fdDate = date;
+		return fd;
+	};
+	const writeSnapshot = (snapshots: MetricSnapshot[]): void => {
+		try {
+			const now = new Date();
+			const date = now.toISOString().slice(0, 10);
+			const redacted = redactSecrets(snapshots);
+			if (!Array.isArray(redacted)) {
+				logInternalError("metric-sink.type", new Error("redactSecrets did not return an array"), `got=${typeof redacted}`);
+				return;
+			}
+			const target = ensureFd(date);
+			fs.writeSync(target, `${JSON.stringify({ exportedAt: now.toISOString(), snapshots: redacted as MetricSnapshot[] })}\n`);
+		} catch (error) {
+			logInternalError("metric-sink.write", error);
+		}
+	};
+	const timer = setInterval(() => writeSnapshot(opts.registry.snapshot()), opts.intervalMs ?? 60_000);
+	timer.unref();
+	return {
+		writeSnapshot,
+		dispose: () => {
+			clearInterval(timer);
+			if (fd !== undefined) {
+				try { fs.closeSync(fd); } catch (error) { logInternalError("metric-sink.dispose", error); }
+				fd = undefined;
+				fdDate = undefined;
+			}
+		},
+	};
+}