@obsunified/collector 2.0.1 → 2.2.0

package/src/plugins/connected-routes/manifest.ts

@@ -1,3 +1,7 @@
+import type {
+	CausalProofTier,
+	RelationshipCertainty,
+} from "@obsunified/types";
 import type {
 	ActionRef,
 	AICallRef,
@@ -26,7 +30,10 @@ export type ConnectedEntityKind =
 	| "user"
 	| "action"
 	| "agent_run"
-	| "tool_call";
+	| "tool_call"
+	| "change"
+	| "finding"
+	| "incident";
 
 export const KNOWN_KINDS: ReadonlySet<string> = new Set<ConnectedEntityKind>([
 	"span",
@@ -41,6 +48,9 @@ export const KNOWN_KINDS: ReadonlySet<string> = new Set<ConnectedEntityKind>([
 	"action",
 	"agent_run",
 	"tool_call",
+	"change",
+	"finding",
+	"incident",
 ]);
 
 export interface ConnectedLink {
@@ -54,6 +64,8 @@ export interface ConnectedLink {
 	confidence?: number;
 	reason?: string;
 	causalConfidence?: CausalConfidence;
+	relationshipCertainty?: RelationshipCertainty;
+	causalProofTier?: CausalProofTier;
 }
 
 export interface ConnectedSection {

package/src/plugins/connected-routes.test.ts

@@ -1789,3 +1789,109 @@ describe("ConnectedRail manifest — agent action graph entities (RFC 0010)", ()
 		expect(otherTools?.links[0].label).toContain("other_tool");
 	});
 });
+
+describe("ConnectedRail manifest — span parent session link", () => {
+	it("surfaces parent session link under Up when interaction usage event has session_id", async () => {
+		const db = new MemSqlDb({
+			all: (sql) => {
+				if (sql.includes("FROM telemetry_spans")) {
+					return [
+						{
+							trace_id: "tr-payment",
+							span_id: "sp-payment",
+							parent_span_id: null,
+							service_name: "checkout-api",
+							span_name: "payment.charge",
+							status_code: 1,
+							status_message: null,
+							start_time: "2026-05-04T10:00:00Z",
+							duration_ms: 700,
+							interaction_id: "int-checkout-click",
+						},
+					];
+				}
+				if (sql.includes("FROM usage_events")) {
+					return [
+						{
+							event_id: "evt-click-1",
+							event_type: "interaction",
+							event_name: "click_checkout",
+							page_path: "/api/checkout",
+							severity: null,
+							occurred_at: "2026-05-04T10:00:00Z",
+							interaction_id: "int-checkout-click",
+							session_id: "session-abc-123456",
+						},
+					];
+				}
+				return [];
+			},
+			first: () => null,
+		});
+		const fetch = setup(db);
+		const m = await fetch("/internal/connected/span/tr-payment:sp-payment");
+
+		// Preserves parent trace link
+		const traceSection = m.up.find((s) => s.label === "Trace");
+		expect(traceSection).toBeDefined();
+		expect(traceSection?.links[0]).toMatchObject({
+			entityKind: "trace",
+			entityId: "tr-payment",
+		});
+
+		// Surfaces parent session link via linkToSession
+		const sessionSection = m.up.find((s) =>
+			s.label.toLowerCase().includes("session"),
+		);
+		expect(sessionSection).toBeDefined();
+		expect(sessionSection?.links[0]).toMatchObject({
+			entityKind: "replay",
+			sample: "session-abc-123456",
+			href: "#/replay?session=session-abc-123456",
+		});
+
+		// Preserves originating click link in Related
+		const clickSection = m.related.find((s) =>
+			s.label.toLowerCase().includes("click"),
+		);
+		expect(clickSection).toBeDefined();
+		expect(clickSection?.links.length).toBeGreaterThan(0);
+	});
+
+	it("preserves informative absence when span has no interaction or session", async () => {
+		const db = new MemSqlDb({
+			all: (sql) => {
+				if (sql.includes("FROM telemetry_spans")) {
+					return [
+						{
+							trace_id: "tr-cron",
+							span_id: "sp-cron",
+							parent_span_id: null,
+							service_name: "worker",
+							span_name: "cron.tick",
+							status_code: 1,
+							status_message: null,
+							start_time: "2026-05-04T10:00:00Z",
+							duration_ms: 100,
+							interaction_id: null,
+						},
+					];
+				}
+				return [];
+			},
+			first: () => null,
+		});
+		const fetch = setup(db);
+		const m = await fetch("/internal/connected/span/tr-cron:sp-cron");
+
+		expect(m.up).toHaveLength(1);
+		expect(m.up[0].label).toBe("Trace");
+
+		const clickSection = m.related.find((s) =>
+			s.label.toLowerCase().includes("click"),
+		);
+		expect(clickSection).toBeDefined();
+		expect(clickSection?.links).toEqual([]);
+		expect(clickSection?.emptyReason).toContain("Server-originated work");
+	});
+});

package/src/plugins/connected-routes.ts

@@ -289,12 +289,25 @@ export const connectedRoutesPlugin: CollectorPlugin = {
 					const otherSpans = traceManifest.spans.filter(
 						(s) => s.spanId !== span.spanId,
 					);
+					const interactionManifest = span.interactionId
+						? await index.byInteraction(projectId, span.interactionId)
+						: null;
+					const parentSessionId = interactionManifest?.usageEvents.find((e) =>
+						Boolean(e.sessionId),
+					)?.sessionId;
+
 					manifest.up = [
 						{
 							label: "Trace",
 							links: [linkToTrace(span.traceId, "Parent trace")],
 						},
 					];
+					if (parentSessionId) {
+						manifest.up.push({
+							label: "User session",
+							links: [linkToSession(parentSessionId)],
+						});
+					}
 					manifest.across = [
 						linksFromSpans(otherSpans, `Other spans in this trace`),
 						linksFromLogs(traceManifest.logs, "Logs in this trace"),
@@ -339,11 +352,7 @@ export const connectedRoutesPlugin: CollectorPlugin = {
 							"Metric exemplars in this trace",
 						),
 					];
-					if (span.interactionId) {
-						const interactionManifest = await index.byInteraction(
-							projectId,
-							span.interactionId,
-						);
+					if (interactionManifest) {
 						manifest.related = [
 							linksFromUsage(
 								interactionManifest.usageEvents,
@@ -1040,6 +1049,277 @@ export const connectedRoutesPlugin: CollectorPlugin = {
 						manifest.rawManifest = actionManifest;
 					}
 				}
+			} else if (kind === "change") {
+				const db = sqlDbFor(c.env);
+				const changeRow = await db
+					.prepare(
+						`SELECT * FROM change_events WHERE project_id = ? AND id = ? LIMIT 1`,
+					)
+					.bind(projectId, id)
+					.first<{
+						id: string;
+						environment: string;
+						kind: string;
+						target_node_id: string;
+						service_name: string | null;
+						version: string | null;
+						previous_version: string | null;
+						commit_sha: string | null;
+						summary: string;
+					}>();
+				if (changeRow) {
+					manifest.up = [
+						{
+							label: "Target Ontology Node",
+							links: [
+								{
+									label: `${changeRow.target_node_id} (${changeRow.environment})`,
+									href: `#/health?node=${encodeURIComponent(changeRow.target_node_id)}`,
+									relationshipCertainty: "exact",
+									reason: "Target node mutated by this change event.",
+								},
+							],
+						},
+					];
+
+					const findings = await db
+						.prepare(
+							`SELECT id, title, causal_proof_tier, confidence, incident_id
+							 FROM investigation_findings
+							 WHERE project_id = ? AND environment = ? AND contributing_change_id = ?
+							 ORDER BY created_at DESC LIMIT 10`,
+						)
+						.bind(projectId, changeRow.environment, changeRow.id)
+						.all<{
+							id: string;
+							title: string;
+							causal_proof_tier: string;
+							confidence: number;
+							incident_id: string | null;
+						}>();
+
+					manifest.down = [
+						{
+							label: "Attributed Findings",
+							links: findings.results.map((f) => ({
+								label: f.title,
+								href: `#/findings/${encodeURIComponent(f.id)}`,
+								entityKind: "finding",
+								entityId: f.id,
+								relationshipCertainty: "exact",
+								causalProofTier:
+									f.causal_proof_tier as import("@obsunified/types").CausalProofTier,
+								confidence: f.confidence,
+								reason: "Finding attributes this change event.",
+							})),
+							emptyReason:
+								findings.results.length === 0
+									? "No investigation findings cite this change event."
+									: undefined,
+						},
+					];
+
+					const spans = changeRow.version
+						? await db
+								.prepare(
+									`SELECT DISTINCT trace_id, span_id, service_name, span_name
+									 FROM telemetry_spans
+									 WHERE project_id = ? AND environment = ? AND service_version = ? AND status_code = 2
+									 ORDER BY start_time DESC LIMIT 5`,
+								)
+								.bind(projectId, changeRow.environment, changeRow.version)
+								.all<{
+									trace_id: string;
+									span_id: string;
+									service_name: string;
+									span_name: string;
+								}>()
+						: { results: [] };
+
+					manifest.across = [
+						{
+							label: "Failing Spans on Cohort Version",
+							links: spans.results.map((s) => ({
+								label: `${s.service_name} · ${s.span_name}`,
+								href: `#/traces/${s.trace_id}#span=${s.span_id}`,
+								entityKind: "span",
+								entityId: `${s.trace_id}:${s.span_id}`,
+								relationshipCertainty: "exact",
+								reason: `Span executed on version ${changeRow.version}.`,
+							})),
+							emptyReason:
+								spans.results.length === 0
+									? "No failing spans recorded on this change version."
+									: undefined,
+						},
+					];
+				}
+			} else if (kind === "finding") {
+				const db = sqlDbFor(c.env);
+				const findingRow = await db
+					.prepare(
+						`SELECT * FROM investigation_findings WHERE project_id = ? AND id = ? LIMIT 1`,
+					)
+					.bind(projectId, id)
+					.first<{
+						id: string;
+						environment: string;
+						incident_id: string | null;
+						title: string;
+						causal_proof_tier: string;
+						confidence: number;
+						symptom_entity_kind: string;
+						symptom_entity_id: string;
+						fault_locus_entity_kind: string;
+						fault_locus_entity_id: string;
+						contributing_change_id: string | null;
+						contending_trace_id: string | null;
+						agent_run_id: string | null;
+					}>();
+				if (findingRow) {
+					const proofTier =
+						findingRow.causal_proof_tier as import("@obsunified/types").CausalProofTier;
+					manifest.up = [];
+					if (findingRow.incident_id) {
+						manifest.up.push({
+							label: "Incident Investigation",
+							links: [
+								{
+									label: `incident ${findingRow.incident_id}`,
+									href: `#/incidents/${encodeURIComponent(findingRow.incident_id)}`,
+									entityKind: "incident",
+									entityId: findingRow.incident_id,
+									relationshipCertainty: "exact",
+									causalProofTier: proofTier,
+								},
+							],
+						});
+					}
+					if (findingRow.contributing_change_id) {
+						manifest.up.push({
+							label: "Contributing Change",
+							links: [
+								{
+									label: `change ${findingRow.contributing_change_id}`,
+									href: `#/changes/${encodeURIComponent(findingRow.contributing_change_id)}`,
+									entityKind: "change",
+									entityId: findingRow.contributing_change_id,
+									relationshipCertainty: "exact",
+									causalProofTier: proofTier,
+									confidence: findingRow.confidence,
+								},
+							],
+						});
+					}
+					manifest.across = [
+						{
+							label: "Fault Locus & Symptom",
+							links: [
+								{
+									label: `fault locus: ${findingRow.fault_locus_entity_id}`,
+									href: `#/traces?q=${encodeURIComponent(findingRow.fault_locus_entity_id)}`,
+									relationshipCertainty: "exact",
+									causalProofTier: proofTier,
+								},
+								...(findingRow.contending_trace_id
+									? [
+											{
+												label: `contending trace ${findingRow.contending_trace_id}`,
+												href: `#/traces/${encodeURIComponent(findingRow.contending_trace_id)}`,
+												entityKind: "trace" as const,
+												entityId: findingRow.contending_trace_id,
+												relationshipCertainty: "inferred" as const,
+												causalProofTier: proofTier,
+											},
+										]
+									: []),
+							],
+						},
+					];
+					manifest.down = [
+						{
+							label: "Agent Lineage",
+							links: [
+								...(findingRow.agent_run_id
+									? [
+											{
+												...linkToAgentRun(findingRow.agent_run_id),
+												relationshipCertainty: "exact" as const,
+												causalProofTier: proofTier,
+											},
+										]
+									: []),
+							],
+							emptyReason: !findingRow.agent_run_id
+								? "No agent run linked to this finding."
+								: undefined,
+						},
+					];
+				}
+			} else if (kind === "incident") {
+				const db = sqlDbFor(c.env);
+				const incRow = await db
+					.prepare(
+						`SELECT * FROM incident_investigations WHERE project_id = ? AND id = ? LIMIT 1`,
+					)
+					.bind(projectId, id)
+					.first<{
+						id: string;
+						environment: string;
+						target_node_id: string;
+						symptom_anchor_kind: string;
+						symptom_anchor_id: string;
+						status: string;
+					}>();
+				if (incRow) {
+					manifest.up = [
+						{
+							label: "Trigger Signal",
+							links: [
+								{
+									label: `${incRow.symptom_anchor_kind}: ${incRow.symptom_anchor_id}`,
+									href: `#/alerts?id=${encodeURIComponent(incRow.symptom_anchor_id)}`,
+									entityKind:
+										incRow.symptom_anchor_kind === "analysis"
+											? "analysis"
+											: "alert",
+									entityId: incRow.symptom_anchor_id,
+									relationshipCertainty: "exact",
+								},
+							],
+						},
+					];
+					const incFindings = await db
+						.prepare(
+							`SELECT id, title, causal_proof_tier FROM investigation_findings
+							 WHERE project_id = ? AND incident_id = ?
+							 ORDER BY created_at DESC LIMIT 5`,
+						)
+						.bind(projectId, incRow.id)
+						.all<{
+							id: string;
+							title: string;
+							causal_proof_tier: string;
+						}>();
+					manifest.across = [
+						{
+							label: "Findings",
+							links: incFindings.results.map((f) => ({
+								label: f.title,
+								href: `#/findings/${encodeURIComponent(f.id)}`,
+								entityKind: "finding" as const,
+								entityId: f.id,
+								relationshipCertainty: "exact" as const,
+								causalProofTier:
+									f.causal_proof_tier as import("@obsunified/types").CausalProofTier,
+							})),
+							emptyReason:
+								incFindings.results.length > 0
+									? undefined
+									: "No finding recorded for this incident yet.",
+						},
+					];
+				}
 			} else if (kind === "alert" || kind === "analysis") {
 				// Alerts and Analyses are topic-related, not identity-related.
 				// Their connections come from the alert_rules.analysis_id and

package/src/plugins/dashboard-routes.test.ts

@@ -0,0 +1,120 @@
+/**
+ * Dashboard auth used to guard `/dashboard/login` itself, and the SPA
+ * fallback redirected `/dashboard/*` to `/dashboard/` — which it also
+ * matched. A browser hitting `/` on a collector without an assets binding
+ * bounced forever. These tests follow the redirect chain by hand.
+ */
+
+import { describe, expect, it } from "vitest";
+import { createDashboardAuth } from "../auth/dashboard-auth";
+import {
+	createTelemetryCollectorApp,
+	isDashboardLoginPath,
+} from "../framework/collector";
+import type { CollectorEnv } from "../framework/env";
+import { MemSqlDb } from "../lib/test-utils/mem-sql-db";
+import { dashboardRoutesPlugin } from "./dashboard-routes";
+
+const HTML = { Accept: "text/html,application/xhtml+xml" };
+
+const makeApp = (auth: Parameters<typeof createDashboardAuth>[0]) =>
+	createTelemetryCollectorApp({
+		plugins: [dashboardRoutesPlugin],
+		dashboardAuth: createDashboardAuth(auth),
+	});
+
+const env = (extra: Record<string, unknown> = {}) =>
+	({ DB: new MemSqlDb(), ...extra }) as unknown as CollectorEnv;
+
+/** Follow same-origin redirects; returns every path visited plus the final response. */
+const follow = async (
+	app: ReturnType<typeof makeApp>,
+	path: string,
+	headers: Record<string, string>,
+	maxHops = 6,
+) => {
+	const visited: string[] = [];
+	let current = path;
+	for (let hop = 0; hop < maxHops; hop += 1) {
+		visited.push(current);
+		const res = await app.request(current, { headers }, env());
+		const location = res.headers.get("Location");
+		if (res.status < 300 || res.status >= 400 || !location) {
+			return { visited, res };
+		}
+		current = location;
+	}
+	throw new Error(`redirect loop: ${visited.join(" -> ")}`);
+};
+
+describe("dashboard routes + auth", () => {
+	it("isDashboardLoginPath matches the login page and its sub-routes only", () => {
+		expect(isDashboardLoginPath("/dashboard/login")).toBe(true);
+		expect(isDashboardLoginPath("/dashboard/login/")).toBe(true);
+		expect(isDashboardLoginPath("/dashboard/login/forgot")).toBe(true);
+		expect(isDashboardLoginPath("/dashboard/loginx")).toBe(false);
+		expect(isDashboardLoginPath("/dashboard/")).toBe(false);
+		expect(isDashboardLoginPath("/internal/login")).toBe(false);
+	});
+
+	it("an unauthenticated browser at / reaches the login page without looping", async () => {
+		const app = makeApp({ password: "pw" });
+		const { visited, res } = await follow(app, "/", HTML);
+		expect(visited).toEqual(["/", "/dashboard/", "/dashboard/login"]);
+		// No assets binding: the login page cannot be served here, but the
+		// chain must end instead of bouncing back to /dashboard/.
+		expect(res.status).toBe(404);
+		expect(res.headers.get("Location")).toBeNull();
+		await expect(res.json()).resolves.toMatchObject({
+			error: expect.stringContaining("Dashboard assets are not configured"),
+		});
+	});
+
+	it("still redirects unauthenticated HTML requests for other dashboard pages to login", async () => {
+		const app = makeApp({ password: "pw" });
+		const res = await app.request(
+			"/dashboard/traces",
+			{ headers: HTML },
+			env(),
+		);
+		expect(res.status).toBe(302);
+		expect(res.headers.get("Location")).toBe("/dashboard/login");
+	});
+
+	it("does not redirect /dashboard/login to itself", async () => {
+		const app = makeApp({ password: "pw" });
+		const res = await app.request("/dashboard/login", { headers: HTML }, env());
+		expect(res.status).toBe(404);
+		expect(res.headers.get("Location")).toBeNull();
+	});
+
+	it("an authenticated request without assets does not loop on /dashboard/", async () => {
+		const app = makeApp({ token: "tok" });
+		const headers = { ...HTML, Authorization: "Bearer tok" };
+		const { visited, res } = await follow(app, "/", headers);
+		expect(visited).toEqual(["/", "/dashboard/"]);
+		expect(res.status).toBe(404);
+	});
+
+	it("serves the SPA entrypoint from the assets binding for deep links", async () => {
+		const app = makeApp({ token: "tok" });
+		const fetched: string[] = [];
+		const assets = {
+			fetch: async (req: Request) => {
+				fetched.push(new URL(req.url).pathname);
+				return new Response("<html>spa</html>", {
+					status: 200,
+					headers: { "content-type": "text/html" },
+				});
+			},
+		};
+		const res = await app.request(
+			"/dashboard/traces/abc",
+			{ headers: { ...HTML, Authorization: "Bearer tok" } },
+			env({ ASSETS: assets }),
+		);
+		expect(res.status).toBe(200);
+		expect(await res.text()).toBe("<html>spa</html>");
+		expect(fetched).toEqual(["/dashboard/"]);
+	});
+});

package/src/plugins/dashboard-routes.ts

@@ -29,8 +29,17 @@ export const dashboardRoutesPlugin: CollectorPlugin = {
 				url.pathname = "/dashboard/";
 				return assets.fetch(new Request(url.toString(), c.req.raw));
 			}
-			// Fallback: redirects to SPA root
-			return c.redirect("/dashboard/");
+			// No assets binding: there is nothing to serve. Redirecting to
+			// `/dashboard/` here would match this same route and loop forever
+			// (and bounce unauthenticated browsers between `/dashboard/` and
+			// `/dashboard/login` endlessly).
+			return c.json(
+				{
+					error:
+						"Dashboard assets are not configured on this collector. Serve @obsunified/dashboard separately or bind [assets] in wrangler.toml.",
+				},
+				404,
+			);
 		});
 
 		// Root redirect: visiting the collector root goes to dashboard

package/src/plugins/default-span-enrichment.ts

@@ -4,6 +4,7 @@ import {
 	SESSION_ID_KEY,
 } from "@obsunified/types/constants";
 import type { CollectorPlugin } from "../framework/collector";
+import { extractSpanLineageAndTopology } from "../lib/autosre-ontology";
 import { parseJsonRecord } from "../lib/json";
 
 export const defaultSpanEnrichmentPlugin: CollectorPlugin = {
@@ -77,7 +78,7 @@ export const defaultSpanEnrichmentPlugin: CollectorPlugin = {
 							? (resourceAttributes["telemetry.sdk.name"] as string)
 							: null;
 
-					return {
+					const candidate: StoredSpan = {
 						...span,
 						serviceName,
 						attributesJson: JSON.stringify(normalizedAttributes),
@@ -85,6 +86,17 @@ export const defaultSpanEnrichmentPlugin: CollectorPlugin = {
 						interactionId,
 						telemetrySdkName,
 					};
+
+					const lineage = extractSpanLineageAndTopology(candidate);
+
+					return {
+						...candidate,
+						environment: lineage.environment,
+						serviceVersion: lineage.serviceVersion,
+						commitSha: lineage.commitSha,
+						targetNodeId: lineage.targetNode?.id ?? null,
+						errorSignature: lineage.errorSignature,
+					};
 				});
 			},
 		});