@obsunified/collector 2.2.1 → 2.3.0

package/src/lib/ai-store/calls.ts

@@ -53,6 +53,48 @@ export async function ingestAICallBatch(
 	await db.batch(batch);
 }
 
+function mapAICallRow(row: AICallRow): AICallRecord {
+	return {
+		projectId: row.project_id ?? "default",
+		callId: row.call_id,
+		traceId: row.trace_id,
+		spanId: row.span_id,
+		serviceName: row.service_name,
+		modelName: row.model_name,
+		provider: row.provider,
+		callType: row.call_type,
+		requestJson: row.request_json,
+		responseJson: row.response_json,
+		promptTokens: row.prompt_tokens,
+		completionTokens: row.completion_tokens,
+		totalCostUsd: row.total_cost_usd,
+		latencyMs: row.latency_ms,
+		isError: row.is_error === 1 || row.is_error === true,
+		errorMessage: row.error_message,
+		occurredAt: row.occurred_at,
+		receivedAt: row.received_at,
+		expiresAt: row.expires_at,
+		sessionId: row.session_id ?? null,
+		interactionId: row.interaction_id ?? null,
+	};
+}
+
+/** One call by id, scoped to the project; `null` when absent. */
+export async function getAICallById(
+	db: SqlDb,
+	projectId: string,
+	callId: string,
+): Promise<AICallRecord | null> {
+	if (!projectId) throw new Error("AIStore.getAICall: projectId is required");
+	const row = await db
+		.prepare(
+			`SELECT * FROM ai_calls WHERE project_id = ? AND call_id = ? LIMIT 1`,
+		)
+		.bind(projectId, callId)
+		.first<AICallRow>();
+	return row ? mapAICallRow(row) : null;
+}
+
 export async function getAICallsOverview(
 	db: SqlDb,
 	options: AICallsOverviewOptions,
@@ -109,29 +151,7 @@ export async function getAICallsOverview(
 			.bind(...summaryParams)
 			.first<AICallSummaryRow>()) || {};
 
-	const calls: AICallRecord[] = (results.results || []).map((row) => ({
-		projectId: row.project_id ?? "default",
-		callId: row.call_id,
-		traceId: row.trace_id,
-		spanId: row.span_id,
-		serviceName: row.service_name,
-		modelName: row.model_name,
-		provider: row.provider,
-		callType: row.call_type,
-		requestJson: row.request_json,
-		responseJson: row.response_json,
-		promptTokens: row.prompt_tokens,
-		completionTokens: row.completion_tokens,
-		totalCostUsd: row.total_cost_usd,
-		latencyMs: row.latency_ms,
-		isError: row.is_error === 1 || row.is_error === true,
-		errorMessage: row.error_message,
-		occurredAt: row.occurred_at,
-		receivedAt: row.received_at,
-		expiresAt: row.expires_at,
-		sessionId: row.session_id ?? null,
-		interactionId: row.interaction_id ?? null,
-	}));
+	const calls: AICallRecord[] = (results.results || []).map(mapAICallRow);
 
 	return {
 		calls,

package/src/lib/ai-store/evaluations.test.ts

@@ -25,20 +25,20 @@ describe("mapEvaluationRows", () => {
 				evidenceId: "ai-evaluation:eval-1",
 				entityKind: "eval",
 				entityId: "eval-1",
-				route: "#/evals/eval-1",
+				route: "#/evaluations/eval-1",
 				source: "ai_span_evaluations.llm_judge",
 				citations: [
 					{
 						label: "span span-1",
 						entityKind: "span",
 						entityId: "trace-1:span-1",
-						route: "#/traces/trace-1#span=span-1",
+						route: "#/traces?trace=trace-1&span=span-1",
 					},
 					{
 						label: "trace trace-1",
 						entityKind: "trace",
 						entityId: "trace-1",
-						route: "#/traces/trace-1",
+						route: "#/traces?trace=trace-1",
 					},
 				],
 			}),

package/src/lib/ai-store.ts

@@ -10,7 +10,11 @@ import type {
 	AISpansOverviewOptions,
 	AISpansOverviewResponse,
 } from "@obsunified/types";
-import { getAICallsOverview, ingestAICallBatch } from "./ai-store/calls";
+import {
+	getAICallById,
+	getAICallsOverview,
+	ingestAICallBatch,
+} from "./ai-store/calls";
 import {
 	getAIEvaluation,
 	ingestAIEvaluations,
@@ -37,6 +41,13 @@ export class AIStore {
 		return getAICallsOverview(this.db, options);
 	}
 
+	async getAICall(
+		projectId: string,
+		callId: string,
+	): Promise<AICallRecord | null> {
+		return getAICallById(this.db, projectId, callId);
+	}
+
 	async purgeExpired(): Promise<number> {
 		return purgeExpiredAIData(this.db);
 	}

package/src/lib/analyses-store.test.ts

@@ -118,7 +118,7 @@ describe("AnalysesStore.getLatestResult evidence references", () => {
 					"analysis:investigate.latency:tail_offenders:0:span:trace-1:span-1",
 				entityKind: "span",
 				entityId: "trace-1:span-1",
-				route: "#/traces/trace-1#span=span-1",
+				route: "#/traces?trace=trace-1&span=span-1",
 				source: "analysis.payload.evidence.tail_offenders",
 				confidence: 0.95,
 				citations: [
@@ -126,7 +126,7 @@ describe("AnalysesStore.getLatestResult evidence references", () => {
 						label: "trace trace-1",
 						entityKind: "trace",
 						entityId: "trace-1",
-						route: "#/traces/trace-1",
+						route: "#/traces?trace=trace-1",
 					},
 				],
 			}),
@@ -134,7 +134,7 @@ describe("AnalysesStore.getLatestResult evidence references", () => {
 				evidenceId: "analysis:investigate.latency:tail_offenders:1:service:api",
 				entityKind: "service",
 				entityId: "api",
-				route: "#/traces?service=api",
+				route: "#/service-map?service=api",
 				source: "analysis.payload.evidence.tail_offenders",
 				confidence: 0.7,
 			}),
@@ -219,7 +219,7 @@ describe("AnalysesStore.getLatestResult evidence references", () => {
 				"analysis:trace.instrumentation_gaps:instrumentation-gap:0:span:trace-gap:span-root",
 			entityKind: "span",
 			entityId: "trace-gap:span-root",
-			route: "#/traces/trace-gap#span=span-root",
+			route: "#/traces?trace=trace-gap&span=span-root",
 			source: "analysis.payload.instrumentationGaps",
 			confidence: 0.9,
 			citations: [
@@ -227,7 +227,7 @@ describe("AnalysesStore.getLatestResult evidence references", () => {
 					label: "trace trace-gap",
 					entityKind: "trace",
 					entityId: "trace-gap",
-					route: "#/traces/trace-gap",
+					route: "#/traces?trace=trace-gap",
 				},
 			],
 			suggestedNextPivots: expect.arrayContaining([
@@ -235,7 +235,7 @@ describe("AnalysesStore.getLatestResult evidence references", () => {
 					label: "Open profiler setup docs",
 					entityKind: "docs",
 					entityId: "howto/ebpf",
-					route: "#/docs/howto/ebpf",
+					route: "#/evidence?kind=docs&id=howto%2Febpf",
 				}),
 			]),
 		});

package/src/lib/autosre-findings.ts

@@ -15,10 +15,11 @@ import type {
 import {
 	buildCanonicalNodeId,
 	buildFindingFingerprint,
+	OntologyNodeKindSchema,
 } from "@obsunified/types";
 import { consoleLogger, type Logger } from "../framework/logger";
 import { computeChangeBlastRadius } from "./autosre-change-correlation";
-import { randomHex } from "./hash";
+import { randomHex, sha256Hex } from "./hash";
 import { parseJsonArray, parseJsonRecord } from "./json";
 import type { SqlDb } from "./sql-db";
 
@@ -221,6 +222,97 @@ function resolveSafeCausalProofTier(
 	return "unverified_locus";
 }
 
+export interface FaultLocusSpanRow {
+	service_name: string | null;
+	span_name: string;
+	status_message: string | null;
+	error_signature?: string | null;
+}
+
+/** Looks up the span a finding's fault locus refers to (newest match wins). */
+export async function loadFaultLocusSpan(
+	db: SqlDb,
+	projectId: string,
+	environment: string,
+	spanId: string,
+	traceId?: string,
+): Promise<FaultLocusSpanRow | null> {
+	if (!spanId) return null;
+	return db
+		.prepare(
+			`SELECT service_name, span_name, status_message, error_signature
+			 FROM telemetry_spans
+			 WHERE project_id = ? AND environment = ? AND span_id = ?
+			 ${traceId ? "AND trace_id = ?" : ""}
+			 ORDER BY start_time DESC
+			 LIMIT 1`,
+		)
+		.bind(
+			...(traceId
+				? [projectId, environment, spanId, traceId]
+				: [projectId, environment, spanId]),
+		)
+		.first<FaultLocusSpanRow>();
+}
+
+/** Fingerprint inputs derivable from a span; empty fields are left undefined. */
+export type SpanFingerprintInput = Pick<
+	FindingFingerprintInput,
+	"environment" | "originatingNodeId" | "downstreamTargetNodeId"
+> &
+	Partial<
+		Pick<FindingFingerprintInput, "normalizedOperation" | "errorSignature">
+	>;
+
+/** True for `kind:env:ns:name...` ids built by buildCanonicalNodeId. */
+function looksLikeCanonicalNodeId(id: string): boolean {
+	const parts = id.split(":");
+	return (
+		parts.length >= 4 &&
+		(OntologyNodeKindSchema.options as readonly string[]).includes(parts[0])
+	);
+}
+
+/**
+ * Splits a `<traceId>:<spanId>` span locus. Returns null for anything that
+ * is a canonical node id or does not have exactly two non-empty parts.
+ */
+function splitTraceSpanLocus(
+	id: string,
+): { traceId: string; spanId: string } | null {
+	if (looksLikeCanonicalNodeId(id)) return null;
+	const parts = id.split(":");
+	if (parts.length !== 2 || !parts[0] || !parts[1]) return null;
+	return { traceId: parts[0], spanId: parts[1] };
+}
+
+/**
+ * Stable recurrence-fingerprint inputs for a fault-locus span: the service node,
+ * the span name as the operation and the span's error signature (falling back
+ * to its status message). No instance ids participate, so two traces failing
+ * the same way on the same service/route share a fingerprint. Used by both
+ * finding creation and the evidence bundle's prior-finding lookup.
+ */
+export function fingerprintInputFromSpan(
+	span: FaultLocusSpanRow,
+	environment: string,
+): SpanFingerprintInput {
+	return {
+		environment,
+		originatingNodeId: buildCanonicalNodeId({
+			kind: "service",
+			environment,
+			serviceName: span.service_name || "unknown-service",
+		}).id,
+		// Empty strings are "absent": returning undefined lets the caller's
+		// `??` chain reach its title/summary fallbacks.
+		normalizedOperation: span.span_name?.trim() || undefined,
+		errorSignature:
+			span.error_signature?.trim() || span.status_message?.trim() || undefined,
+		downstreamTargetNodeId: null,
+	};
+}
+
 export async function recordInvestigationFinding(
 	db: SqlDb,
 	projectId: string,
@@ -237,23 +329,86 @@ export async function recordInvestigationFinding(
 		.trim()
 		.toLowerCase();
 
-	const defaultOriginNode = input.faultLocusEntityId.includes(":")
-		? input.faultLocusEntityId
+	// Idempotent retries: one key maps to one finding id per project and
+	// environment, and a replay returns the stored finding untouched.
+	const idempotencyKey = input.idempotencyKey?.trim();
+	let idempotencyId: string | undefined;
+	if (idempotencyKey) {
+		idempotencyId = `fnd_k${(await sha256Hex(`${projectId}\u0000${environment}\u0000${idempotencyKey}`)).slice(0, 20)}`;
+		const replay = await getInvestigationFinding(
+			db,
+			projectId,
+			idempotencyId,
+			environment,
+		);
+		if (replay) return replay;
+	}
+
+	// Findings pointing at a span id (no colon) must not mint a per-incident
+	// fingerprint. Resolve the span to its service/operation/error signature so
+	// every incident on the same service + route + error shares one identity.
+	// Caller-supplied fingerprint fields always win; unknown spans fall back to
+	// treating the locus id as a service name.
+	const supplied: Partial<FindingFingerprintInput> =
+		input.fingerprintInput ?? {};
+	const locusId = input.faultLocusEntityId.trim();
+	let spanDerived: Partial<FindingFingerprintInput> = {};
+	const traceSpan =
+		input.faultLocusEntityKind === "span" ? splitTraceSpanLocus(locusId) : null;
+	if (traceSpan) {
+		const spanRow = await loadFaultLocusSpan(
+			db,
+			projectId,
+			environment,
+			traceSpan.spanId,
+			traceSpan.traceId,
+		);
+		if (spanRow) spanDerived = fingerprintInputFromSpan(spanRow, environment);
+	} else if (
+		!locusId.includes(":") &&
+		input.faultLocusEntityKind !== "service"
+	) {
+		const spanRow = await loadFaultLocusSpan(
+			db,
+			projectId,
+			environment,
+			locusId,
+		);
+		if (spanRow) spanDerived = fingerprintInputFromSpan(spanRow, environment);
+	}
+	const defaultOriginNode = locusId.includes(":")
+		? traceSpan
+			? buildCanonicalNodeId({
+					kind: "service",
+					environment,
+					serviceName: locusId,
+				}).id
+			: locusId
 		: buildCanonicalNodeId({
 				kind: "service",
 				environment,
-				serviceName: input.faultLocusEntityId,
+				serviceName: locusId,
 			}).id;
 
-	const fpResult = buildFindingFingerprint(
-		input.fingerprintInput ?? {
-			environment,
-			originatingNodeId: defaultOriginNode,
-			normalizedOperation: input.title,
-			errorSignature: input.summary.slice(0, 120),
-			downstreamTargetNodeId: null,
-		},
-	);
+	const fpResult = buildFindingFingerprint({
+		environment: supplied.environment ?? environment,
+		originatingNodeId:
+			supplied.originatingNodeId ??
+			spanDerived.originatingNodeId ??
+			defaultOriginNode,
+		normalizedOperation:
+			supplied.normalizedOperation ??
+			spanDerived.normalizedOperation ??
+			input.title,
+		errorSignature:
+			supplied.errorSignature ??
+			spanDerived.errorSignature ??
+			input.summary.slice(0, 120),
+		downstreamTargetNodeId:
+			supplied.downstreamTargetNodeId ??
+			spanDerived.downstreamTargetNodeId ??
+			null,
+	});
 
 	// Check for prior verified findings with the same stable fingerprint
 	const priorRow = await db
@@ -346,7 +501,7 @@ export async function recordInvestigationFinding(
 		finalConfidence: confidence,
 	};
 
-	const id = input.id?.trim() || `fnd_${randomHex(10)}`;
+	const id = idempotencyId ?? (input.id?.trim() || `fnd_${randomHex(10)}`);
 	const expiresAt = new Date(Date.now() + 90 * 24 * 3600_000).toISOString();
 
 	await db