agent-telemetry 0.1.0 → 0.3.0

package/src/adapters/fetch.ts

@@ -0,0 +1,135 @@
+/**
+ * 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 {
+	type FetchFn,
+	defaultPropagateTo,
+	injectTraceparent,
+	resolveInput,
+	resolveUrl,
+} from "../fetch-utils.ts";
+import { startSpan } from "../trace-context.ts";
+import { formatTraceparent } from "../traceparent.ts";
+import type { ExternalCallEvent, Telemetry, TraceContext } from "../types.ts";
+
+export type { FetchFn } from "../fetch-utils.ts";
+
+/** 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?: () => TraceContext | undefined;
+	/** Predicate controlling where to forward `traceparent` headers. */
+	propagateTo?: (url: URL) => boolean;
+	/** Optional callback invoked when responses include `traceparent`. */
+	onResponseTraceparent?: (traceparent: string) => void;
+	/** Guard function — return false to skip tracing. */
+	isEnabled?: () => boolean;
+}
+
+/**
+ * Create a traced fetch function that emits external.call telemetry events.
+ *
+ * The returned function has the same signature as globalThis.fetch.
+ * Request inputs are only cloned when header propagation is enabled.
+ * 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,
+		propagateTo,
+		onResponseTraceparent,
+		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.toUpperCase();
+		const parsedUrl = resolveUrl(url);
+
+		const service = parsedUrl.hostname;
+		const pathname = parsedUrl.pathname;
+
+		const operation = `${method} ${pathname}`;
+
+		const ctx = getTraceContext?.();
+		const span = startSpan({
+			traceId: ctx?.traceId,
+			parentSpanId: ctx?.parentSpanId,
+			traceFlags: ctx?.traceFlags,
+		});
+		const traceparent = formatTraceparent(span.traceId, span.spanId, span.traceFlags);
+
+		const shouldPropagate = (propagateTo ?? defaultPropagateTo)(parsedUrl);
+		const outbound = shouldPropagate
+			? injectTraceparent(input, init, traceparent)
+			: { input, init };
+
+		const start = performance.now();
+
+		try {
+			const response = await baseFetch(outbound.input, outbound.init);
+			const duration_ms = Math.round(performance.now() - start);
+			const responseTraceparent = response.headers.get("traceparent");
+			if (responseTraceparent) {
+				onResponseTraceparent?.(responseTraceparent);
+			}
+
+			telemetry.emit({
+				kind: "external.call",
+				traceId: span.traceId,
+				spanId: span.spanId,
+				parentSpanId: span.parentSpanId,
+				service,
+				operation,
+				duration_ms,
+				status: "success",
+			});
+
+			return response;
+		} catch (err) {
+			const duration_ms = Math.round(performance.now() - start);
+
+			telemetry.emit({
+				kind: "external.call",
+				traceId: span.traceId,
+				spanId: span.spanId,
+				parentSpanId: span.parentSpanId,
+				service,
+				operation,
+				duration_ms,
+				status: "error",
+			});
+
+			throw err;
+		}
+	};
+}

package/src/adapters/hono.ts

@@ -21,8 +21,10 @@
 
 import type { Context, MiddlewareHandler } from "hono";
 import { extractEntities } from "../entities.ts";
-import { generateSpanId, generateTraceId } from "../ids.ts";
-import { formatTraceparent, parseTraceparent } from "../traceparent.ts";
+import { toSafeErrorLabel } from "../error.ts";
+import { generateSpanId } from "../ids.ts";
+import { startSpanFromTraceparent } from "../trace-context.ts";
+import { formatTraceparent } from "../traceparent.ts";
 import type { EntityPattern, HttpRequestEvent, Telemetry } from "../types.ts";
 
 /** Options for Hono trace middleware. */
@@ -38,6 +40,7 @@ export interface HonoTraceOptions {
 /** Hono variable keys for trace storage. */
 const TRACE_ID_VAR = "traceId" as const;
 const SPAN_ID_VAR = "spanId" as const;
+const TRACE_FLAGS_VAR = "traceFlags" as const;
 
 /**
  * Create Hono middleware that traces HTTP requests.
@@ -54,12 +57,11 @@ export function createHonoTrace(options: HonoTraceOptions): MiddlewareHandler {
 			return next();
 		}
 
-		const parsed = parseTraceparent(c.req.header("traceparent"));
-		const traceId = parsed?.traceId ?? generateTraceId();
-		const spanId = generateSpanId();
+		const span = startSpanFromTraceparent(c.req.header("traceparent"));
 
-		c.set(TRACE_ID_VAR, traceId);
-		c.set(SPAN_ID_VAR, spanId);
+		c.set(TRACE_ID_VAR, span.traceId);
+		c.set(SPAN_ID_VAR, span.spanId);
+		c.set(TRACE_FLAGS_VAR, span.traceFlags);
 
 		const start = performance.now();
 		let error: string | undefined;
@@ -67,18 +69,20 @@ 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;
 			const duration_ms = Math.round(performance.now() - start);
 			const path = c.req.path;
 
-			c.header("traceparent", formatTraceparent(traceId, spanId));
+			c.header("traceparent", formatTraceparent(span.traceId, span.spanId, span.traceFlags));
 
 			const event: HttpRequestEvent = {
 				kind: "http.request",
-				traceId,
+				traceId: span.traceId,
+				spanId: span.spanId,
+				parentSpanId: span.parentSpanId,
 				method: c.req.method,
 				path,
 				status,
@@ -90,7 +94,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);
 		}
@@ -112,9 +120,12 @@ export function createHonoTrace(options: HonoTraceOptions): MiddlewareHandler {
  */
 export function getTraceContext(
 	c: Context,
-): { _trace: { traceId: string; parentSpanId: string } } | Record<string, never> {
+):
+	| { _trace: { traceId: string; parentSpanId: string; traceFlags?: string } }
+	| Record<string, never> {
 	const traceId = c.get(TRACE_ID_VAR) as string | undefined;
 	const spanId = c.get(SPAN_ID_VAR) as string | undefined;
+	const traceFlags = c.get(TRACE_FLAGS_VAR) as string | undefined;
 	if (!traceId) return {};
-	return { _trace: { traceId, parentSpanId: spanId ?? generateSpanId() } };
+	return { _trace: { traceId, parentSpanId: spanId ?? generateSpanId(), traceFlags } };
 }

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,118 @@
+/**
+ * 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 { startSpan } from "../trace-context.ts";
+import type { DbQueryEvent, Telemetry, TraceContext } 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?: () => TraceContext | 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 ctx = getTraceContext?.();
+					const span = startSpan({
+						traceId: ctx?.traceId,
+						parentSpanId: ctx?.parentSpanId,
+						traceFlags: ctx?.traceFlags,
+					});
+
+					try {
+						const result = await query(args);
+						const duration_ms = Math.round(performance.now() - start);
+
+						const event: DbQueryEvent = {
+							kind: "db.query",
+							traceId: span.traceId,
+							spanId: span.spanId,
+							parentSpanId: span.parentSpanId,
+							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: span.traceId,
+							spanId: span.spanId,
+							parentSpanId: span.parentSpanId,
+							provider: "prisma",
+							model,
+							operation,
+							duration_ms,
+							status: "error",
+							error: toSafeErrorLabel(err),
+						};
+						telemetry.emit(event);
+
+						throw err;
+					}
+				},
+			},
+		},
+	};
+}

package/src/adapters/supabase.ts

@@ -0,0 +1,239 @@
+/**
+ * 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 { type FetchFn, resolveInput } from "../fetch-utils.ts";
+import { startSpan } from "../trace-context.ts";
+import type {
+	DbQueryEvent,
+	ExternalCallEvent,
+	SupabaseEvents,
+	Telemetry,
+	TraceContext,
+} from "../types.ts";
+
+export type { FetchFn } from "../fetch-utils.ts";
+
+/** 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?: () => TraceContext | 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+\/([^?/]+)/;
+
+/**
+ * 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 span = startSpan({
+			traceId: ctx?.traceId,
+			parentSpanId: ctx?.parentSpanId,
+			traceFlags: ctx?.traceFlags,
+		});
+
+		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: span.traceId,
+					spanId: span.spanId,
+					parentSpanId: span.parentSpanId,
+					provider: classification.provider,
+					model: classification.model,
+					operation: classification.operation,
+					duration_ms,
+					status: "success",
+				};
+				telemetry.emit(event);
+			} else {
+				const event: ExternalCallEvent = {
+					kind: "external.call",
+					traceId: span.traceId,
+					spanId: span.spanId,
+					parentSpanId: span.parentSpanId,
+					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: span.traceId,
+					spanId: span.spanId,
+					parentSpanId: span.parentSpanId,
+					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: span.traceId,
+					spanId: span.spanId,
+					parentSpanId: span.parentSpanId,
+					service: classification.service,
+					operation: classification.operation,
+					duration_ms,
+					status: "error",
+				};
+				telemetry.emit(event);
+			}
+
+			throw err;
+		}
+	};
+}