@obsunified/collector 2.0.1

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

@@ -0,0 +1,109 @@
+import type {
+	AISpanRecord,
+	AISpansOverviewOptions,
+	AISpansOverviewResponse,
+	JsonValue,
+} from "@obsunified/types";
+import { parseJsonRecord } from "../json";
+import { dialectFor, type SqlDb } from "../sql-db";
+import { enrichCost } from "./helpers";
+import type { AISpanRow } from "./types";
+import { clampInt } from "./types";
+
+export async function getAISpansOverview(
+	db: SqlDb,
+	options: AISpansOverviewOptions,
+): Promise<AISpansOverviewResponse> {
+	if (!options.projectId)
+		throw new Error("AIStore.getAISpans: projectId is required");
+	const dialect = dialectFor(db);
+	const hours = clampInt(options.hours, 1, 720, 24);
+	const limit = clampInt(options.limit, 1, 1000, 100);
+
+	let sql = `
+      SELECT
+        s.trace_id            AS trace_id,
+        s.span_id             AS span_id,
+        s.parent_span_id      AS parent_span_id,
+        s.service_name        AS service_name,
+        s.span_name           AS span_name,
+        s.status_code         AS status_code,
+        s.status_message      AS status_message,
+        s.start_time          AS start_time,
+        s.end_time            AS end_time,
+        s.duration_ms         AS duration_ms,
+        s.attributes_json     AS attributes_json,
+        p.span_kind           AS span_kind,
+        p.input_json          AS input_json,
+        p.output_json         AS output_json
+      FROM ai_span_payloads p
+      INNER JOIN telemetry_spans s
+        ON s.trace_id = p.trace_id AND s.span_id = p.span_id
+      WHERE p.project_id = ?
+        AND p.received_at >= ${dialect.sinceHours("?")}
+    `;
+	const params: unknown[] = [options.projectId, hours];
+
+	if (options.kind) {
+		sql += ` AND p.span_kind = ?`;
+		params.push(options.kind);
+	}
+	if (options.service) {
+		sql += ` AND s.service_name = ?`;
+		params.push(options.service);
+	}
+	if (options.traceId) {
+		sql += ` AND s.trace_id = ?`;
+		params.push(options.traceId);
+	}
+
+	sql += ` ORDER BY s.start_time DESC LIMIT ?`;
+	params.push(limit);
+
+	const results = await db
+		.prepare(sql)
+		.bind(...params)
+		.all<AISpanRow>();
+
+	const spans: AISpanRecord[] = (results.results || []).map((row) => {
+		const attrs = parseJsonRecord(row.attributes_json) as Record<
+			string,
+			JsonValue
+		>;
+		enrichCost(attrs);
+		return {
+			traceId: row.trace_id,
+			spanId: row.span_id,
+			parentSpanId: row.parent_span_id,
+			serviceName: row.service_name,
+			spanName: row.span_name,
+			spanKind: row.span_kind,
+			statusCode: row.status_code ?? 0,
+			statusMessage: row.status_message,
+			startTime: row.start_time,
+			endTime: row.end_time ?? row.start_time,
+			durationMs: row.duration_ms ?? 0,
+			attributes: attrs,
+			inputJson: row.input_json,
+			outputJson: row.output_json,
+		};
+	});
+
+	const byKind: Record<string, number> = {};
+	let errorSpans = 0;
+	for (const span of spans) {
+		byKind[span.spanKind] = (byKind[span.spanKind] ?? 0) + 1;
+		if (span.statusCode === 2) errorSpans++;
+	}
+
+	return {
+		spans,
+		summary: {
+			totalSpans: spans.length,
+			byKind,
+			errorSpans,
+		},
+		windowHours: hours,
+		timestamp: new Date().toISOString(),
+	};
+}

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

@@ -0,0 +1,112 @@
+import type { AICallRecord, AIEvaluationSource } from "@obsunified/types";
+
+export interface IngestEvaluation {
+	projectId: string;
+	evaluationId: string;
+	traceId: string;
+	spanId: string;
+	name: string;
+	score: number | null;
+	label: string | null;
+	explanation: string | null;
+	source: AIEvaluationSource;
+	metadataJson: string | null;
+	createdAt: string;
+	expiresAt: string;
+}
+
+/** Clamp an integer to a safe range */
+export const clampInt = (
+	value: unknown,
+	min: number,
+	max: number,
+	fallback: number,
+): number => {
+	const n = typeof value === "number" ? value : parseInt(String(value), 10);
+	if (!Number.isFinite(n)) return fallback;
+	return Math.max(min, Math.min(max, n));
+};
+
+export interface AICallRow {
+	project_id?: string;
+	call_id: string;
+	trace_id: string | null;
+	span_id: string | null;
+	service_name: string | null;
+	model_name: string;
+	provider: string;
+	call_type: AICallRecord["callType"];
+	request_json: string | null;
+	response_json: string | null;
+	prompt_tokens: number | null;
+	completion_tokens: number | null;
+	total_cost_usd: number | null;
+	latency_ms: number | null;
+	is_error: number;
+	error_message: string | null;
+	occurred_at: string;
+	received_at: string;
+	expires_at: string;
+	session_id: string | null;
+	interaction_id: string | null;
+}
+
+export interface AICallSummaryRow {
+	totalCalls?: number;
+	totalCostUsd?: number;
+	totalPromptTokens?: number;
+	totalCompletionTokens?: number;
+	errorCalls?: number;
+}
+
+export interface AISpanRow {
+	trace_id: string;
+	span_id: string;
+	parent_span_id: string | null;
+	service_name: string | null;
+	span_name: string;
+	span_kind: string;
+	status_code: number | null;
+	status_message: string | null;
+	start_time: string;
+	end_time: string | null;
+	duration_ms: number | null;
+	attributes_json: string | null;
+	input_json: string | null;
+	output_json: string | null;
+	user_id?: string | null;
+}
+
+export interface AISessionRow {
+	session_id: string;
+	user_id: string | null;
+	span_count: number | null;
+	llm_span_count: number | null;
+	error_count: number | null;
+	prompt_tokens: number | null;
+	completion_tokens: number | null;
+	cost_usd: number | null;
+	first_span_at: string;
+	last_span_at: string;
+	trace_count: number | null;
+}
+
+export interface AISessionPreviewRow {
+	session_id: string;
+	input_json: string | null;
+}
+
+export interface AIEvaluationRow {
+	evaluation_id: string;
+	project_id: string;
+	trace_id: string;
+	span_id: string;
+	name: string;
+	score: number | null;
+	label: string | null;
+	explanation: string | null;
+	source: AIEvaluationSource;
+	metadata_json: string | null;
+	created_at: string;
+	expires_at: string;
+}

package/src/lib/ai-store.ts

@@ -0,0 +1,76 @@
+import type {
+	AICallRecord,
+	AICallsOverviewOptions,
+	AICallsOverviewResponse,
+	AIEvaluationsListOptions,
+	AIEvaluationsListResponse,
+	AISessionDetailResponse,
+	AISessionsListOptions,
+	AISessionsListResponse,
+	AISpansOverviewOptions,
+	AISpansOverviewResponse,
+} from "@obsunified/types";
+import { getAICallsOverview, ingestAICallBatch } from "./ai-store/calls";
+import {
+	getAIEvaluation,
+	ingestAIEvaluations,
+	listAIEvaluations,
+} from "./ai-store/evaluations";
+import { purgeExpiredAIData } from "./ai-store/retention";
+import { getAISessionDetail, listAISessions } from "./ai-store/sessions";
+import { getAISpansOverview } from "./ai-store/spans";
+import type { IngestEvaluation } from "./ai-store/types";
+import type { SqlDb } from "./sql-db";
+
+export type { IngestEvaluation } from "./ai-store/types";
+
+export class AIStore {
+	constructor(private readonly db: SqlDb) {}
+
+	async ingestBatch(calls: AICallRecord[]): Promise<void> {
+		return ingestAICallBatch(this.db, calls);
+	}
+
+	async getAICalls(
+		options: AICallsOverviewOptions,
+	): Promise<AICallsOverviewResponse> {
+		return getAICallsOverview(this.db, options);
+	}
+
+	async purgeExpired(): Promise<number> {
+		return purgeExpiredAIData(this.db);
+	}
+
+	async getAISpans(
+		options: AISpansOverviewOptions,
+	): Promise<AISpansOverviewResponse> {
+		return getAISpansOverview(this.db, options);
+	}
+
+	async listSessions(
+		options: AISessionsListOptions,
+	): Promise<AISessionsListResponse> {
+		return listAISessions(this.db, options);
+	}
+
+	async getSession(
+		projectId: string,
+		sessionId: string,
+	): Promise<AISessionDetailResponse> {
+		return getAISessionDetail(this.db, projectId, sessionId);
+	}
+
+	async ingestEvaluations(evaluations: IngestEvaluation[]): Promise<void> {
+		return ingestAIEvaluations(this.db, evaluations);
+	}
+
+	async listEvaluations(
+		options: AIEvaluationsListOptions,
+	): Promise<AIEvaluationsListResponse> {
+		return listAIEvaluations(this.db, options);
+	}
+
+	async getEvaluation(projectId: string, evaluationId: string) {
+		return getAIEvaluation(this.db, projectId, evaluationId);
+	}
+}