agent-telemetry 0.2.0 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 Lightweight JSONL telemetry for easier AI agent consumption. Zero runtime dependencies.
 
-Writes structured telemetry events to rotating JSONL files in development. Falls back to `console.log` in runtimes without filesystem access (Cloudflare Workers). Includes framework adapters for Hono, Inngest, Express, Fastify, Prisma, Supabase, and a generic traced fetch wrapper.
+Writes structured telemetry events to rotating JSONL files in development. Falls back to `console.log` in runtimes without filesystem access (Cloudflare Workers). Includes framework adapters for Hono, Inngest, Express, Fastify, Prisma, Supabase, a generic traced fetch wrapper, and browser trace-context helpers.
 
 ## Install
 
@@ -47,7 +47,7 @@ Inbound HTTP  →  Database Queries  →  External API Calls  →  Background Jo
   Fastify                                storage/functions)
 ```
 
-One `traceId` follows a request from the HTTP boundary through database queries, external API calls, and into background job execution. HTTP adapters use the [W3C `traceparent`](https://www.w3.org/TR/trace-context/) header for propagation, enabling interop with OpenTelemetry and other standards-compliant tools. Query your JSONL logs by `traceId` to see the full chain.
+One `traceId` follows a request from the HTTP boundary through database queries, external API calls, and into background job execution. `spanId`/`parentSpanId` fields preserve parent-child relationships inside that trace. HTTP adapters use the [W3C `traceparent`](https://www.w3.org/TR/trace-context/) header for propagation, enabling interop with OpenTelemetry and other standards-compliant tools. Query your JSONL logs by `traceId` to see the full chain.
 
 ## Full-Stack Example
 
@@ -152,10 +152,10 @@ app.use('*', trace)
 The middleware:
 - Parses the incoming W3C `traceparent` header, or generates a fresh trace ID if absent/invalid
 - Sets `traceparent` on the response for client-side correlation (format: `00-{traceId}-{spanId}-01`)
-- Emits `http.request` events with method, path, status, duration, and extracted entities
+- Emits `http.request` events with method, path, status, duration, extracted entities, and span linkage (`spanId`, `parentSpanId`)
 - Extracts entity IDs from URL paths — looks for a matching `segment`, then checks if the next segment is a UUID
 
-`getTraceContext(c)` returns `{ _trace: { traceId, parentSpanId } }` for spreading into dispatch payloads. Returns `{}` if no trace middleware is active.
+`getTraceContext(c)` returns `{ _trace: { traceId, parentSpanId, traceFlags } }` for spreading into dispatch payloads. Returns `{}` if no trace middleware is active.
 
 ## Inngest Adapter
 
@@ -188,17 +188,47 @@ const fetch = createTracedFetch({
   telemetry,
   baseFetch: globalThis.fetch,       // Optional — default: globalThis.fetch
   getTraceContext: () => ctx,         // Optional — correlate with parent request
+  propagateTo: (url) => url.origin === 'https://api.my-app.com', // Optional header allowlist
+  onResponseTraceparent: (tp) => {    // Optional response callback
+    console.log(tp)
+  },
   isEnabled: () => true,             // Optional guard
 })
 
 const res = await fetch('https://api.stripe.com/v1/charges', { method: 'POST' })
 ```
 
-- Emits `external.call` events with `service` (hostname) and `operation` (`METHOD /pathname`)
+- Emits `external.call` events with `service` (hostname), `operation` (`METHOD /pathname`), and span linkage (`spanId`, optional `parentSpanId`)
 - `duration_ms` measures time-to-headers (TTFB) — the Response body is returned untouched for streaming
 - Handles all three fetch input types: `string`, `URL`, `Request`
+- Can inject outbound `traceparent` headers using `propagateTo` (default: same-origin only in browser, disabled elsewhere)
 - Non-2xx responses return normally (not thrown); network errors re-throw after emitting
 
+## Browser Trace Context
+
+Use the browser helpers to continue the same trace from UI requests into server adapters.
+
+```typescript
+import { createBrowserTraceContext, createBrowserTracedFetch } from 'agent-telemetry/browser'
+
+const trace = createBrowserTraceContext({
+  // Optional SSR bootstrap: <meta name="traceparent" content="00-...">
+  initialTraceparent: document.querySelector('meta[name="traceparent"]')?.getAttribute('content'),
+})
+
+const fetch = createBrowserTracedFetch({
+  trace,
+  // Default is same-origin only. Keep this allowlist strict.
+  propagateTo: (url) => url.origin === window.location.origin,
+})
+
+await fetch('/api/users')
+```
+
+- `createBrowserTraceContext()` bootstraps from `initialTraceparent`, then `<meta name="traceparent">`, then fresh IDs
+- `createBrowserTracedFetch()` injects W3C `traceparent` on allowed requests and can adopt response `traceparent`
+- `trace.withSpan(name, fn)` creates a child span for user actions and restores the previous parent span after completion
+
 ## Prisma Adapter
 
 Traces all Prisma model operations via `$extends()`. No runtime `@prisma/client` import — the extension is structurally compatible.
@@ -213,7 +243,7 @@ const prisma = new PrismaClient().$extends(createPrismaTrace({
 }))
 ```
 
-- Emits `db.query` events with `provider: "prisma"`, `model` (e.g. `"User"`), and `operation` (e.g. `"findMany"`)
+- Emits `db.query` events with `provider: "prisma"`, `model` (e.g. `"User"`), `operation` (e.g. `"findMany"`), and span linkage (`spanId`, optional `parentSpanId`)
 - Requires Prisma 5.0.0+ (stable `$extends` API)
 - No access to raw SQL at the query extension level — model and operation names only
 
@@ -239,7 +269,7 @@ app.post('/api/users/:id', (req, res) => {
 })
 ```
 
-- Emits `http.request` events with method, path (query string stripped), status, duration, entities
+- Emits `http.request` events with method, path (query string stripped), status, duration, entities, and span linkage
 - Parses/sets W3C `traceparent` header for propagation
 - Uses `req.route.path` for parameterized patterns (e.g. `/users/:id`), falls back to `req.originalUrl`
 - Handles both `res.on("finish")` and `res.on("close")` to capture aborted requests
@@ -260,7 +290,7 @@ app.register(createFastifyTrace({
 }))
 ```
 
-- Emits `http.request` events using `reply.elapsedTime` for high-resolution duration
+- Emits `http.request` events using `reply.elapsedTime` for high-resolution duration, including span linkage
 - Strips query strings from emitted `path` values
 - Parses/sets W3C `traceparent` header for propagation
 - Uses `request.routeOptions.url` for parameterized route patterns

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "agent-telemetry",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "Lightweight JSONL telemetry for AI agent backends. Zero deps, framework adapters included.",
 	"type": "module",
 	"exports": {
@@ -35,6 +35,10 @@
 		"./supabase": {
 			"import": "./src/adapters/supabase.ts",
 			"types": "./src/adapters/supabase.ts"
+		},
+		"./browser": {
+			"import": "./src/browser.ts",
+			"types": "./src/browser.ts"
 		}
 	},
 	"files": ["src"],

package/src/adapters/express.ts

@@ -17,8 +17,8 @@
  */
 
 import { extractEntities } from "../entities.ts";
-import { generateSpanId, generateTraceId } from "../ids.ts";
-import { formatTraceparent, parseTraceparent } from "../traceparent.ts";
+import { startSpanFromTraceparent } from "../trace-context.ts";
+import { formatTraceparent } from "../traceparent.ts";
 import type { EntityPattern, HttpRequestEvent, Telemetry } from "../types.ts";
 
 // ============================================================================
@@ -52,7 +52,7 @@ export type ExpressMiddleware = (
 // Request-Scoped Trace Storage
 // ============================================================================
 
-const traceStore = new WeakMap<object, { traceId: string; spanId: string }>();
+const traceStore = new WeakMap<object, { traceId: string; spanId: string; traceFlags: string }>();
 
 function stripQueryAndFragment(url: string): string {
 	const queryIdx = url.indexOf("?");
@@ -104,12 +104,14 @@ export function createExpressTrace(options: ExpressTraceOptions): ExpressMiddlew
 		const incoming = Array.isArray(req.headers.traceparent)
 			? req.headers.traceparent[0]
 			: req.headers.traceparent;
-		const parsed = parseTraceparent(incoming);
-		const traceId = parsed?.traceId ?? generateTraceId();
-		const spanId = generateSpanId();
+		const span = startSpanFromTraceparent(incoming);
 
-		traceStore.set(req, { traceId, spanId });
-		res.setHeader("traceparent", formatTraceparent(traceId, spanId));
+		traceStore.set(req, {
+			traceId: span.traceId,
+			spanId: span.spanId,
+			traceFlags: span.traceFlags,
+		});
+		res.setHeader("traceparent", formatTraceparent(span.traceId, span.spanId, span.traceFlags));
 
 		const start = performance.now();
 		let emitted = false;
@@ -124,7 +126,9 @@ export function createExpressTrace(options: ExpressTraceOptions): ExpressMiddlew
 
 			const event: HttpRequestEvent = {
 				kind: "http.request",
-				traceId,
+				traceId: span.traceId,
+				spanId: span.spanId,
+				parentSpanId: span.parentSpanId,
 				method: req.method,
 				path,
 				status: res.statusCode,
@@ -169,8 +173,16 @@ export function createExpressTrace(options: ExpressTraceOptions): ExpressMiddlew
  */
 export function getTraceContext(
 	req: object,
-): { _trace: { traceId: string; parentSpanId: string } } | Record<string, never> {
+):
+	| { _trace: { traceId: string; parentSpanId: string; traceFlags?: string } }
+	| Record<string, never> {
 	const stored = traceStore.get(req);
 	if (!stored) return {};
-	return { _trace: { traceId: stored.traceId, parentSpanId: stored.spanId } };
+	return {
+		_trace: {
+			traceId: stored.traceId,
+			parentSpanId: stored.spanId,
+			traceFlags: stored.traceFlags,
+		},
+	};
 }

package/src/adapters/fastify.ts

@@ -18,8 +18,8 @@
  */
 
 import { extractEntities } from "../entities.ts";
-import { generateSpanId, generateTraceId } from "../ids.ts";
-import { formatTraceparent, parseTraceparent } from "../traceparent.ts";
+import { startSpanFromTraceparent } from "../trace-context.ts";
+import { formatTraceparent } from "../traceparent.ts";
 import type { EntityPattern, HttpRequestEvent, Telemetry } from "../types.ts";
 
 // ---------------------------------------------------------------------------
@@ -62,7 +62,10 @@ type FastifyPluginCallback = ((
 // Trace storage (keyed on Fastify request wrapper, not request.raw)
 // ---------------------------------------------------------------------------
 
-const traceStore = new WeakMap<object, { traceId: string; spanId: string }>();
+const traceStore = new WeakMap<
+	object,
+	{ traceId: string; spanId: string; parentSpanId?: string; traceFlags: string }
+>();
 
 function stripQueryAndFragment(url: string): string {
 	const queryIdx = url.indexOf("?");
@@ -113,12 +116,15 @@ export function createFastifyTrace(options: FastifyTraceOptions): FastifyPluginC
 			const incoming = Array.isArray(request.headers.traceparent)
 				? request.headers.traceparent[0]
 				: request.headers.traceparent;
-			const parsed = parseTraceparent(incoming);
-			const traceId = parsed?.traceId ?? generateTraceId();
-			const spanId = generateSpanId();
-
-			traceStore.set(request, { traceId, spanId });
-			reply.header("traceparent", formatTraceparent(traceId, spanId));
+			const span = startSpanFromTraceparent(incoming);
+
+			traceStore.set(request, {
+				traceId: span.traceId,
+				spanId: span.spanId,
+				parentSpanId: span.parentSpanId,
+				traceFlags: span.traceFlags,
+			});
+			reply.header("traceparent", formatTraceparent(span.traceId, span.spanId, span.traceFlags));
 			hookDone();
 		});
 
@@ -136,6 +142,8 @@ export function createFastifyTrace(options: FastifyTraceOptions): FastifyPluginC
 			const event: HttpRequestEvent = {
 				kind: "http.request",
 				traceId: trace.traceId,
+				spanId: trace.spanId,
+				parentSpanId: trace.parentSpanId,
 				method: request.method,
 				path,
 				status: reply.statusCode,
@@ -183,9 +191,17 @@ export function createFastifyTrace(options: FastifyTraceOptions): FastifyPluginC
  */
 export function getTraceContext(
 	request: unknown,
-): { _trace: { traceId: string; parentSpanId: string } } | Record<string, never> {
+):
+	| { _trace: { traceId: string; parentSpanId: string; traceFlags?: string } }
+	| Record<string, never> {
 	if (!request || typeof request !== "object") return {};
 	const trace = traceStore.get(request);
 	if (!trace) return {};
-	return { _trace: { traceId: trace.traceId, parentSpanId: trace.spanId } };
+	return {
+		_trace: {
+			traceId: trace.traceId,
+			parentSpanId: trace.spanId,
+			traceFlags: trace.traceFlags,
+		},
+	};
 }

package/src/adapters/fetch.ts

@@ -19,11 +19,18 @@
  * ```
  */
 
-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>;
+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 {
@@ -32,46 +39,32 @@ export interface TracedFetchOptions {
 	/** Base fetch implementation. Default: globalThis.fetch. */
 	baseFetch?: FetchFn;
 	/** Provide trace context for correlating with a parent HTTP request. */
-	getTraceContext?: () => { traceId: string; parentSpanId?: string } | undefined;
+	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;
 }
 
-/**
- * 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.
+ * 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, isEnabled } = options;
+	const {
+		telemetry,
+		baseFetch = globalThis.fetch,
+		getTraceContext,
+		propagateTo,
+		onResponseTraceparent,
+		isEnabled,
+	} = options;
 
 	return async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
 		if (isEnabled && !isEnabled()) {
@@ -79,34 +72,42 @@ export function createTracedFetch(options: TracedFetchOptions): FetchFn {
 		}
 
 		const { url, method: resolvedMethod } = resolveInput(input);
-		const method = init?.method?.toUpperCase() ?? resolvedMethod;
+		const method = init?.method?.toUpperCase() ?? resolvedMethod.toUpperCase();
+		const parsedUrl = resolveUrl(url);
 
-		let service = "unknown";
-		let pathname = "/";
-		try {
-			const parsed = new URL(url);
-			service = parsed.hostname;
-			pathname = parsed.pathname;
-		} catch {
-			// keep defaults
-		}
+		const service = parsedUrl.hostname;
+		const pathname = parsedUrl.pathname;
 
 		const operation = `${method} ${pathname}`;
 
 		const ctx = getTraceContext?.();
-		const traceId = ctx?.traceId ?? generateTraceId();
-		const spanId = generateSpanId();
+		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(input, init);
+			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,
-				spanId,
+				traceId: span.traceId,
+				spanId: span.spanId,
+				parentSpanId: span.parentSpanId,
 				service,
 				operation,
 				duration_ms,
@@ -119,8 +120,9 @@ export function createTracedFetch(options: TracedFetchOptions): FetchFn {
 
 			telemetry.emit({
 				kind: "external.call",
-				traceId,
-				spanId,
+				traceId: span.traceId,
+				spanId: span.spanId,
+				parentSpanId: span.parentSpanId,
 				service,
 				operation,
 				duration_ms,

package/src/adapters/hono.ts

@@ -22,8 +22,9 @@
 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 { 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. */
@@ -39,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.
@@ -55,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;
@@ -75,11 +76,13 @@ export function createHonoTrace(options: HonoTraceOptions): MiddlewareHandler {
 			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,
@@ -117,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/prisma.ts

@@ -18,8 +18,8 @@
  */
 
 import { toSafeErrorLabel } from "../error.ts";
-import { generateSpanId, generateTraceId } from "../ids.ts";
-import type { DbQueryEvent, Telemetry } from "../types.ts";
+import { startSpan } from "../trace-context.ts";
+import type { DbQueryEvent, Telemetry, TraceContext } from "../types.ts";
 
 /** Options for the Prisma trace extension. */
 export interface PrismaTraceOptions {
@@ -28,7 +28,7 @@ export interface PrismaTraceOptions {
 	/** Guard function — return false to skip tracing. */
 	isEnabled?: () => boolean;
 	/** Provide parent trace context for correlating with an incoming request. */
-	getTraceContext?: () => { traceId: string } | undefined;
+	getTraceContext?: () => TraceContext | undefined;
 }
 
 /** Callback params passed by Prisma's $allOperations hook. */
@@ -67,8 +67,12 @@ export function createPrismaTrace(options: PrismaTraceOptions): PrismaTraceExten
 					}
 
 					const start = performance.now();
-					const traceId = getTraceContext?.()?.traceId ?? generateTraceId();
-					const spanId = generateSpanId();
+					const ctx = getTraceContext?.();
+					const span = startSpan({
+						traceId: ctx?.traceId,
+						parentSpanId: ctx?.parentSpanId,
+						traceFlags: ctx?.traceFlags,
+					});
 
 					try {
 						const result = await query(args);
@@ -76,8 +80,9 @@ export function createPrismaTrace(options: PrismaTraceOptions): PrismaTraceExten
 
 						const event: DbQueryEvent = {
 							kind: "db.query",
-							traceId,
-							spanId,
+							traceId: span.traceId,
+							spanId: span.spanId,
+							parentSpanId: span.parentSpanId,
 							provider: "prisma",
 							model,
 							operation,
@@ -92,8 +97,9 @@ export function createPrismaTrace(options: PrismaTraceOptions): PrismaTraceExten
 
 						const event: DbQueryEvent = {
 							kind: "db.query",
-							traceId,
-							spanId,
+							traceId: span.traceId,
+							spanId: span.spanId,
+							parentSpanId: span.parentSpanId,
 							provider: "prisma",
 							model,
 							operation,

package/src/adapters/supabase.ts

@@ -24,11 +24,17 @@
  */
 
 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>;
+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 {
@@ -37,7 +43,7 @@ export interface SupabaseTraceOptions {
 	/** Base fetch implementation. Default: globalThis.fetch. */
 	baseFetch?: FetchFn;
 	/** Provide trace context for correlating with a parent HTTP request. */
-	getTraceContext?: () => { traceId: string; parentSpanId?: string } | undefined;
+	getTraceContext?: () => TraceContext | undefined;
 	/** Guard function — return false to skip tracing. */
 	isEnabled?: () => boolean;
 }
@@ -67,31 +73,6 @@ 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,
@@ -180,8 +161,11 @@ export function createSupabaseTrace(options: SupabaseTraceOptions): FetchFn {
 		const classification = classifyRequest(parsed, method);
 
 		const ctx = getTraceContext?.();
-		const traceId = ctx?.traceId ?? generateTraceId();
-		const spanId = generateSpanId();
+		const span = startSpan({
+			traceId: ctx?.traceId,
+			parentSpanId: ctx?.parentSpanId,
+			traceFlags: ctx?.traceFlags,
+		});
 
 		const start = performance.now();
 
@@ -193,8 +177,9 @@ export function createSupabaseTrace(options: SupabaseTraceOptions): FetchFn {
 			if (classification.kind === "db.query") {
 				const event: DbQueryEvent = {
 					kind: "db.query",
-					traceId,
-					spanId,
+					traceId: span.traceId,
+					spanId: span.spanId,
+					parentSpanId: span.parentSpanId,
 					provider: classification.provider,
 					model: classification.model,
 					operation: classification.operation,
@@ -205,8 +190,9 @@ export function createSupabaseTrace(options: SupabaseTraceOptions): FetchFn {
 			} else {
 				const event: ExternalCallEvent = {
 					kind: "external.call",
-					traceId,
-					spanId,
+					traceId: span.traceId,
+					spanId: span.spanId,
+					parentSpanId: span.parentSpanId,
 					service: classification.service,
 					operation: classification.operation,
 					duration_ms,
@@ -222,8 +208,9 @@ export function createSupabaseTrace(options: SupabaseTraceOptions): FetchFn {
 			if (classification.kind === "db.query") {
 				const event: DbQueryEvent = {
 					kind: "db.query",
-					traceId,
-					spanId,
+					traceId: span.traceId,
+					spanId: span.spanId,
+					parentSpanId: span.parentSpanId,
 					provider: classification.provider,
 					model: classification.model,
 					operation: classification.operation,
@@ -235,8 +222,9 @@ export function createSupabaseTrace(options: SupabaseTraceOptions): FetchFn {
 			} else {
 				const event: ExternalCallEvent = {
 					kind: "external.call",
-					traceId,
-					spanId,
+					traceId: span.traceId,
+					spanId: span.spanId,
+					parentSpanId: span.parentSpanId,
 					service: classification.service,
 					operation: classification.operation,
 					duration_ms,

package/src/browser.ts

@@ -0,0 +1,184 @@
+import {
+	type FetchFn,
+	defaultPropagateTo,
+	injectTraceparent,
+	resolveInput,
+	resolveUrl,
+} from "./fetch-utils.ts";
+import { generateSpanId, generateTraceId } from "./ids.ts";
+import { normalizeTraceFlags, startSpan } from "./trace-context.ts";
+import { formatTraceparent, parseTraceparent } from "./traceparent.ts";
+import type { TraceContext } from "./types.ts";
+
+export type { FetchFn } from "./fetch-utils.ts";
+
+interface BrowserTraceState {
+	traceId: string;
+	parentSpanId: string;
+	traceFlags: string;
+}
+
+function readMetaTraceparent(metaName: string): string | undefined {
+	if (typeof document === "undefined") return undefined;
+	const value = document.querySelector(`meta[name="${metaName}"]`)?.getAttribute("content");
+	return value ?? undefined;
+}
+
+function toTraceContext(state: BrowserTraceState): TraceContext {
+	return {
+		traceId: state.traceId,
+		parentSpanId: state.parentSpanId,
+		traceFlags: state.traceFlags,
+	};
+}
+
+/** Browser trace context manager for request propagation. */
+export interface BrowserTraceContext {
+	/** Get the current trace context for child operations. */
+	getTraceContext(): TraceContext;
+	/** Get a serialized `traceparent` for the current context. */
+	getTraceparent(): string;
+	/** Replace the current trace context. */
+	setTraceContext(context: TraceContext): void;
+	/** Parse and adopt an incoming `traceparent` header value. */
+	updateFromTraceparent(traceparent: string | null | undefined): boolean;
+	/**
+	 * Run work under a child span.
+	 * The callback receives a context whose `parentSpanId` is the created span ID.
+	 */
+	withSpan<T>(
+		name: string,
+		run: (context: TraceContext & { spanId: string; name: string }) => Promise<T> | T,
+	): Promise<T>;
+}
+
+export interface BrowserTraceContextOptions {
+	/** Optional bootstrap header value (e.g. from SSR). */
+	initialTraceparent?: string | null;
+	/** Meta tag name used for bootstrap lookup. Default: "traceparent". */
+	metaName?: string;
+}
+
+/**
+ * Create browser trace context.
+ *
+ * Bootstrap order:
+ * 1) options.initialTraceparent
+ * 2) <meta name="traceparent" content="...">
+ * 3) fresh trace/span IDs
+ */
+export function createBrowserTraceContext(
+	options: BrowserTraceContextOptions = {},
+): BrowserTraceContext {
+	const metaName = options.metaName ?? "traceparent";
+	const bootstrap = options.initialTraceparent ?? readMetaTraceparent(metaName);
+	const parsed = parseTraceparent(bootstrap);
+
+	const state: BrowserTraceState = {
+		traceId: parsed?.traceId ?? generateTraceId(),
+		parentSpanId: parsed?.parentId ?? generateSpanId(),
+		traceFlags: normalizeTraceFlags(parsed?.traceFlags),
+	};
+
+	const api: BrowserTraceContext = {
+		getTraceContext() {
+			return toTraceContext(state);
+		},
+		getTraceparent() {
+			return formatTraceparent(state.traceId, state.parentSpanId, state.traceFlags);
+		},
+		setTraceContext(context) {
+			state.traceId = context.traceId;
+			state.parentSpanId = context.parentSpanId;
+			state.traceFlags = normalizeTraceFlags(context.traceFlags);
+		},
+		updateFromTraceparent(traceparent) {
+			const incoming = parseTraceparent(traceparent);
+			if (!incoming) return false;
+			state.traceId = incoming.traceId;
+			state.parentSpanId = incoming.parentId;
+			state.traceFlags = normalizeTraceFlags(incoming.traceFlags);
+			return true;
+		},
+		async withSpan(name, run) {
+			const currentParent = state.parentSpanId;
+			const span = startSpan({
+				traceId: state.traceId,
+				parentSpanId: currentParent,
+				traceFlags: state.traceFlags,
+			});
+
+			state.parentSpanId = span.spanId;
+			try {
+				return await run({
+					traceId: span.traceId,
+					parentSpanId: span.spanId,
+					traceFlags: span.traceFlags,
+					spanId: span.spanId,
+					name,
+				});
+			} finally {
+				state.parentSpanId = currentParent;
+			}
+		},
+	};
+
+	return api;
+}
+
+export interface BrowserTracedFetchOptions {
+	/** Base fetch implementation. Default: globalThis.fetch. */
+	baseFetch?: FetchFn;
+	/** Shared trace context manager. If omitted, a new one is created. */
+	trace?: BrowserTraceContext;
+	/** Predicate controlling where to forward `traceparent`. Default: same-origin only. */
+	propagateTo?: (url: URL) => boolean;
+	/** Whether to adopt response `traceparent` headers. Default: true. */
+	updateContextFromResponse?: boolean;
+}
+
+/**
+ * Create a browser fetch wrapper that injects W3C `traceparent`.
+ *
+ * By default it only propagates headers to same-origin URLs.
+ */
+export function createBrowserTracedFetch(options: BrowserTracedFetchOptions = {}): FetchFn {
+	const {
+		baseFetch = globalThis.fetch,
+		trace = createBrowserTraceContext(),
+		propagateTo = defaultPropagateTo,
+		updateContextFromResponse = true,
+	} = options;
+
+	return async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+		const { url } = resolveInput(input);
+		const parsedUrl = resolveUrl(url);
+
+		const ctx = trace.getTraceContext();
+		const span = startSpan({
+			traceId: ctx.traceId,
+			parentSpanId: ctx.parentSpanId,
+			traceFlags: ctx.traceFlags,
+		});
+		const traceparent = formatTraceparent(span.traceId, span.spanId, span.traceFlags);
+
+		const outbound = propagateTo(parsedUrl)
+			? injectTraceparent(input, init, traceparent)
+			: { input, init };
+
+		const response = await baseFetch(outbound.input, outbound.init);
+
+		if (updateContextFromResponse) {
+			const responseTraceparent = response.headers.get("traceparent");
+			if (!responseTraceparent || !trace.updateFromTraceparent(responseTraceparent)) {
+				trace.setTraceContext({
+					traceId: span.traceId,
+					parentSpanId: span.spanId,
+					traceFlags: span.traceFlags,
+				});
+			}
+		}
+
+		return response;
+	};
+}

package/src/fetch-utils.ts

@@ -0,0 +1,67 @@
+/**
+ * Shared fetch utilities for adapters that wrap fetch.
+ *
+ * Used by the traced fetch adapter, Supabase adapter, and browser module
+ * to avoid duplicating URL resolution, traceparent injection, and
+ * origin detection logic.
+ */
+
+/** Callable fetch signature (without static properties like `preconnect`). */
+export type FetchFn = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
+export function getLocationOrigin(): string | undefined {
+	const globalWithLocation = globalThis as { location?: { origin?: string } };
+	return globalWithLocation.location?.origin;
+}
+
+export function resolveUrl(url: string): URL {
+	const base = getLocationOrigin() ?? "http://localhost";
+	return new URL(url, base);
+}
+
+export function defaultPropagateTo(url: URL): boolean {
+	const origin = getLocationOrigin();
+	return origin != null && url.origin === origin;
+}
+
+/**
+ * Extract URL metadata from the three fetch input types.
+ * This is metadata-only — the original input is never modified.
+ */
+export 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 location-aware fallback
+	try {
+		return { url: new URL(input).href, method: "GET" };
+	} catch {
+		return {
+			url: resolveUrl(input).href,
+			method: "GET",
+		};
+	}
+}
+
+export function injectTraceparent(
+	input: RequestInfo | URL,
+	init: RequestInit | undefined,
+	traceparent: string,
+): { input: RequestInfo | URL; init: RequestInit | undefined } {
+	if (input instanceof Request) {
+		const request = new Request(input, init);
+		const headers = new Headers(request.headers);
+		headers.set("traceparent", traceparent);
+		return { input: new Request(request, { headers }), init: undefined };
+	}
+
+	const headers = new Headers(init?.headers);
+	headers.set("traceparent", traceparent);
+	return { input, init: { ...init, headers } };
+}

package/src/trace-context.ts

@@ -0,0 +1,41 @@
+import { generateSpanId, generateTraceId } from "./ids.ts";
+import { parseTraceparent } from "./traceparent.ts";
+
+const TRACE_FLAGS_RE = /^[\da-f]{2}$/;
+
+export function normalizeTraceFlags(traceFlags: string | undefined): string {
+	if (!traceFlags) return "01";
+	const normalized = traceFlags.toLowerCase();
+	return TRACE_FLAGS_RE.test(normalized) ? normalized : "01";
+}
+
+export interface SpanStartOptions {
+	traceId?: string;
+	parentSpanId?: string;
+	traceFlags?: string;
+}
+
+export interface SpanContext {
+	traceId: string;
+	spanId: string;
+	parentSpanId?: string;
+	traceFlags: string;
+}
+
+export function startSpan(options: SpanStartOptions = {}): SpanContext {
+	return {
+		traceId: options.traceId ?? generateTraceId(),
+		spanId: generateSpanId(),
+		parentSpanId: options.parentSpanId,
+		traceFlags: normalizeTraceFlags(options.traceFlags),
+	};
+}
+
+export function startSpanFromTraceparent(header: string | null | undefined): SpanContext {
+	const parsed = parseTraceparent(header);
+	return startSpan({
+		traceId: parsed?.traceId,
+		parentSpanId: parsed?.parentId,
+		traceFlags: parsed?.traceFlags,
+	});
+}

package/src/types.ts

@@ -22,6 +22,8 @@ export interface BaseTelemetryEvent {
 
 export interface HttpRequestEvent extends BaseTelemetryEvent {
 	kind: "http.request";
+	spanId?: string;
+	parentSpanId?: string;
 	method: string;
 	path: string;
 	status: number;
@@ -72,6 +74,7 @@ export type JobEvents = JobStartEvent | JobEndEvent | JobDispatchEvent | JobStep
 export interface ExternalCallEvent extends BaseTelemetryEvent {
 	kind: "external.call";
 	spanId: string;
+	parentSpanId?: string;
 	service: string;
 	operation: string;
 	duration_ms: number;
@@ -84,6 +87,7 @@ export type ExternalEvents = ExternalCallEvent;
 export interface DbQueryEvent extends BaseTelemetryEvent {
 	kind: "db.query";
 	spanId: string;
+	parentSpanId?: string;
 	/** Provider identifier (e.g. "prisma", "supabase", "drizzle"). */
 	provider: string;
 	/** The data entity being operated on — ORM model name or database table. */