@telemetry-dev/tanstack-ai 0.1.0 → 0.1.2

package/README.md

@@ -1,11 +1,12 @@
 # @telemetry-dev/tanstack-ai
 
 TanStack AI telemetry integration for [telemetry.dev](https://telemetry.dev). A `chat()` middleware
-that streams every run to the telemetry.dev ingest API. Each `chat()` call is its own OTel trace: a
-root span (operation `chat`, or `invoke_agent` once tools are used), a `chat` span per agent-loop
-iteration, and an `execute_tool` span per tool call — spans are typed by `gen_ai.operation.name`.
-Conversations are carried by `gen_ai.conversation.id` (lifted from `metadata.sessionId`, falling
-back to the chat's `threadId`), not by sharing one trace.
+that streams every run to the telemetry.dev ingest API. Each `chat()` call produces a root span
+(operation `chat`, or `invoke_agent` once tools are used), a `chat` span per agent-loop iteration,
+and an `execute_tool` span per tool call — spans are typed by `gen_ai.operation.name`. All calls of
+one conversation (`metadata.sessionId`, falling back to the chat's `threadId`) share one trace, with
+the root of each call as a sibling in start order; the id is also stamped as
+`gen_ai.conversation.id` on every span.
 
 ## Install
 
@@ -27,6 +28,12 @@ Requires `@tanstack/ai >= 0.28.0 < 1`.
 All four are also settable via `telemetryDev({ apiKey, baseUrl, environment, serviceName })`, which
 takes precedence over the environment.
 
+Trace sampling uses `OTEL_TRACES_SAMPLER` / `OTEL_TRACES_SAMPLER_ARG`, which also control session roots.
+The default is parent-based always-on.
+Pass an OTel `Sampler` as `telemetryDev({ sampler })` to override the environment.
+Real active parents keep their sampling decisions. The integration does not send dropped or record-only spans.
+The [session sampling contract](../otel/README.md#correlation-attributes) lists environment modes and argument defaults.
+
 ## Usage
 
 ```ts
@@ -44,8 +51,7 @@ const stream = chat({
 
 `metadata.userId` is recorded as the `user.id` span attribute and `metadata.sessionId` as
 `gen_ai.conversation.id` (when absent, the chat's `threadId` is used); any remaining metadata keys
-ride along as `td.metadata.<key>` attributes. Each call is its own trace — `sessionId` only
-correlates calls through `gen_ai.conversation.id`, it never merges them into a single trace.
+ride along as `td.metadata.<key>` attributes. Calls that share a conversation id share one trace.
 
 A single `telemetryDev()` instance is **concurrency-safe**: per-run state is keyed by the chat's
 middleware context, so you can create one at module scope and share it across overlapping `chat()`

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { Attributes } from "@opentelemetry/api";
-import { ReadableSpan } from "@opentelemetry/sdk-trace-base";
+import { ReadableSpan, Sampler } from "@opentelemetry/sdk-trace-base";
 import { ChatMiddleware } from "@tanstack/ai";
 
 //#region src/config.d.ts
@@ -12,12 +12,14 @@ interface TelemetryDevOptions {
   environment?: string;
   /** Service name attached to every trace. Falls back to `OTEL_SERVICE_NAME`, then `unknown_service`. */
   serviceName?: string;
+  /** OTel sampling policy. Defaults to OTEL_TRACES_SAMPLER / OTEL_TRACES_SAMPLER_ARG. */
+  sampler?: Sampler;
   /** Injected fetch implementation. Defaults to `globalThis.fetch`. */
   fetch?: typeof fetch;
   /** Serverless extender (e.g. Cloudflare `ctx.waitUntil`). When provided, `onFinish` does not await the POST. */
   waitUntil?: (p: Promise<unknown>) => void;
   /** Receives any error raised while emitting telemetry; the integration never throws into the SDK. */
-  onError?: (error: unknown) => void;
+  onError?: (cause: unknown) => void;
 }
 //#endregion
 //#region src/otel.d.ts
@@ -30,7 +32,8 @@ interface EmitterOverrides {
 //#region src/middleware.d.ts
 /**
  * Build a TanStack AI chat middleware that streams `chat()` runs to telemetry.dev as
- * OpenTelemetry GenAI (`gen_ai.*`) spans + metrics: one root span per `chat()` call, one CLIENT
+ * OpenTelemetry GenAI (`gen_ai.*`) spans + metrics: one root span per `chat()` call (the roots
+ * of one session share a trace, see withSessionParent), one CLIENT
  * span per agent-loop iteration, and one span per tool execution. Per-run state is keyed by the
  * middleware context in a WeakMap, so a single `telemetryDev()` instance is safe to share across
  * concurrent and overlapping `chat()` calls (e.g. registered once at module scope).

package/dist/index.mjs

@@ -1,18 +1,20 @@
-import { ROOT_CONTEXT, SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
-import { ProtobufMetricsSerializer, ProtobufTraceSerializer } from "@opentelemetry/otlp-transformer";
+import { ROOT_CONTEXT, SpanKind, SpanStatusCode, TraceFlags, context, trace } from "@opentelemetry/api";
+import { DORMANT_INTERVAL_MS, DURATION_BUCKETS, TOKEN_BUCKETS, createMetricExporter, createTraceExporter, jsonAttr, omitUndefined, otlpHeaders, sessionSampler, withSessionParent } from "@telemetry-dev/otel";
+import { ExportResultCode } from "@opentelemetry/core";
 import { resourceFromAttributes } from "@opentelemetry/resources";
-import { AggregationTemporality, MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
+import { MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
 import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
 //#region src/config.ts
 const DEFAULT_BASE_URL = "https://ingest.telemetry.dev";
 function resolveConfig(options = {}) {
-	const env = typeof process !== "undefined" && process.env ? process.env : {};
+	const env = globalThis.process?.env ?? {};
 	const baseUrl = (options.baseUrl ?? env.TELEMETRY_DEV_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
 	return {
 		apiKey: options.apiKey ?? env.TELEMETRY_DEV_API_KEY,
 		baseUrl,
 		environment: options.environment ?? env.TELEMETRY_DEV_ENVIRONMENT ?? "production",
 		serviceName: options.serviceName ?? env.OTEL_SERVICE_NAME ?? "unknown_service",
+		sampler: options.sampler,
 		fetchImpl: options.fetch ?? globalThis.fetch,
 		waitUntil: options.waitUntil,
 		onError: options.onError
@@ -20,72 +22,9 @@ function resolveConfig(options = {}) {
 }
 //#endregion
 //#region src/otel.ts
-const DURATION_BUCKETS = [
-	.01,
-	.02,
-	.04,
-	.08,
-	.16,
-	.32,
-	.64,
-	1.28,
-	2.56,
-	5.12,
-	10.24,
-	20.48,
-	40.96,
-	81.92
-];
-const TOKEN_BUCKETS = [
-	1,
-	4,
-	16,
-	64,
-	256,
-	1024,
-	4096,
-	16384,
-	65536,
-	262144,
-	1048576,
-	4194304,
-	16777216,
-	67108864
-];
 const SCOPE_NAME = "@telemetry-dev/tanstack-ai";
 const SCOPE_VERSION = "0.0.0";
-const RETRY_DELAYS_MS = [100, 500];
-const RETRYABLE_STATUSES = new Set([
-	429,
-	502,
-	503,
-	504
-]);
-const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-const cancelBody = async (res) => {
-	try {
-		await res.body?.cancel();
-	} catch {}
-};
-const postOtlp = async ({ fetchImpl, url, headers, body }) => {
-	for (let attempt = 0;; attempt += 1) {
-		try {
-			const res = await fetchImpl(url, {
-				method: "POST",
-				headers,
-				body
-			});
-			if (res.ok || !RETRYABLE_STATUSES.has(res.status) || attempt === RETRY_DELAYS_MS.length) {
-				await cancelBody(res);
-				return res;
-			}
-			await cancelBody(res);
-		} catch (error) {
-			if (attempt === RETRY_DELAYS_MS.length) throw error;
-		}
-		await delay(RETRY_DELAYS_MS[attempt]);
-	}
-};
+const isReadableSpan = (span) => "resource" in span && "instrumentationScope" in span && "events" in span && (span.spanContext().traceFlags & TraceFlags.SAMPLED) !== 0;
 const cache = /* @__PURE__ */ new Map();
 const buildCore = (config) => {
 	const { apiKey, baseUrl, environment, serviceName } = config;
@@ -93,63 +32,29 @@ const buildCore = (config) => {
 		"service.name": serviceName,
 		"deployment.environment.name": environment
 	});
-	const headers = {
-		"content-type": "application/x-protobuf",
-		authorization: `Bearer ${apiKey}`
-	};
-	const tracer = new BasicTracerProvider({ resource }).getTracer(SCOPE_NAME, SCOPE_VERSION);
-	const sendSpans = async (spans, transport) => {
-		const body = ProtobufTraceSerializer.serializeRequest(spans);
-		if (!body || body.byteLength === 0) return;
-		const { fetchImpl, onError } = transport;
-		const res = await postOtlp({
-			fetchImpl,
+	const headers = otlpHeaders(apiKey ?? "", "@telemetry-dev/tanstack-ai");
+	const tracer = new BasicTracerProvider({
+		resource,
+		sampler: sessionSampler(config.sampler)
+	}).getTracer(SCOPE_NAME, SCOPE_VERSION);
+	const sendSpans = (spans, transport) => new Promise((resolve, reject) => {
+		createTraceExporter({
 			url: `${baseUrl}/v1/traces`,
-			headers,
-			body
+			headers
+		}, { fetchImpl: transport.fetchImpl }).export(spans, (result) => {
+			if (result.code === ExportResultCode.SUCCESS) resolve();
+			else reject(result.error ?? /* @__PURE__ */ new Error("telemetry.dev trace export failed"));
 		});
-		if (!res.ok) onError?.(/* @__PURE__ */ new Error(`telemetry.dev trace ingest failed: ${res.status}`));
-	};
+	});
 	const buildMetrics = (transport) => {
-		const { fetchImpl, onError } = transport;
 		const meterProvider = new MeterProvider({
 			resource,
 			readers: [new PeriodicExportingMetricReader({
-				exporter: {
-					export(resourceMetrics, resultCallback) {
-						const body = ProtobufMetricsSerializer.serializeRequest(resourceMetrics);
-						if (!body || body.byteLength === 0) {
-							resultCallback({ code: 0 });
-							return;
-						}
-						fetchImpl(`${baseUrl}/v1/metrics`, {
-							method: "POST",
-							headers,
-							body
-						}).then((res) => {
-							if (!res.ok) {
-								const error = /* @__PURE__ */ new Error(`telemetry.dev metric ingest failed: ${res.status}`);
-								onError?.(error);
-								resultCallback({
-									code: 1,
-									error
-								});
-								return;
-							}
-							resultCallback({ code: 0 });
-						}).catch((error) => {
-							onError?.(error);
-							resultCallback({
-								code: 1,
-								error: error instanceof Error ? error : void 0
-							});
-						});
-					},
-					selectAggregationTemporality: () => AggregationTemporality.DELTA,
-					forceFlush: () => Promise.resolve(),
-					shutdown: () => Promise.resolve()
-				},
-				exportIntervalMillis: 2 ** 31 - 1
+				exporter: createMetricExporter({
+					url: `${baseUrl}/v1/metrics`,
+					headers
+				}, transport),
+				exportIntervalMillis: DORMANT_INTERVAL_MS
 			})]
 		});
 		const meter = meterProvider.getMeter(SCOPE_NAME, SCOPE_VERSION);
@@ -172,6 +77,7 @@ const buildCore = (config) => {
 	};
 };
 const coreFor = (config) => {
+	if (config.sampler) return buildCore(config);
 	const key = `${config.apiKey}|${config.baseUrl}|${config.environment}|${config.serviceName}`;
 	const cached = cache.get(key);
 	if (cached) return cached;
@@ -199,14 +105,15 @@ const createEmitter = (config, overrides) => {
 		metrics = void 0;
 		const p = (async () => {
 			try {
-				await sendSpans(spans);
+				const readableSpans = spans.filter(isReadableSpan);
+				if (readableSpans.length) await sendSpans(readableSpans);
 			} catch (e) {
-				onError?.(e);
+				onError?.(e instanceof Error ? e : new Error(String(e)));
 			}
 			try {
 				if (pipeline) await pipeline.shutdown();
 			} catch (e) {
-				onError?.(e);
+				onError?.(e instanceof Error ? e : new Error(String(e)));
 			}
 		})();
 		if (config.waitUntil) {
@@ -224,45 +131,32 @@ const createEmitter = (config, overrides) => {
 };
 //#endregion
 //#region src/middleware.ts
-function omitUndefined(attributes) {
-	const out = {};
-	for (const key of Object.keys(attributes)) {
-		const value = attributes[key];
-		if (value !== void 0) out[key] = value;
-	}
-	return out;
-}
+const isString = (value) => typeof value === "string";
+const isNumber = (value) => typeof value === "number";
+const isBigInt = (value) => typeof value === "bigint";
+const isObject = (value) => value !== null && typeof value === "object";
 function readId(value) {
-	if (typeof value === "string") return value.length > 0 ? value : null;
-	if (typeof value === "number" || typeof value === "bigint") return value.toString();
+	if (isString(value)) return value.length > 0 ? value : null;
+	if (isNumber(value) || isBigInt(value)) return value.toString();
 	return null;
 }
-function jsonAttr(value) {
-	if (value === void 0) return void 0;
-	if (typeof value === "string") return value;
-	try {
-		return JSON.stringify(value);
-	} catch {
-		return;
-	}
-}
 function firstNumber(...candidates) {
-	for (const candidate of candidates) if (typeof candidate === "number" && Number.isFinite(candidate)) return candidate;
+	for (const candidate of candidates) if (isNumber(candidate) && Number.isFinite(candidate)) return candidate;
 }
 function errorTypeName(err) {
 	if (err instanceof Error) return err.name || "Error";
-	if (err && typeof err === "object" && "name" in err) {
+	if (err && isObject(err) && "name" in err) {
 		const n = err.name;
-		if (typeof n === "string" && n.length > 0) return n;
+		if (isString(n) && n.length > 0) return n;
 	}
 	return "Error";
 }
 function errorMessage(err) {
 	if (err instanceof Error) return err.message;
-	if (typeof err === "string") return err;
-	if (err && typeof err === "object" && "message" in err) {
+	if (isString(err)) return err;
+	if (err && isObject(err) && "message" in err) {
 		const m = err.message;
-		if (typeof m === "string") return m;
+		if (isString(m)) return m;
 	}
 	return String(err);
 }
@@ -278,7 +172,7 @@ const MAX_TOKENS_KEYS = [
 ];
 function samplingAttributes(modelOptions) {
 	const sampling = modelOptions ?? {};
-	const nested = sampling["options"] && typeof sampling["options"] === "object" ? sampling["options"] : void 0;
+	const nested = sampling["options"] && isObject(sampling["options"]) ? sampling["options"] : void 0;
 	return omitUndefined({
 		"gen_ai.request.temperature": firstNumber(sampling["temperature"], nested?.["temperature"]),
 		"gen_ai.request.top_p": firstNumber(sampling["top_p"], sampling["topP"], nested?.["top_p"]),
@@ -287,7 +181,8 @@ function samplingAttributes(modelOptions) {
 }
 /**
 * Build a TanStack AI chat middleware that streams `chat()` runs to telemetry.dev as
-* OpenTelemetry GenAI (`gen_ai.*`) spans + metrics: one root span per `chat()` call, one CLIENT
+* OpenTelemetry GenAI (`gen_ai.*`) spans + metrics: one root span per `chat()` call (the roots
+* of one session share a trace, see withSessionParent), one CLIENT
 * span per agent-loop iteration, and one span per tool execution. Per-run state is keyed by the
 * middleware context in a WeakMap, so a single `telemetryDev()` instance is safe to share across
 * concurrent and overlapping `chat()` calls (e.g. registered once at module scope).
@@ -337,7 +232,7 @@ function telemetryDev(options, overrides) {
 			...state.rootSampling
 		}));
 		if (state.restMetadata) for (const [key, value] of Object.entries(state.restMetadata)) {
-			const attr = typeof value === "string" ? value : jsonAttr(value);
+			const attr = isString(value) ? value : jsonAttr(value);
 			if (attr !== void 0) state.rootSpan.setAttribute(`td.metadata.${key}`, attr);
 		}
 	};
@@ -398,7 +293,7 @@ function telemetryDev(options, overrides) {
 		onStart(ctx) {
 			try {
 				const rawMetadata = ctx.options?.["metadata"];
-				const metadata = rawMetadata && typeof rawMetadata === "object" ? rawMetadata : void 0;
+				const metadata = rawMetadata && isObject(rawMetadata) ? rawMetadata : void 0;
 				const userId = readId(metadata?.["userId"]);
 				const sessionId = readId(metadata?.["sessionId"]) ?? ctx.threadId;
 				let restMetadata;
@@ -410,7 +305,7 @@ function telemetryDev(options, overrides) {
 				const rootSpan = emitter.tracer.startSpan("chat", {
 					startTime: /* @__PURE__ */ new Date(),
 					kind: SpanKind.INTERNAL
-				});
+				}, withSessionParent(context.active(), sessionId ?? void 0, config.apiKey));
 				states.set(ctx, {
 					rootSpan,
 					rootCtx: trace.setSpan(ROOT_CONTEXT, rootSpan),
@@ -444,7 +339,7 @@ function telemetryDev(options, overrides) {
 				const inputMessages = [];
 				for (const prompt of chatConfig.systemPrompts) inputMessages.push({
 					role: "system",
-					content: typeof prompt === "string" ? prompt : prompt.content
+					content: isString(prompt) ? prompt : prompt.content
 				});
 				for (const message of chatConfig.messages) inputMessages.push({
 					role: message.role,
@@ -493,7 +388,7 @@ function telemetryDev(options, overrides) {
 				if (chunk.type === "CUSTOM") {
 					if (iteration.structured && chunk.name === "structured-output.complete") {
 						const raw = chunk.value?.raw;
-						if (typeof raw === "string") iteration.outputText = raw;
+						if (isString(raw)) iteration.outputText = raw;
 					}
 					return;
 				}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telemetry-dev/tanstack-ai",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "TanStack AI telemetry integration for telemetry.dev: chat() middleware emitting OpenTelemetry GenAI spans.",
   "keywords": [
     "genai",
@@ -36,13 +36,13 @@
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
-    "@opentelemetry/otlp-transformer": "^0.218.0",
+    "@opentelemetry/core": "^2.7.1",
     "@opentelemetry/resources": "^2.7.1",
     "@opentelemetry/sdk-metrics": "^2.7.1",
-    "@opentelemetry/sdk-trace-base": "^2.7.1"
+    "@opentelemetry/sdk-trace-base": "^2.7.1",
+    "@telemetry-dev/otel": "^0.1.2"
   },
   "devDependencies": {
-    "@opentelemetry/core": "^2.7.1",
     "@tanstack/ai": "0.28.0",
     "@types/node": "^25.5.0",
     "@typescript/native-preview": "7.0.0-dev.20260328.1",

package/src/config.ts

@@ -1,3 +1,5 @@
+import type { Sampler } from "@opentelemetry/sdk-trace-base";
+
 export interface TelemetryDevOptions {
   /** telemetry.dev ingest key (`td_live_…`). Falls back to `TELEMETRY_DEV_API_KEY`. When absent the integration is a no-op. */
   apiKey?: string;
@@ -7,12 +9,14 @@ export interface TelemetryDevOptions {
   environment?: string;
   /** Service name attached to every trace. Falls back to `OTEL_SERVICE_NAME`, then `unknown_service`. */
   serviceName?: string;
+  /** OTel sampling policy. Defaults to OTEL_TRACES_SAMPLER / OTEL_TRACES_SAMPLER_ARG. */
+  sampler?: Sampler;
   /** Injected fetch implementation. Defaults to `globalThis.fetch`. */
   fetch?: typeof fetch;
   /** Serverless extender (e.g. Cloudflare `ctx.waitUntil`). When provided, `onFinish` does not await the POST. */
   waitUntil?: (p: Promise<unknown>) => void;
   /** Receives any error raised while emitting telemetry; the integration never throws into the SDK. */
-  onError?: (error: unknown) => void;
+  onError?: (cause: unknown) => void;
 }
 
 export interface ResolvedConfig {
@@ -20,18 +24,16 @@ export interface ResolvedConfig {
   baseUrl: string;
   environment: string;
   serviceName: string;
+  sampler?: Sampler;
   fetchImpl: typeof fetch;
   waitUntil?: (p: Promise<unknown>) => void;
-  onError?: (error: unknown) => void;
+  onError?: (cause: unknown) => void;
 }
 
 const DEFAULT_BASE_URL = "https://ingest.telemetry.dev";
 
 export function resolveConfig(options: TelemetryDevOptions = {}): ResolvedConfig {
-  const env =
-    typeof process !== "undefined" && process.env
-      ? process.env
-      : ({} as Record<string, string | undefined>);
+  const env = globalThis.process?.env ?? {};
   const baseUrl = (options.baseUrl ?? env.TELEMETRY_DEV_BASE_URL ?? DEFAULT_BASE_URL).replace(
     /\/+$/,
     "",
@@ -41,6 +43,7 @@ export function resolveConfig(options: TelemetryDevOptions = {}): ResolvedConfig
     baseUrl,
     environment: options.environment ?? env.TELEMETRY_DEV_ENVIRONMENT ?? "production",
     serviceName: options.serviceName ?? env.OTEL_SERVICE_NAME ?? "unknown_service",
+    sampler: options.sampler,
     fetchImpl: options.fetch ?? globalThis.fetch,
     waitUntil: options.waitUntil,
     onError: options.onError,

package/src/middleware.ts

@@ -1,12 +1,14 @@
 import {
   type Attributes,
   type Context,
+  context as otelContext,
   ROOT_CONTEXT,
   type Span,
   SpanKind,
   SpanStatusCode,
   trace,
 } from "@opentelemetry/api";
+import { withSessionParent } from "@telemetry-dev/otel";
 import type {
   AbortInfo,
   AfterToolCallInfo,
@@ -20,67 +22,61 @@ import type {
   ToolPhaseCompleteInfo,
   UsageInfo,
 } from "@tanstack/ai";
+import { jsonAttr, omitUndefined } from "@telemetry-dev/otel";
 
 import { resolveConfig, type TelemetryDevOptions } from "./config.ts";
 import { createEmitter, type EmitterOverrides } from "./otel.ts";
 
-function omitUndefined(attributes: Attributes): Attributes {
-  const out: Attributes = {};
-  for (const key of Object.keys(attributes)) {
-    const value = attributes[key];
-    if (value !== undefined) {
-      out[key] = value;
-    }
-  }
-  return out;
-}
-
-function readId(value: unknown): string | null {
-  if (typeof value === "string") {
+type JsonValue =
+  | string
+  | number
+  | bigint
+  | boolean
+  | null
+  | undefined
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+const isString = (value: unknown): value is string => typeof value === "string";
+const isNumber = (value: unknown): value is number => typeof value === "number";
+const isBigInt = (value: unknown): value is bigint => typeof value === "bigint";
+const isObject = <T>(value: T): value is T & { [key: string]: JsonValue } =>
+  value !== null && typeof value === "object";
+
+function readId<T>(value: T): string | null {
+  if (isString(value)) {
     return value.length > 0 ? value : null;
   }
-  if (typeof value === "number" || typeof value === "bigint") {
+  if (isNumber(value) || isBigInt(value)) {
     return value.toString();
   }
   return null;
 }
 
-// Stringify structured content (messages / tool args) for the gen_ai.* string attributes the
-// ingest parses back into JSON. Returns undefined so omitUndefined drops absent content.
-function jsonAttr(value: unknown): string | undefined {
-  if (value === undefined) return undefined;
-  if (typeof value === "string") return value;
-  try {
-    return JSON.stringify(value);
-  } catch {
-    return undefined;
-  }
-}
-
-function firstNumber(...candidates: unknown[]): number | undefined {
+function firstNumber<T>(...candidates: T[]): number | undefined {
   for (const candidate of candidates) {
-    if (typeof candidate === "number" && Number.isFinite(candidate)) {
+    if (isNumber(candidate) && Number.isFinite(candidate)) {
       return candidate;
     }
   }
   return undefined;
 }
 
-function errorTypeName(err: unknown): string {
+function errorTypeName<T>(err: T): string {
   if (err instanceof Error) return err.name || "Error";
-  if (err && typeof err === "object" && "name" in err) {
+  if (err && isObject(err) && "name" in err) {
     const n = (err as { name?: unknown }).name;
-    if (typeof n === "string" && n.length > 0) return n;
+    if (isString(n) && n.length > 0) return n;
   }
   return "Error";
 }
 
-function errorMessage(err: unknown): string {
+function errorMessage<T>(err: T): string {
   if (err instanceof Error) return err.message;
-  if (typeof err === "string") return err;
-  if (err && typeof err === "object" && "message" in err) {
+  if (isString(err)) return err;
+  if (err && isObject(err) && "message" in err) {
     const m = (err as { message?: unknown }).message;
-    if (typeof m === "string") return m;
+    if (isString(m)) return m;
   }
   return String(err);
 }
@@ -101,11 +97,11 @@ const MAX_TOKENS_KEYS = [
 
 // Sampling options live in opaque provider-native `modelOptions`; pick the first numeric value
 // among the known spellings (including Ollama's nested `options`) for the gen_ai.request.* attrs.
-function samplingAttributes(modelOptions: Record<string, unknown> | undefined): Attributes {
+function samplingAttributes(modelOptions: Record<string, JsonValue> | undefined): Attributes {
   const sampling = modelOptions ?? {};
   const nested =
-    sampling["options"] && typeof sampling["options"] === "object"
-      ? (sampling["options"] as Record<string, unknown>)
+    sampling["options"] && isObject(sampling["options"])
+      ? (sampling["options"] as Record<string, JsonValue>)
       : undefined;
   return omitUndefined({
     "gen_ai.request.temperature": firstNumber(sampling["temperature"], nested?.["temperature"]),
@@ -136,7 +132,7 @@ interface RunState {
   responseModel: string | null;
   userId: string | null;
   sessionId: string;
-  restMetadata: Record<string, unknown> | undefined;
+  restMetadata: Record<string, JsonValue> | undefined;
   rootInput: string | undefined;
   rootSampling: Attributes;
   rootCaptured: boolean;
@@ -157,7 +153,8 @@ interface RunState {
 
 /**
  * Build a TanStack AI chat middleware that streams `chat()` runs to telemetry.dev as
- * OpenTelemetry GenAI (`gen_ai.*`) spans + metrics: one root span per `chat()` call, one CLIENT
+ * OpenTelemetry GenAI (`gen_ai.*`) spans + metrics: one root span per `chat()` call (the roots
+ * of one session share a trace, see withSessionParent), one CLIENT
  * span per agent-loop iteration, and one span per tool execution. Per-run state is keyed by the
  * middleware context in a WeakMap, so a single `telemetryDev()` instance is safe to share across
  * concurrent and overlapping `chat()` calls (e.g. registered once at module scope).
@@ -229,7 +226,7 @@ export function telemetryDev(
     );
     if (state.restMetadata) {
       for (const [key, value] of Object.entries(state.restMetadata)) {
-        const attr = typeof value === "string" ? value : jsonAttr(value);
+        const attr = isString(value) ? value : jsonAttr(value);
         if (attr !== undefined) {
           state.rootSpan.setAttribute(`td.metadata.${key}`, attr);
         }
@@ -297,14 +294,14 @@ export function telemetryDev(
       try {
         const rawMetadata = ctx.options?.["metadata"];
         const metadata =
-          rawMetadata && typeof rawMetadata === "object"
-            ? (rawMetadata as Record<string, unknown>)
+          rawMetadata && isObject(rawMetadata)
+            ? (rawMetadata as Record<string, JsonValue>)
             : undefined;
         const userId = readId(metadata?.["userId"]);
         const sessionId = readId(metadata?.["sessionId"]) ?? ctx.threadId;
-        let restMetadata: Record<string, unknown> | undefined;
+        let restMetadata: Record<string, JsonValue> | undefined;
         if (metadata) {
-          const rest: Record<string, unknown> = {};
+          const rest: Record<string, JsonValue> = {};
           for (const [key, value] of Object.entries(metadata)) {
             if (key !== "userId" && key !== "sessionId") {
               rest[key] = value;
@@ -313,10 +310,12 @@ export function telemetryDev(
           restMetadata = Object.keys(rest).length > 0 ? rest : undefined;
         }
 
-        const rootSpan = emitter.tracer.startSpan("chat", {
-          startTime: new Date(),
-          kind: SpanKind.INTERNAL,
-        });
+        // Session-parented: see withSessionParent.
+        const rootSpan = emitter.tracer.startSpan(
+          "chat",
+          { startTime: new Date(), kind: SpanKind.INTERNAL },
+          withSessionParent(otelContext.active(), sessionId ?? undefined, config.apiKey),
+        );
         states.set(ctx, {
           rootSpan,
           rootCtx: trace.setSpan(ROOT_CONTEXT, rootSpan),
@@ -360,14 +359,16 @@ export function telemetryDev(
         for (const prompt of chatConfig.systemPrompts) {
           inputMessages.push({
             role: "system",
-            content: typeof prompt === "string" ? prompt : prompt.content,
+            content: isString(prompt) ? prompt : prompt.content,
           });
         }
         for (const message of chatConfig.messages) {
           inputMessages.push({ role: message.role, content: message.content });
         }
         const inputJson = jsonAttr(inputMessages);
-        const sampling = samplingAttributes(chatConfig.modelOptions ?? ctx.modelOptions);
+        const sampling = samplingAttributes(
+          (chatConfig.modelOptions ?? ctx.modelOptions) as Record<string, JsonValue> | undefined,
+        );
         if (!state.rootCaptured) {
           state.rootCaptured = true;
           state.rootInput = inputJson;
@@ -418,7 +419,7 @@ export function telemetryDev(
           // still holds the agent loop's text, so this is the structured span's only output.
           if (iteration.structured && chunk.name === "structured-output.complete") {
             const raw = (chunk.value as { raw?: unknown } | null | undefined)?.raw;
-            if (typeof raw === "string") iteration.outputText = raw;
+            if (isString(raw)) iteration.outputText = raw;
           }
           return undefined;
         }

package/src/otel.ts

@@ -1,35 +1,30 @@
-import { type Attributes, type Histogram, type Span, type Tracer } from "@opentelemetry/api";
 import {
-  ProtobufMetricsSerializer,
-  ProtobufTraceSerializer,
-} from "@opentelemetry/otlp-transformer";
+  type Attributes,
+  type Histogram,
+  type Span,
+  TraceFlags,
+  type Tracer,
+} from "@opentelemetry/api";
+import { ExportResultCode } from "@opentelemetry/core";
 import { resourceFromAttributes } from "@opentelemetry/resources";
-import {
-  AggregationTemporality,
-  MeterProvider,
-  PeriodicExportingMetricReader,
-  type PushMetricExporter,
-  type ResourceMetrics,
-} from "@opentelemetry/sdk-metrics";
+import { MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
 import { BasicTracerProvider, type ReadableSpan } from "@opentelemetry/sdk-trace-base";
+import {
+  createMetricExporter,
+  createTraceExporter,
+  DORMANT_INTERVAL_MS,
+  DURATION_BUCKETS,
+  otlpHeaders,
+  sessionSampler,
+  TOKEN_BUCKETS,
+} from "@telemetry-dev/otel";
 
 import type { ResolvedConfig } from "./config.ts";
 
-// Histogram bucket boundaries from the OTel GenAI semantic-convention recommendations for
-// gen_ai.client.operation.duration (seconds) and gen_ai.client.token.usage ({token}).
-const DURATION_BUCKETS = [
-  0.01, 0.02, 0.04, 0.08, 0.16, 0.32, 0.64, 1.28, 2.56, 5.12, 10.24, 20.48, 40.96, 81.92,
-];
-const TOKEN_BUCKETS = [
-  1, 4, 16, 64, 256, 1024, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864,
-];
-
 const SCOPE_NAME = "@telemetry-dev/tanstack-ai";
 const SCOPE_VERSION = "0.0.0";
 
-// Spans created by the SDK tracer are concrete `Span`s that, once `.end()`ed, also satisfy
-// ReadableSpan (the serializer's input). The integration only holds the api `Span` type, so the
-// emitter surface accepts `Span[]` and casts at the single serialize site.
+// The sampler can return non-recording API spans.
 export interface Emitter {
   tracer: Tracer;
   recordDuration(seconds: number, attributes: Attributes): void;
@@ -38,52 +33,12 @@ export interface Emitter {
 }
 
 export interface EmitterOverrides {
-  // Test seam: capture serialized spans / recorded metric points instead of POSTing them.
   sendSpans?: (spans: ReadableSpan[]) => Promise<void>;
   recordDuration?: (seconds: number, attributes: Attributes) => void;
   recordTokens?: (tokenType: "input" | "output", count: number, attributes: Attributes) => void;
 }
 
-type Transport = { fetchImpl: typeof fetch; onError?: (error: unknown) => void };
-
-const RETRY_DELAYS_MS = [100, 500] as const;
-
-const RETRYABLE_STATUSES = new Set([429, 502, 503, 504]);
-
-const delay = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
-
-const cancelBody = async (res: Response) => {
-  try {
-    await res.body?.cancel();
-  } catch {}
-};
-
-const postOtlp = async ({
-  fetchImpl,
-  url,
-  headers,
-  body,
-}: {
-  fetchImpl: typeof fetch;
-  url: string;
-  headers: Record<string, string>;
-  body: Uint8Array;
-}) => {
-  for (let attempt = 0; ; attempt += 1) {
-    try {
-      const res = await fetchImpl(url, { method: "POST", headers, body });
-      if (res.ok || !RETRYABLE_STATUSES.has(res.status) || attempt === RETRY_DELAYS_MS.length) {
-        await cancelBody(res);
-        return res;
-      }
-      await cancelBody(res);
-    } catch (error) {
-      if (attempt === RETRY_DELAYS_MS.length) throw error;
-    }
-
-    await delay(RETRY_DELAYS_MS[attempt]!);
-  }
-};
+type Transport = { fetchImpl: typeof fetch; onError?: (cause: unknown) => void };
 
 interface MetricsPipeline {
   durationHistogram: Histogram;
@@ -97,6 +52,12 @@ interface EmitterCore {
   buildMetrics: (transport: Transport) => MetricsPipeline;
 }
 
+const isReadableSpan = (span: Span): span is Span & ReadableSpan =>
+  "resource" in span &&
+  "instrumentationScope" in span &&
+  "events" in span &&
+  (span.spanContext().traceFlags & TraceFlags.SAMPLED) !== 0;
+
 const cache = new Map<string, EmitterCore>();
 
 const buildCore = (config: ResolvedConfig): EmitterCore => {
@@ -105,23 +66,21 @@ const buildCore = (config: ResolvedConfig): EmitterCore => {
     "service.name": serviceName,
     "deployment.environment.name": environment,
   });
-  const headers = {
-    "content-type": "application/x-protobuf",
-    authorization: `Bearer ${apiKey}`,
-  };
+  const headers = otlpHeaders(apiKey ?? "", "@telemetry-dev/tanstack-ai");
 
-  const provider = new BasicTracerProvider({ resource });
+  const provider = new BasicTracerProvider({ resource, sampler: sessionSampler(config.sampler) });
   const tracer = provider.getTracer(SCOPE_NAME, SCOPE_VERSION);
 
-  const sendSpans = async (spans: ReadableSpan[], transport: Transport): Promise<void> => {
-    const body = ProtobufTraceSerializer.serializeRequest(spans);
-    if (!body || body.byteLength === 0) return;
-    const { fetchImpl, onError } = transport;
-    const res = await postOtlp({ fetchImpl, url: `${baseUrl}/v1/traces`, headers, body });
-    if (!res.ok) {
-      onError?.(new Error(`telemetry.dev trace ingest failed: ${res.status}`));
-    }
-  };
+  const sendSpans = (spans: ReadableSpan[], transport: Transport): Promise<void> =>
+    new Promise((resolve, reject) => {
+      createTraceExporter(
+        { url: `${baseUrl}/v1/traces`, headers },
+        { fetchImpl: transport.fetchImpl },
+      ).export(spans, (result) => {
+        if (result.code === ExportResultCode.SUCCESS) resolve();
+        else reject(result.error ?? new Error("telemetry.dev trace export failed"));
+      });
+    });
 
   // Each emitter builds its OWN metrics pipeline bound to its OWN transport: the exporter closes
   // over this call's fetch/onError, so concurrent same-identity emitters never flush metrics
@@ -129,39 +88,10 @@ const buildCore = (config: ResolvedConfig): EmitterCore => {
   // interval timer) and lazily rebuilt, so a reused globally-registered emitter gets a fresh meter
   // per generation without leaking timers.
   const buildMetrics = (transport: Transport): MetricsPipeline => {
-    const { fetchImpl, onError } = transport;
-    const metricsExporter: PushMetricExporter = {
-      export(resourceMetrics: ResourceMetrics, resultCallback) {
-        const body = ProtobufMetricsSerializer.serializeRequest(resourceMetrics);
-        if (!body || body.byteLength === 0) {
-          resultCallback({ code: 0 });
-          return;
-        }
-        // DELTA metric batches are not idempotent; a retry after an already-ingested response would double-count.
-        fetchImpl(`${baseUrl}/v1/metrics`, { method: "POST", headers, body })
-          .then((res) => {
-            if (!res.ok) {
-              const error = new Error(`telemetry.dev metric ingest failed: ${res.status}`);
-              onError?.(error);
-              resultCallback({ code: 1, error });
-              return;
-            }
-            resultCallback({ code: 0 });
-          })
-          .catch((error: unknown) => {
-            onError?.(error);
-            resultCallback({ code: 1, error: error instanceof Error ? error : undefined });
-          });
-      },
-      selectAggregationTemporality: () => AggregationTemporality.DELTA,
-      forceFlush: () => Promise.resolve(),
-      shutdown: () => Promise.resolve(),
-    };
-
     // A long interval keeps the periodic timer dormant; the single flush is driven by shutdown().
     const reader = new PeriodicExportingMetricReader({
-      exporter: metricsExporter,
-      exportIntervalMillis: 2 ** 31 - 1,
+      exporter: createMetricExporter({ url: `${baseUrl}/v1/metrics`, headers }, transport),
+      exportIntervalMillis: DORMANT_INTERVAL_MS,
     });
     const meterProvider = new MeterProvider({ resource, readers: [reader] });
     const meter = meterProvider.getMeter(SCOPE_NAME, SCOPE_VERSION);
@@ -183,6 +113,7 @@ const buildCore = (config: ResolvedConfig): EmitterCore => {
 };
 
 const coreFor = (config: ResolvedConfig): EmitterCore => {
+  if (config.sampler) return buildCore(config);
   const key = `${config.apiKey}|${config.baseUrl}|${config.environment}|${config.serviceName}`;
   const cached = cache.get(key);
   if (cached) return cached;
@@ -226,14 +157,15 @@ export const createEmitter = (config: ResolvedConfig, overrides?: EmitterOverrid
     metrics = undefined;
     const p = (async () => {
       try {
-        await sendSpans(spans as unknown as ReadableSpan[]);
+        const readableSpans = spans.filter(isReadableSpan);
+        if (readableSpans.length) await sendSpans(readableSpans);
       } catch (e) {
-        onError?.(e);
+        onError?.(e instanceof Error ? e : new Error(String(e)));
       }
       try {
         if (pipeline) await pipeline.shutdown();
       } catch (e) {
-        onError?.(e);
+        onError?.(e instanceof Error ? e : new Error(String(e)));
       }
     })();
     if (config.waitUntil) {