@obsunified/collector 2.0.1

package/src/lib/propagation-metric.test.ts

@@ -0,0 +1,196 @@
+/**
+ * RFC 0004 Phase 1.8 — propagation aggregator tests.
+ *
+ * Exercises the SQL the aggregator issues against a structural fake
+ * database. Validates:
+ *  - the count queries pin to project_id + the hour cutoff
+ *  - 8 metric points emerge (4 signals × 2 propagated values)
+ *  - point identities are stable across runs (so the cron upserts series)
+ *  - zero rows still produce points with value=0 (visible-empty-state)
+ */
+
+import { describe, expect, it, vi } from "vitest";
+import type { Logger } from "../framework/logger";
+import { aggregatePropagationForProject } from "./propagation-metric";
+import type { SqlDb } from "./sql-db";
+
+interface FakeRow {
+	propagated: number;
+	missing: number;
+}
+
+class FakeDb {
+	calls: Array<{ sql: string; binds: unknown[] }> = [];
+	constructor(
+		private readonly counts: Record<string, FakeRow>,
+		private readonly seriesExisting = new Map<string, string>(),
+	) {}
+
+	prepare(sql: string) {
+		const calls = this.calls;
+		const counts = this.counts;
+		const seriesExisting = this.seriesExisting;
+		let binds: unknown[] = [];
+		const stmt: {
+			bind: (...args: unknown[]) => typeof stmt;
+			first: <T>() => Promise<T | null>;
+			all: <T>() => Promise<{ results: T[] }>;
+			run: () => Promise<{ meta: { changes: number } }>;
+		} = {
+			bind: (...args: unknown[]) => {
+				binds = args;
+				return stmt;
+			},
+			first: async <T>() => {
+				calls.push({ sql, binds: [...binds] });
+				if (sql.includes("FROM telemetry_spans"))
+					return counts.telemetry_spans as T;
+				if (sql.includes("FROM logs")) return counts.logs as T;
+				if (sql.includes("FROM usage_events")) return counts.usage_events as T;
+				if (sql.includes("FROM ai_calls")) return counts.ai_calls as T;
+				return null;
+			},
+			all: async <T>() => {
+				calls.push({ sql, binds: [...binds] });
+				if (sql.includes("FROM metric_series")) {
+					// MetricsStore.resolveSeries SELECT — return any pre-seeded
+					// series so the aggregator reuses ids on repeat runs.
+					const identities = binds.slice(1) as string[];
+					const results = identities
+						.filter((id) => seriesExisting.has(id))
+						.map((id) => ({
+							id: seriesExisting.get(id),
+							identity: id,
+						}));
+					return { results: results as unknown as T[] };
+				}
+				return { results: [] };
+			},
+			run: async () => {
+				calls.push({ sql, binds: [...binds] });
+				return { meta: { changes: 1 } };
+			},
+		};
+		return stmt;
+	}
+
+	async batch(stmts: unknown[]) {
+		return stmts.map(() => ({ success: true, meta: { changes: 1 } }));
+	}
+}
+
+describe("aggregatePropagationForProject", () => {
+	it("queries 4 signal tables with project_id + hour cutoff", async () => {
+		const db = new FakeDb({
+			telemetry_spans: { propagated: 12, missing: 3 },
+			logs: { propagated: 8, missing: 0 },
+			usage_events: { propagated: 5, missing: 7 },
+			ai_calls: { propagated: 2, missing: 1 },
+		});
+		const now = new Date("2026-05-04T12:30:00.000Z");
+		await aggregatePropagationForProject(db as unknown as SqlDb, "p1", now);
+
+		const expectedCutoff = "2026-05-04T11:30:00.000Z";
+
+		const countCalls = db.calls.filter((c) =>
+			c.sql.includes("SUM(CASE WHEN interaction_id"),
+		);
+		expect(countCalls).toHaveLength(4);
+		for (const call of countCalls) {
+			expect(call.binds[0]).toBe("p1");
+			expect(call.binds[1]).toBe(expectedCutoff);
+		}
+	});
+
+	it("writes 8 metric points (4 signals × 2 propagated values)", async () => {
+		const db = new FakeDb({
+			telemetry_spans: { propagated: 12, missing: 3 },
+			logs: { propagated: 8, missing: 0 },
+			usage_events: { propagated: 5, missing: 7 },
+			ai_calls: { propagated: 2, missing: 1 },
+		});
+		const result = await aggregatePropagationForProject(
+			db as unknown as SqlDb,
+			"p1",
+			new Date(),
+		);
+		expect(result.pointsWritten).toBe(8);
+	});
+
+	it("includes zero-count points so the dashboard sees both buckets", async () => {
+		const db = new FakeDb({
+			telemetry_spans: { propagated: 0, missing: 0 },
+			logs: { propagated: 0, missing: 0 },
+			usage_events: { propagated: 0, missing: 0 },
+			ai_calls: { propagated: 0, missing: 0 },
+		});
+		const result = await aggregatePropagationForProject(
+			db as unknown as SqlDb,
+			"p1",
+			new Date(),
+		);
+		expect(result.pointsWritten).toBe(8);
+	});
+
+	it("treats null SUM as 0 (empty signal table edge case)", async () => {
+		const db = new FakeDb({
+			telemetry_spans: {
+				propagated: null,
+				missing: null,
+			} as unknown as FakeRow,
+			logs: { propagated: null, missing: null } as unknown as FakeRow,
+			usage_events: { propagated: null, missing: null } as unknown as FakeRow,
+			ai_calls: { propagated: null, missing: null } as unknown as FakeRow,
+		});
+		const result = await aggregatePropagationForProject(
+			db as unknown as SqlDb,
+			"p1",
+			new Date(),
+		);
+		expect(result.pointsWritten).toBe(8);
+	});
+
+	it("logs and continues when a single signal count fails", async () => {
+		// Make ONE signal throw on its count by using a db that throws for a
+		// specific table.
+		const baseDb = new FakeDb({
+			telemetry_spans: { propagated: 1, missing: 0 },
+			logs: { propagated: 1, missing: 0 },
+			usage_events: { propagated: 1, missing: 0 },
+			ai_calls: { propagated: 1, missing: 0 },
+		});
+		const originalPrepare = baseDb.prepare.bind(baseDb);
+		baseDb.prepare = (sql: string) => {
+			if (sql.includes("FROM logs")) {
+				return {
+					bind: () => ({
+						first: async () => {
+							throw new Error("boom");
+						},
+						all: async () => ({ results: [] }),
+						run: async () => ({ meta: { changes: 0 } }),
+					}),
+				} as unknown as ReturnType<typeof originalPrepare>;
+			}
+			return originalPrepare(sql);
+		};
+		const logger = {
+			error: vi.fn(),
+			info: vi.fn(),
+			warn: vi.fn(),
+			debug: vi.fn(),
+		};
+		const result = await aggregatePropagationForProject(
+			baseDb as unknown as SqlDb,
+			"p1",
+			new Date(),
+			logger as Logger,
+		);
+		// Three signals succeed (×2 points each) — logs throws, so 6 points.
+		expect(result.pointsWritten).toBe(6);
+		expect(logger.error).toHaveBeenCalledWith(
+			"[propagation-metric] count failed",
+			expect.objectContaining({ signal: "log", projectId: "p1" }),
+		);
+	});
+});

package/src/lib/propagation-metric.ts

@@ -0,0 +1,175 @@
+/**
+ * RFC 0004 Phase 1.8 — interaction_id propagation metric.
+ *
+ * Hourly aggregator: counts how many records in each signal table for
+ * each project carry an interaction_id versus null over the last hour.
+ * Writes 8 metric points per project per hour to metric_point as the
+ * standard OTel counter `obs.interaction.propagation` with attributes
+ * `(signal, propagated)`. The Health dashboard's tile (Phase 1.10
+ * follow-up or RFC 0006 Connected rail consumer) reads these series and
+ * surfaces the ratio per signal.
+ *
+ * Why aggregate via cron rather than emit per-request:
+ * - The signal tables already have the data; a hourly count is two
+ *   indexed COUNT(*) queries per signal — sub-ms.
+ * - Per-request emission adds a ~2x write amplification across every
+ *   ingest path. The metric is operational, not analytical, and an
+ *   hourly cadence is enough to surface drift.
+ *
+ * Series identity is stable so the cron upserts the same series rows
+ * each run rather than creating new ones.
+ */
+
+import type { Logger } from "../framework/logger";
+import type { DecodedMetricPoint } from "../otlp/decode";
+import { MetricsStore } from "./metrics-store";
+import type { SqlDb } from "./sql-db";
+
+const PROPAGATION_METRIC_NAME = "obs.interaction.propagation";
+
+type Signal = "span" | "log" | "usage" | "ai_call";
+
+interface SignalQuery {
+	signal: Signal;
+	table: string;
+}
+
+const SIGNALS: SignalQuery[] = [
+	{ signal: "span", table: "telemetry_spans" },
+	{ signal: "log", table: "logs" },
+	{ signal: "usage", table: "usage_events" },
+	{ signal: "ai_call", table: "ai_calls" },
+];
+
+/**
+ * Stable identity string for the (name, attributes) tuple. Mirrors the
+ * format MetricsStore writes for OTLP-ingested points so a query joining
+ * on metric_series.identity gets a consistent result regardless of
+ * source.
+ */
+const propagationIdentity = (signal: Signal, propagated: boolean): string =>
+	`${PROPAGATION_METRIC_NAME}|signal=${signal}|propagated=${propagated}`;
+
+const buildPoint = (
+	signal: Signal,
+	propagated: boolean,
+	count: number,
+	tsNs: string,
+): DecodedMetricPoint => ({
+	name: PROPAGATION_METRIC_NAME,
+	description:
+		"Count of signal records ingested in the last hour, partitioned by whether they carry interaction_id (RFC 0004).",
+	unit: "{records}",
+	type: "sum",
+	isMonotonic: false, // delta over a one-hour window, not cumulative
+	temporality: 1, // DELTA
+	scopeName: "obs.collector",
+	scopeVersion: "1",
+	serviceName: "obs-collector",
+	resourceAttrsJson: null,
+	attributesJson: JSON.stringify({ signal, propagated }),
+	identity: propagationIdentity(signal, propagated),
+	tsNs,
+	startTsNs: null,
+	value: count,
+	count: null,
+	sum: null,
+	min: null,
+	max: null,
+	boundsJson: null,
+	bucketCountsJson: null,
+	extraJson: null,
+	exemplarsJson: null,
+});
+
+const countsForSignal = async (
+	db: SqlDb,
+	projectId: string,
+	table: string,
+	hourCutoffIso: string,
+): Promise<{ propagated: number; missing: number }> => {
+	const row = await db
+		.prepare(
+			`SELECT
+			  SUM(CASE WHEN interaction_id IS NOT NULL THEN 1 ELSE 0 END) AS propagated,
+			  SUM(CASE WHEN interaction_id IS NULL THEN 1 ELSE 0 END) AS missing
+			FROM ${table}
+			WHERE project_id = ? AND received_at >= ?`,
+		)
+		.bind(projectId, hourCutoffIso)
+		.first<{ propagated: number | null; missing: number | null }>();
+	return {
+		propagated: row?.propagated ?? 0,
+		missing: row?.missing ?? 0,
+	};
+};
+
+/**
+ * Aggregate propagation counts for a single project and write them as
+ * metric points. Idempotent per hour-bucket (each run produces a new
+ * point; series identity stays stable).
+ */
+export const aggregatePropagationForProject = async (
+	db: SqlDb,
+	projectId: string,
+	now: Date,
+	logger?: Logger,
+): Promise<{ pointsWritten: number }> => {
+	const hourCutoff = new Date(now.getTime() - 60 * 60 * 1000).toISOString();
+	const tsNs = (BigInt(now.getTime()) * 1_000_000n).toString();
+	const points: DecodedMetricPoint[] = [];
+
+	for (const { signal, table } of SIGNALS) {
+		try {
+			const { propagated, missing } = await countsForSignal(
+				db,
+				projectId,
+				table,
+				hourCutoff,
+			);
+			points.push(buildPoint(signal, true, propagated, tsNs));
+			points.push(buildPoint(signal, false, missing, tsNs));
+		} catch (err) {
+			logger?.error("[propagation-metric] count failed", {
+				signal,
+				table,
+				projectId,
+				error: err instanceof Error ? err.message : String(err),
+			});
+		}
+	}
+
+	if (points.length === 0) return { pointsWritten: 0 };
+
+	const store = new MetricsStore(db);
+	await store.ingestBatch({
+		projectId,
+		points,
+		receivedAt: now.toISOString(),
+		// Keep propagation metrics on the same retention as everything else.
+		expiresAt: new Date(now.getTime() + 72 * 60 * 60 * 1000).toISOString(),
+	});
+
+	return { pointsWritten: points.length };
+};
+
+/**
+ * Run the aggregation across all known projects. Designed for a once-per-hour
+ * cron handler; cheap enough to run alongside retention cleanup.
+ */
+export const aggregatePropagation = async (
+	db: SqlDb,
+	now: Date,
+	logger?: Logger,
+): Promise<{ projects: number; pointsWritten: number }> => {
+	const projects = await db
+		.prepare("SELECT id FROM projects")
+		.all<{ id: string }>();
+
+	let pointsWritten = 0;
+	for (const p of projects.results) {
+		const r = await aggregatePropagationForProject(db, p.id, now, logger);
+		pointsWritten += r.pointsWritten;
+	}
+	return { projects: projects.results.length, pointsWritten };
+};

package/src/lib/sql-db-dialect.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { postgresDialect, sqliteDialect } from "./sql-db";
+
+describe("SqlDialect", () => {
+	it("renders native SQLite expressions", () => {
+		expect(sqliteDialect.sinceHours("?")).toBe(
+			"datetime('now', '-' || ? || ' hours')",
+		);
+		expect(
+			sqliteDialect.jsonText("attributes_json", '$."llm.cost.total_usd"'),
+		).toBe(`json_extract(attributes_json, '$."llm.cost.total_usd"')`);
+	});
+
+	it("renders native Postgres expressions without adapter regex translation", () => {
+		expect(postgresDialect.sinceHours("$1")).toBe(
+			"(CURRENT_TIMESTAMP - ($1::text || ' hours')::interval)",
+		);
+		expect(
+			postgresDialect.jsonText("attributes_json", '$."llm.cost.total_usd"'),
+		).toBe("(attributes_json::jsonb ->> 'llm.cost.total_usd')");
+	});
+});

package/src/lib/sql-db-postgres.ts

@@ -0,0 +1,229 @@
+/**
+ * Postgres adapter for the SqlDb seam (RFC 0008).
+ *
+ * Wraps `pg` (node-postgres) to expose the same `prepare → bind → first |
+ * all | run` chain as `D1Adapter`. Used by the Docker / standalone Node
+ * deployment of `apps/collector`; the Workers deployment continues to
+ * use `D1Adapter`.
+ *
+ * Notable differences from D1 handled here:
+ *  - Placeholders: D1 uses `?`; Postgres uses `$1`, `$2`. We rewrite
+ *    `?` to `$N` in `prepare`. Statements MUST use `?` for portability.
+ *  - `INSERT … RETURNING`: D1 doesn't support RETURNING; Postgres does.
+ *    Code that targets both MUST NOT rely on RETURNING.
+ *  - `TEXT vs VARCHAR`: D1 is permissive; we use TEXT exclusively in
+ *    the postgres migrations.
+ *  - `meta.changes`: D1 reports affected row count via meta.changes;
+ *    Postgres reports it via `result.rowCount`. We normalize.
+ *
+ * Connection pooling is the caller's job — pass a `pg.Pool`, not a
+ * one-shot Client. Each `prepare` checks out, runs the statement, and
+ * releases. Long-lived transactions need a different surface (not yet
+ * exposed; collector code today does not require them).
+ */
+
+import type { Pool, QueryResultRow } from "pg";
+import { postgresDialect, type SqlDb, type SqlStatement } from "./sql-db";
+
+export interface PostgresAdapterOptions {
+	/**
+	 * Statement-level timeout in milliseconds. Defaults to 30s. Issued
+	 * via `SET statement_timeout` at the start of each query (session-level;
+	 * `SET LOCAL` outside a transaction would be a no-op).
+	 */
+	statementTimeoutMs?: number;
+}
+
+export class PostgresAdapter implements SqlDb {
+	readonly dialect = postgresDialect;
+	private readonly statementTimeoutMs: number;
+
+	constructor(
+		private readonly pool: Pool,
+		options: PostgresAdapterOptions = {},
+	) {
+		const rawTimeout = options.statementTimeoutMs ?? 30_000;
+		this.statementTimeoutMs =
+			Number.isFinite(rawTimeout) && rawTimeout >= 0
+				? Math.trunc(rawTimeout)
+				: 30_000;
+
+		// Configure statement timeout once upon connection establishment
+		this.pool.on("connect", (client) => {
+			client
+				.query(`SET statement_timeout = ${this.statementTimeoutMs}`)
+				.catch(() => {});
+		});
+	}
+
+	prepare(sql: string): SqlStatement {
+		return new PostgresStatement(
+			this.pool,
+			translateD1Sql(rewriteQuestionMarks(sql)),
+		);
+	}
+
+	async batch(
+		statements: SqlStatement[],
+	): Promise<Array<{ meta: { changes: number } }>> {
+		const client = await this.pool.connect();
+		try {
+			await client.query("BEGIN");
+			// SET LOCAL works here because it is inside the transaction.
+			await client.query(
+				`SET LOCAL statement_timeout = ${this.statementTimeoutMs}`,
+			);
+			const out: Array<{ meta: { changes: number } }> = [];
+			for (const s of statements) {
+				if (!(s instanceof PostgresStatement)) {
+					throw new Error(
+						"PostgresAdapter.batch: statement was not produced by PostgresAdapter",
+					);
+				}
+				const r = await s.runOnClient(client);
+				out.push(r);
+			}
+			await client.query("COMMIT");
+			return out;
+		} catch (err) {
+			await client.query("ROLLBACK").catch(() => {});
+			throw err;
+		} finally {
+			client.release();
+		}
+	}
+}
+
+class PostgresStatement implements SqlStatement {
+	private bound: unknown[] = [];
+
+	constructor(
+		private readonly pool: Pool,
+		private readonly sql: string,
+	) {}
+
+	bind(...args: unknown[]): SqlStatement {
+		this.bound = args;
+		return this;
+	}
+
+	async first<T = Record<string, unknown>>(): Promise<T | null> {
+		const result = await this.exec<T & QueryResultRow>();
+		return (result.rows[0] as T | undefined) ?? null;
+	}
+
+	async all<T = Record<string, unknown>>(): Promise<{ results: T[] }> {
+		const result = await this.exec<T & QueryResultRow>();
+		return { results: result.rows as unknown as T[] };
+	}
+
+	async run(): Promise<{ meta: { changes: number } }> {
+		const result = await this.exec();
+		return { meta: { changes: result.rowCount ?? 0 } };
+	}
+
+	// Internal — used by batch() to run inside an already-checked-out
+	// client (so the BEGIN/COMMIT span the whole batch).
+	async runOnClient(client: {
+		query: (
+			text: string,
+			values?: unknown[],
+		) => Promise<{ rowCount: number | null }>;
+	}): Promise<{ meta: { changes: number } }> {
+		const r = await client.query(this.sql, this.bound);
+		return { meta: { changes: r.rowCount ?? 0 } };
+	}
+
+	private async exec<T extends QueryResultRow = QueryResultRow>(): Promise<{
+		rows: T[];
+		rowCount: number | null;
+	}> {
+		const client = await this.pool.connect();
+		try {
+			const r = await client.query<T>(this.sql, this.bound);
+			return { rows: r.rows, rowCount: r.rowCount };
+		} finally {
+			client.release();
+		}
+	}
+}
+
+// D1 → Postgres placeholder rewrite. Walks the string once; tracks
+// whether we're inside a single-quoted string literal so that '?' inside
+// strings isn't rewritten. Doesn't handle dollar-quoted strings — none
+// of the collector's SQL uses them.
+const rewriteQuestionMarks = (sql: string): string => {
+	let out = "";
+	let inString = false;
+	let n = 0;
+	for (let i = 0; i < sql.length; i++) {
+		const ch = sql[i];
+		if (ch === "'") {
+			inString = !inString;
+			out += ch;
+			continue;
+		}
+		if (ch === "?" && !inString) {
+			n += 1;
+			out += `$${n}`;
+			continue;
+		}
+		out += ch;
+	}
+	return out;
+};
+
+const translateD1Sql = (sql: string): string => {
+	let out = sql;
+	const hadInsertOrIgnore = /\bINSERT\s+OR\s+IGNORE\s+INTO\b/i.test(out);
+
+	out = out.replace(/\bINSERT\s+OR\s+IGNORE\s+INTO\b/gi, "INSERT INTO");
+
+	out = out.replace(
+		/datetime\('now',\s*'-'\s*\|\|\s*(\$\d+)\s*\|\|\s*'\s*hours'\)/gi,
+		"(CURRENT_TIMESTAMP - ($1::text || ' hours')::interval)",
+	);
+	out = out.replace(
+		/datetime\('now',\s*'-'\s*\|\|\s*(\$\d+)\s*\|\|\s*'\s*minutes'\)/gi,
+		"(CURRENT_TIMESTAMP - ($1::text || ' minutes')::interval)",
+	);
+	out = out.replace(
+		/datetime\('now',\s*'-(\d+)\s+(hour|hours|minute|minutes|day|days)'\)/gi,
+		"CURRENT_TIMESTAMP - INTERVAL '$1 $2'",
+	);
+	out = out.replace(/datetime\('now'\)/gi, "CURRENT_TIMESTAMP");
+
+	out = out.replace(
+		/json_extract\(([^,()]+),\s*'\$\.(?:"([^"]+)"|([A-Za-z0-9_\\.\\\\]+))'\)/gi,
+		(
+			_match,
+			expr: string,
+			quotedKey: string | undefined,
+			bareKey: string | undefined,
+		) => {
+			const key = (quotedKey ?? bareKey ?? "").replace(
+				/\\\\u002E|\\u002E/g,
+				".",
+			);
+			return `(${expr.trim()}::jsonb ->> '${key.replace(/'/g, "''")}')`;
+		},
+	);
+
+	out = out.replace(
+		/strftime\('%Y-%m-%dT%H:%M:00Z',\s*([^)]+)\)/gi,
+		"to_char(date_trunc('minute', $1::timestamp), 'YYYY-MM-DD\"T\"HH24:MI:00\"Z\"')",
+	);
+	out = out.replace(
+		/strftime\('%Y-%m-%dT%H:00:00Z',\s*([^)]+)\)/gi,
+		"to_char(date_trunc('hour', $1::timestamp), 'YYYY-MM-DD\"T\"HH24:00:00\"Z\"')",
+	);
+	out = out.replace(
+		/strftime\('%s',\s*([^)]+)\)/gi,
+		"EXTRACT(EPOCH FROM $1::timestamp)",
+	);
+	if (hadInsertOrIgnore && /\bON\s+CONFLICT\b/i.test(out) === false) {
+		out = out.replace(/(;?\s*)$/, " ON CONFLICT DO NOTHING$1");
+	}
+
+	return out;
+};