agent-telemetry 0.1.0 → 0.2.0

package/src/adapters/fetch.ts

@@ -0,0 +1,133 @@
+/**
+ * Traced Fetch Adapter
+ *
+ * Wraps fetch with telemetry for external service calls. Does NOT monkey-patch
+ * the global — returns a new function with identical semantics.
+ *
+ * duration_ms measures time-to-headers (TTFB), not total transfer time.
+ * The Response object is returned untouched — streaming bodies work correctly.
+ *
+ * @example
+ * ```ts
+ * import { createTelemetry, type ExternalEvents } from 'agent-telemetry'
+ * import { createTracedFetch } from 'agent-telemetry/fetch'
+ *
+ * const telemetry = await createTelemetry<ExternalEvents>()
+ * const fetch = createTracedFetch({ telemetry })
+ *
+ * const res = await fetch('https://api.example.com/users')
+ * ```
+ */
+
+import { generateSpanId, generateTraceId } from "../ids.ts";
+import type { ExternalCallEvent, Telemetry } from "../types.ts";
+
+/** Callable fetch signature (without static properties like `preconnect`). */
+export type FetchFn = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
+/** Options for the traced fetch adapter. */
+export interface TracedFetchOptions {
+	/** Telemetry instance to emit events through. */
+	telemetry: Telemetry<ExternalCallEvent>;
+	/** Base fetch implementation. Default: globalThis.fetch. */
+	baseFetch?: FetchFn;
+	/** Provide trace context for correlating with a parent HTTP request. */
+	getTraceContext?: () => { traceId: string; parentSpanId?: string } | undefined;
+	/** Guard function — return false to skip tracing. */
+	isEnabled?: () => boolean;
+}
+
+/**
+ * Extract URL metadata from the three fetch input types.
+ * This is metadata-only — the original input is never modified.
+ */
+function resolveInput(input: RequestInfo | URL): {
+	url: string;
+	method: string;
+} {
+	if (input instanceof Request) {
+		return { url: input.url, method: input.method };
+	}
+	if (input instanceof URL) {
+		return { url: input.href, method: "GET" };
+	}
+	// string — try absolute first, then relative with localhost fallback
+	try {
+		return { url: new URL(input).href, method: "GET" };
+	} catch {
+		return {
+			url: new URL(input, "http://localhost").href,
+			method: "GET",
+		};
+	}
+}
+
+/**
+ * Create a traced fetch function that emits external.call telemetry events.
+ *
+ * The returned function has the same signature as globalThis.fetch.
+ * The original input and init are passed through to baseFetch untouched.
+ * Non-2xx responses are returned normally (not thrown). Network errors
+ * are emitted as status "error" and re-thrown.
+ */
+export function createTracedFetch(options: TracedFetchOptions): FetchFn {
+	const { telemetry, baseFetch = globalThis.fetch, getTraceContext, isEnabled } = options;
+
+	return async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+		if (isEnabled && !isEnabled()) {
+			return baseFetch(input, init);
+		}
+
+		const { url, method: resolvedMethod } = resolveInput(input);
+		const method = init?.method?.toUpperCase() ?? resolvedMethod;
+
+		let service = "unknown";
+		let pathname = "/";
+		try {
+			const parsed = new URL(url);
+			service = parsed.hostname;
+			pathname = parsed.pathname;
+		} catch {
+			// keep defaults
+		}
+
+		const operation = `${method} ${pathname}`;
+
+		const ctx = getTraceContext?.();
+		const traceId = ctx?.traceId ?? generateTraceId();
+		const spanId = generateSpanId();
+
+		const start = performance.now();
+
+		try {
+			const response = await baseFetch(input, init);
+			const duration_ms = Math.round(performance.now() - start);
+
+			telemetry.emit({
+				kind: "external.call",
+				traceId,
+				spanId,
+				service,
+				operation,
+				duration_ms,
+				status: "success",
+			});
+
+			return response;
+		} catch (err) {
+			const duration_ms = Math.round(performance.now() - start);
+
+			telemetry.emit({
+				kind: "external.call",
+				traceId,
+				spanId,
+				service,
+				operation,
+				duration_ms,
+				status: "error",
+			});
+
+			throw err;
+		}
+	};
+}

package/src/adapters/hono.ts

@@ -21,6 +21,7 @@
 
 import type { Context, MiddlewareHandler } from "hono";
 import { extractEntities } from "../entities.ts";
+import { toSafeErrorLabel } from "../error.ts";
 import { generateSpanId, generateTraceId } from "../ids.ts";
 import { formatTraceparent, parseTraceparent } from "../traceparent.ts";
 import type { EntityPattern, HttpRequestEvent, Telemetry } from "../types.ts";
@@ -67,7 +68,7 @@ export function createHonoTrace(options: HonoTraceOptions): MiddlewareHandler {
 		try {
 			await next();
 		} catch (err) {
-			error = err instanceof Error ? err.message : "Unknown error";
+			error = toSafeErrorLabel(err);
 			throw err;
 		} finally {
 			const status = error && c.res.status < 400 ? 500 : c.res.status;
@@ -90,7 +91,11 @@ export function createHonoTrace(options: HonoTraceOptions): MiddlewareHandler {
 				if (entities) event.entities = entities;
 			}
 
-			if (error) event.error = error;
+			if (error) {
+				event.error = status >= 500 ? `HTTP ${status}` : error;
+			} else if (status >= 500) {
+				event.error = `HTTP ${status}`;
+			}
 
 			telemetry.emit(event);
 		}

package/src/adapters/inngest.ts

@@ -18,6 +18,7 @@
 
 import { InngestMiddleware } from "inngest";
 import { extractEntitiesFromEvent } from "../entities.ts";
+import { toSafeErrorLabel } from "../error.ts";
 import { generateSpanId, generateTraceId } from "../ids.ts";
 import type {
 	JobDispatchEvent,
@@ -86,9 +87,7 @@ export function createInngestTrace(options: InngestTraceOptions): InngestMiddlew
 								runId,
 								duration_ms,
 								status: hasError ? "error" : "success",
-								error: hasError
-									? ((result.error as Error)?.message ?? String(result.error))
-									: undefined,
+								error: hasError ? toSafeErrorLabel(result.error) : undefined,
 							};
 							telemetry.emit(endEvent);
 						},

package/src/adapters/prisma.ts

@@ -0,0 +1,112 @@
+/**
+ * Prisma Adapter
+ *
+ * Creates a Prisma client extension that emits db.query telemetry events
+ * for all model operations. Uses $extends({ query }) — no $use() middleware.
+ *
+ * No runtime import of @prisma/client — the extension object is structurally
+ * compatible with PrismaClient.$extends().
+ *
+ * @example
+ * ```ts
+ * import { createTelemetry, type DbEvents } from 'agent-telemetry'
+ * import { createPrismaTrace } from 'agent-telemetry/prisma'
+ *
+ * const telemetry = await createTelemetry<DbEvents>()
+ * const prisma = new PrismaClient().$extends(createPrismaTrace({ telemetry }))
+ * ```
+ */
+
+import { toSafeErrorLabel } from "../error.ts";
+import { generateSpanId, generateTraceId } from "../ids.ts";
+import type { DbQueryEvent, Telemetry } from "../types.ts";
+
+/** Options for the Prisma trace extension. */
+export interface PrismaTraceOptions {
+	/** Telemetry instance to emit events through. */
+	telemetry: Telemetry<DbQueryEvent>;
+	/** Guard function — return false to skip tracing. */
+	isEnabled?: () => boolean;
+	/** Provide parent trace context for correlating with an incoming request. */
+	getTraceContext?: () => { traceId: string } | undefined;
+}
+
+/** Callback params passed by Prisma's $allOperations hook. */
+interface AllOperationsParams {
+	model: string;
+	operation: string;
+	args: unknown;
+	query: (args: unknown) => Promise<unknown>;
+}
+
+/** Shape returned by createPrismaTrace, compatible with PrismaClient.$extends(). */
+export interface PrismaTraceExtension {
+	query: {
+		$allModels: {
+			$allOperations(params: AllOperationsParams): Promise<unknown>;
+		};
+	};
+}
+
+/**
+ * Create a Prisma client extension that traces all model queries.
+ *
+ * Returns a plain object compatible with `PrismaClient.$extends()`.
+ * Emits a db.query event for every model operation with timing,
+ * status, and optional trace context correlation.
+ */
+export function createPrismaTrace(options: PrismaTraceOptions): PrismaTraceExtension {
+	const { telemetry, isEnabled, getTraceContext } = options;
+
+	return {
+		query: {
+			$allModels: {
+				async $allOperations({ model, operation, args, query }) {
+					if (isEnabled && !isEnabled()) {
+						return query(args);
+					}
+
+					const start = performance.now();
+					const traceId = getTraceContext?.()?.traceId ?? generateTraceId();
+					const spanId = generateSpanId();
+
+					try {
+						const result = await query(args);
+						const duration_ms = Math.round(performance.now() - start);
+
+						const event: DbQueryEvent = {
+							kind: "db.query",
+							traceId,
+							spanId,
+							provider: "prisma",
+							model,
+							operation,
+							duration_ms,
+							status: "success",
+						};
+						telemetry.emit(event);
+
+						return result;
+					} catch (err) {
+						const duration_ms = Math.round(performance.now() - start);
+
+						const event: DbQueryEvent = {
+							kind: "db.query",
+							traceId,
+							spanId,
+							provider: "prisma",
+							model,
+							operation,
+							duration_ms,
+							status: "error",
+							error: toSafeErrorLabel(err),
+						};
+						telemetry.emit(event);
+
+						throw err;
+					}
+				},
+			},
+		},
+	};
+}

package/src/adapters/supabase.ts

@@ -0,0 +1,251 @@
+/**
+ * Supabase Adapter
+ *
+ * Creates a traced fetch function for Supabase's createClient({ global: { fetch } }).
+ * Parses Supabase URL patterns to emit rich, service-aware telemetry:
+ * - PostgREST calls -> db.query events with table/operation
+ * - Auth/Storage/Functions calls -> external.call events with service context
+ *
+ * Each fetch invocation emits one event. Supabase's built-in retry logic
+ * will generate separate events per retry — each is a real network call.
+ *
+ * duration_ms measures time-to-headers (TTFB). Response is returned untouched.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from '@supabase/supabase-js'
+ * import { createTelemetry, type SupabaseEvents } from 'agent-telemetry'
+ * import { createSupabaseTrace } from 'agent-telemetry/supabase'
+ *
+ * const telemetry = await createTelemetry<SupabaseEvents>()
+ * const tracedFetch = createSupabaseTrace({ telemetry })
+ * const supabase = createClient(url, key, { global: { fetch: tracedFetch } })
+ * ```
+ */
+
+import { toSafeErrorLabel } from "../error.ts";
+import { generateSpanId, generateTraceId } from "../ids.ts";
+import type { DbQueryEvent, ExternalCallEvent, SupabaseEvents, Telemetry } from "../types.ts";
+
+/** Callable fetch signature (without static properties like `preconnect`). */
+export type FetchFn = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
+/** Options for the Supabase trace adapter. */
+export interface SupabaseTraceOptions {
+	/** Telemetry instance to emit events through. */
+	telemetry: Telemetry<SupabaseEvents>;
+	/** Base fetch implementation. Default: globalThis.fetch. */
+	baseFetch?: FetchFn;
+	/** Provide trace context for correlating with a parent HTTP request. */
+	getTraceContext?: () => { traceId: string; parentSpanId?: string } | undefined;
+	/** Guard function — return false to skip tracing. */
+	isEnabled?: () => boolean;
+}
+
+/** Classification result for a Supabase URL. */
+type Classification =
+	| {
+			kind: "db.query";
+			provider: "supabase";
+			model: string;
+			operation: string;
+	  }
+	| { kind: "external.call"; service: string; operation: string };
+
+/** HTTP method to PostgREST operation mapping. */
+const METHOD_TO_OPERATION: Record<string, string> = {
+	GET: "select",
+	POST: "insert",
+	PATCH: "update",
+	PUT: "upsert",
+	DELETE: "delete",
+};
+
+// URL pattern regexes — use /v\d+/ to handle future API versions (I5).
+const REST_RE = /\/rest\/v\d+\/([^?/]+)/;
+const AUTH_RE = /\/auth\/v\d+\/(.+)/;
+const STORAGE_RE = /\/storage\/v\d+\/object\/([^/]+)/;
+const FUNCTIONS_RE = /\/functions\/v\d+\/([^?/]+)/;
+
+/**
+ * Extract URL metadata from the three fetch input types.
+ * This is metadata-only — the original input is never modified (C3/C4).
+ */
+function resolveInput(input: RequestInfo | URL): {
+	url: string;
+	method: string;
+} {
+	if (input instanceof Request) {
+		return { url: input.url, method: input.method };
+	}
+	if (input instanceof URL) {
+		return { url: input.href, method: "GET" };
+	}
+	// string
+	try {
+		return { url: new URL(input).href, method: "GET" };
+	} catch {
+		return {
+			url: new URL(input, "http://localhost").href,
+			method: "GET",
+		};
+	}
+}
+
+/**
+ * Classify a Supabase request URL into the appropriate event type.
+ * Uses the URL pathname to determine if it's a PostgREST, Auth,
+ * Storage, Functions, or fallback request.
+ */
+function classifyRequest(url: URL, method: string): Classification {
+	const pathname = url.pathname;
+
+	// PostgREST: /rest/v{N}/{table}
+	const restMatch = REST_RE.exec(pathname);
+	if (restMatch) {
+		const table = restMatch[1];
+		const operation = METHOD_TO_OPERATION[method] ?? method.toLowerCase();
+		return {
+			kind: "db.query",
+			provider: "supabase",
+			model: table,
+			operation,
+		};
+	}
+
+	// Auth: /auth/v{N}/{endpoint}
+	const authMatch = AUTH_RE.exec(pathname);
+	if (authMatch) {
+		return {
+			kind: "external.call",
+			service: "supabase-auth",
+			operation: authMatch[1],
+		};
+	}
+
+	// Storage: /storage/v{N}/object/{bucket}/...
+	const storageMatch = STORAGE_RE.exec(pathname);
+	if (storageMatch) {
+		return {
+			kind: "external.call",
+			service: "supabase-storage",
+			operation: `${method} ${storageMatch[1]}`,
+		};
+	}
+
+	// Functions: /functions/v{N}/{name}
+	const functionsMatch = FUNCTIONS_RE.exec(pathname);
+	if (functionsMatch) {
+		return {
+			kind: "external.call",
+			service: "supabase-functions",
+			operation: functionsMatch[1],
+		};
+	}
+
+	// Fallback: unknown path
+	return {
+		kind: "external.call",
+		service: "supabase",
+		operation: `${method} ${pathname}`,
+	};
+}
+
+/**
+ * Create a traced fetch function for Supabase that emits telemetry events.
+ *
+ * The returned function has the same signature as globalThis.fetch.
+ * The original input and init are passed through to baseFetch untouched.
+ * The Response object is returned as-is — streaming bodies work correctly.
+ */
+export function createSupabaseTrace(options: SupabaseTraceOptions): FetchFn {
+	const { telemetry, baseFetch = globalThis.fetch, getTraceContext, isEnabled } = options;
+
+	return async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+		if (isEnabled && !isEnabled()) {
+			return baseFetch(input, init);
+		}
+
+		// Extract metadata only — original input is never modified.
+		const { url, method: resolvedMethod } = resolveInput(input);
+		const method = init?.method?.toUpperCase() ?? resolvedMethod.toUpperCase();
+
+		let parsed: URL;
+		try {
+			parsed = new URL(url);
+		} catch {
+			parsed = new URL(url, "http://localhost");
+		}
+
+		const classification = classifyRequest(parsed, method);
+
+		const ctx = getTraceContext?.();
+		const traceId = ctx?.traceId ?? generateTraceId();
+		const spanId = generateSpanId();
+
+		const start = performance.now();
+
+		try {
+			// Pass ORIGINAL input/init to baseFetch unchanged.
+			const response = await baseFetch(input, init);
+			const duration_ms = Math.round(performance.now() - start);
+
+			if (classification.kind === "db.query") {
+				const event: DbQueryEvent = {
+					kind: "db.query",
+					traceId,
+					spanId,
+					provider: classification.provider,
+					model: classification.model,
+					operation: classification.operation,
+					duration_ms,
+					status: "success",
+				};
+				telemetry.emit(event);
+			} else {
+				const event: ExternalCallEvent = {
+					kind: "external.call",
+					traceId,
+					spanId,
+					service: classification.service,
+					operation: classification.operation,
+					duration_ms,
+					status: "success",
+				};
+				telemetry.emit(event);
+			}
+
+			return response;
+		} catch (err) {
+			const duration_ms = Math.round(performance.now() - start);
+
+			if (classification.kind === "db.query") {
+				const event: DbQueryEvent = {
+					kind: "db.query",
+					traceId,
+					spanId,
+					provider: classification.provider,
+					model: classification.model,
+					operation: classification.operation,
+					duration_ms,
+					status: "error",
+					error: toSafeErrorLabel(err),
+				};
+				telemetry.emit(event);
+			} else {
+				const event: ExternalCallEvent = {
+					kind: "external.call",
+					traceId,
+					spanId,
+					service: classification.service,
+					operation: classification.operation,
+					duration_ms,
+					status: "error",
+				};
+				telemetry.emit(event);
+			}
+
+			throw err;
+		}
+	};
+}

package/src/error.ts

@@ -0,0 +1,16 @@
+/**
+ * Error helpers.
+ *
+ * Keeps telemetry error fields low-sensitivity by using stable labels
+ * (error names) instead of raw exception messages.
+ */
+
+const DEFAULT_ERROR_LABEL = "Error";
+const MAX_ERROR_LABEL_LENGTH = 80;
+
+export function toSafeErrorLabel(err: unknown): string {
+	if (!(err instanceof Error)) return DEFAULT_ERROR_LABEL;
+	const name = err.name.trim();
+	if (!name) return DEFAULT_ERROR_LABEL;
+	return name.slice(0, MAX_ERROR_LABEL_LENGTH);
+}

package/src/index.ts

@@ -51,6 +51,8 @@ export async function createTelemetry<TEvent extends BaseTelemetryEvent = BaseTe
 // Re-export all public types
 export type {
 	BaseTelemetryEvent,
+	DbEvents,
+	DbQueryEvent,
 	EntityPattern,
 	ExternalCallEvent,
 	ExternalEvents,
@@ -62,6 +64,7 @@ export type {
 	JobStartEvent,
 	JobStepEvent,
 	PresetEvents,
+	SupabaseEvents,
 	Telemetry,
 	TelemetryConfig,
 	TraceContext,

package/src/traceparent.ts

@@ -10,15 +10,15 @@
 
 /** Parsed representation of a `traceparent` header. */
 export interface Traceparent {
-	version: string
-	traceId: string
-	parentId: string
-	traceFlags: string
+	version: string;
+	traceId: string;
+	parentId: string;
+	traceFlags: string;
 }
 
-const TRACEPARENT_RE = /^([\da-f]{2})-([\da-f]{32})-([\da-f]{16})-([\da-f]{2})$/
-const ALL_ZEROS_32 = '0'.repeat(32)
-const ALL_ZEROS_16 = '0'.repeat(16)
+const TRACEPARENT_RE = /^([\da-f]{2})-([\da-f]{32})-([\da-f]{16})-([\da-f]{2})$/;
+const ALL_ZEROS_32 = "0".repeat(32);
+const ALL_ZEROS_16 = "0".repeat(16);
 
 /**
  * Parse a `traceparent` header value.
@@ -27,21 +27,22 @@ const ALL_ZEROS_16 = '0'.repeat(16)
  * malformed, or violates the W3C spec (e.g. all-zero trace-id/parent-id).
  */
 export function parseTraceparent(header: string | undefined | null): Traceparent | null {
-	if (!header) return null
+	if (!header) return null;
 
-	const match = TRACEPARENT_RE.exec(header.trim().toLowerCase())
-	if (!match) return null
+	const match = TRACEPARENT_RE.exec(header.trim().toLowerCase());
+	if (!match) return null;
 
 	// Captures are guaranteed by the regex match above
-	const version = match[1] as string
-	const traceId = match[2] as string
-	const parentId = match[3] as string
-	const traceFlags = match[4] as string
+	const version = match[1] as string;
+	const traceId = match[2] as string;
+	const parentId = match[3] as string;
+	const traceFlags = match[4] as string;
 
-	// W3C spec: all-zero trace-id and parent-id are invalid
-	if (traceId === ALL_ZEROS_32 || parentId === ALL_ZEROS_16) return null
+	// W3C spec: "ff" is invalid as the version, and all-zero IDs are invalid.
+	if (version === "ff") return null;
+	if (traceId === ALL_ZEROS_32 || parentId === ALL_ZEROS_16) return null;
 
-	return { version, traceId, parentId, traceFlags }
+	return { version, traceId, parentId, traceFlags };
 }
 
 /**
@@ -51,6 +52,6 @@ export function parseTraceparent(header: string | undefined | null): Traceparent
  * @param parentId 16-char lowercase hex parent/span ID
  * @param flags    2-char hex trace flags (default: "01" = sampled)
  */
-export function formatTraceparent(traceId: string, parentId: string, flags = '01'): string {
-	return `00-${traceId}-${parentId}-${flags}`
+export function formatTraceparent(traceId: string, parentId: string, flags = "01"): string {
+	return `00-${traceId}-${parentId}-${flags}`;
 }

package/src/types.ts

@@ -81,8 +81,28 @@ export interface ExternalCallEvent extends BaseTelemetryEvent {
 /** All external service call events. */
 export type ExternalEvents = ExternalCallEvent;
 
+export interface DbQueryEvent extends BaseTelemetryEvent {
+	kind: "db.query";
+	spanId: string;
+	/** Provider identifier (e.g. "prisma", "supabase", "drizzle"). */
+	provider: string;
+	/** The data entity being operated on — ORM model name or database table. */
+	model?: string;
+	/** Operation name (e.g. "findMany", "create", "select", "insert"). */
+	operation: string;
+	duration_ms: number;
+	status: "success" | "error";
+	error?: string;
+}
+
+/** All database query events. */
+export type DbEvents = DbQueryEvent;
+
+/** Events emitted by the Supabase adapter (db.query for PostgREST, external.call for auth/storage/functions). */
+export type SupabaseEvents = DbQueryEvent | ExternalCallEvent;
+
 /** Union of all preset event types. */
-export type PresetEvents = HttpEvents | JobEvents | ExternalEvents;
+export type PresetEvents = HttpEvents | JobEvents | ExternalEvents | DbEvents;
 
 // ============================================================================
 // Entity Extraction