@telemetry-dev/sdk 0.1.3 → 0.1.6

package/README.md

@@ -77,7 +77,8 @@ The SDK installs the [session sampling wrapper](../otel/README.md#correlation-at
 - `observe(fn, options?)` — wrap a sync/async function: args → input, return → output, errors
   captured and rethrown; activates context for nesting.
 - `startSpan(name, options?)` — manual handle; does **not** activate context. `handle.update()`,
-  `handle.end()`, `handle.traceparent`, `handle.span` (raw OTel span).
+  `handle.end()`, `handle.recordOutputChunk(timestampMs?)`, `handle.traceparent`, `handle.span`
+  (raw OTel span).
 - `startActiveSpan(name, options?, fn)` — callback-scoped; activates context, auto-ends.
 - `updateActiveSpan(fields)` — update the innermost active span.
 - `propagateAttributes({ userId, sessionId, metadata }, fn)` — stamps `user.id`,
@@ -89,16 +90,35 @@ The SDK installs the [session sampling wrapper](../otel/README.md#correlation-at
   context.
 - `extractW3cContext(carrier, options?)` / `injectW3cContext(context, carrier, options?)` — extract
   or inject W3C trace context. Baggage is omitted unless `includeBaggage` is true.
+- `captureEnabled("input" | "output")` — report whether the active initialized client permits that
+  capture direction. Returns `false` when no client is initialized.
+- `boundedCapture(value, options?)` — copy a JSON-compatible value within bounded work and retained
+  size. Defaults to 48 KiB, depth 32, and 1,000 traversal items. Returns `{ value, truncated }`;
+  `value` can be partial or `undefined` when a limit, cycle, getter, or skip rule prevents capture.
 - `flush()` / `shutdown()` — export pending data; required before serverless freeze/exit.
 
 Span types: `span` (default) | `generation` | `tool` | `agent` | `embedding` — mapped to
 `gen_ai.operation.name` `function` / `chat` / `execute_tool` / `invoke_agent` / `embeddings`.
 Generation fields (`model`, `provider`, `usage`, `costUsd`, sampling params, …) map to the OTel
-GenAI semantic conventions; cost is computed server-side from usage unless `costUsd` is set.
+GenAI semantic conventions. An explicit `costUsd` takes precedence; otherwise, the server estimates
+standard token cost when reported usage and matching model pricing are available. Missing pricing leaves cost
+unavailable, not zero, and does not prevent tracing or token accounting.
 
 Duration and token-usage histograms (`gen_ai.client.operation.duration`,
 `gen_ai.client.token.usage`) are recorded automatically for generation/agent/embedding/tool spans.
 
+Generation spans also emit `gen_ai.client.operation.time_to_first_chunk` when a valid
+`timeToFirstChunkMs` is supplied. `handle.recordOutputChunk()` records each nonempty output chunk's
+arrival; after the first chunk, intervals contribute to
+`gen_ai.client.operation.time_per_output_chunk`. Both histograms use seconds and are emitted only
+after the ended span passes `spanFilter`, including interrupted streams. Chunk timing uses bounded
+histogram state and does not retain individual intervals. Pull-based timing includes consumer delay
+between reads. An explicit timestamp uses the same monotonic millisecond clock for every chunk.
+
+Provider integrations feature-detect chunk recording. With an older core SDK that lacks
+`recordOutputChunk`, streams and existing tracing continue normally, but chunk-interval metrics are
+unavailable. Upgrade the core SDK with provider integrations to enable the new metric.
+
 ## Serverless
 
 Use `exportMode: "immediate"` and either `await flush()` before returning or pass the platform

package/dist/index.d.mts

@@ -59,6 +59,24 @@ interface TelemetryOptions {
   sdkName?: string;
 }
 //#endregion
+//#region src/capture.d.ts
+interface BoundedCaptureOptions {
+  maxBytes?: number;
+  maxDepth?: number;
+  maxItems?: number;
+  skip?: (key: string, value: unknown, parent: unknown, path: readonly string[]) => boolean;
+}
+interface BoundedCaptureResult {
+  value: unknown;
+  truncated: boolean;
+}
+interface BoundedCaptureDetails extends BoundedCaptureResult {
+  bytes: number;
+  items: number;
+}
+declare function boundedCaptureDetails(input: unknown, options?: BoundedCaptureOptions): BoundedCaptureDetails;
+declare function boundedCapture(input: unknown, options?: BoundedCaptureOptions): BoundedCaptureResult;
+//#endregion
 //#region src/attrs.d.ts
 type SpanType = "span" | "generation" | "tool" | "agent" | "embedding";
 interface TokenUsage {
@@ -68,6 +86,15 @@ interface TokenUsage {
   cacheReadInputTokens?: number;
   cacheCreationInputTokens?: number;
   reasoningOutputTokens?: number;
+  textInputTokens?: number;
+  textOutputTokens?: number;
+  textCacheReadInputTokens?: number;
+  imageInputTokens?: number;
+  imageOutputTokens?: number;
+  imageCacheReadInputTokens?: number;
+  audioInputTokens?: number;
+  audioOutputTokens?: number;
+  audioCacheReadInputTokens?: number;
 }
 interface GenerationFields {
   model?: string;
@@ -126,6 +153,7 @@ interface TelemetryClient {
   /** Flush + teardown + unregister globals; the client becomes a no-op afterwards. */
   shutdown(): Promise<void>;
 }
+declare function captureEnabled(kind: "input" | "output"): boolean;
 declare function flush(): Promise<void>;
 declare function shutdown(): Promise<void>;
 declare function init(options?: TelemetryOptions, overrides?: ClientOverrides): TelemetryClient;
@@ -172,6 +200,8 @@ interface SpanHandle {
   readonly traceparent: string | null;
   readonly isRecording: boolean;
   update(fields: SpanFields): SpanHandle;
+  /** Records an output chunk arrival. Pull-based streams include consumer delay between pulls. */
+  recordOutputChunk(timestampMs?: number): void;
   end(fields?: SpanFields & {
     endTime?: Date | number;
   }): void;
@@ -205,4 +235,4 @@ interface ObserveOptions extends StartSpanOptions {
  */
 declare function observe<TThis, TArgs extends unknown[], TReturn>(fn: (this: TThis, ...args: TArgs) => TReturn, options?: ObserveOptions): (...args: TArgs) => TReturn;
 //#endregion
-export { type AgentFields, type BatchOptions, type ClientOverrides, type ExportMode, type GenerationFields, type LogLevel, type LogOptions, type MaskFn, type ObserveOptions, type ParentRef, type PropagatedAttributes, SCOPE_NAME, type SdkLogLevel, type SpanFields, type SpanHandle, type SpanType, type StartSpanOptions, type TelemetryClient, type TelemetryOptions, TelemetrySpanProcessor, type TelemetrySpanProcessorOptions, type TokenUsage, type ToolFields, activeContext, extractW3cContext, flush, getTraceparent, init, injectW3cContext, log, observe, propagateAttributes, shutdown, startActiveSpan, startSpan, updateActiveSpan, withContext };
+export { type AgentFields, type BatchOptions, type BoundedCaptureDetails, type BoundedCaptureOptions, type BoundedCaptureResult, type ClientOverrides, type ExportMode, type GenerationFields, type LogLevel, type LogOptions, type MaskFn, type ObserveOptions, type ParentRef, type PropagatedAttributes, SCOPE_NAME, type SdkLogLevel, type SpanFields, type SpanHandle, type SpanType, type StartSpanOptions, type TelemetryClient, type TelemetryOptions, TelemetrySpanProcessor, type TelemetrySpanProcessorOptions, type TokenUsage, type ToolFields, activeContext, boundedCapture, boundedCaptureDetails, captureEnabled, extractW3cContext, flush, getTraceparent, init, injectW3cContext, log, observe, propagateAttributes, shutdown, startActiveSpan, startSpan, updateActiveSpan, withContext };

package/dist/index.mjs

@@ -3,7 +3,7 @@ import { CompositePropagator, W3CBaggagePropagator, W3CTraceContextPropagator, p
 import { resourceFromAttributes } from "@opentelemetry/resources";
 import { BatchLogRecordProcessor, LoggerProvider, SimpleLogRecordProcessor } from "@opentelemetry/sdk-logs";
 import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
-import { AlsContextManager, BATCHED_METRIC_INTERVAL_MS, DEFAULT_BASE_URL, DEFAULT_BATCH, DORMANT_INTERVAL_MS, PROPAGATED_KEY, SCOPE_NAME, SCOPE_NAME as SCOPE_NAME$1, SCOPE_VERSION, StampingSpanProcessor, TelemetrySpanProcessor, activeContext, activeContext as activeContext$1, als, createLogExporter, createMetricExporter, createMetricsPipeline, createTraceExporter, diag, jsonAttr, omitUndefined, otlpHeaders, propagateAttributes, propagatedFromContext, reportError, resolveEnv, sessionIdOf, sessionRootTracerProvider, sessionSampler, setLogLevel, withContext, withContext as withContext$1, withSessionParent } from "@telemetry-dev/otel";
+import { AlsContextManager, BATCHED_METRIC_INTERVAL_MS, DEFAULT_BASE_URL, DEFAULT_BATCH, DORMANT_INTERVAL_MS, DURATION_BUCKETS, OUTPUT_CHUNK_HISTOGRAM, PROPAGATED_KEY, SCOPE_NAME, SCOPE_NAME as SCOPE_NAME$1, SCOPE_VERSION, StampingSpanProcessor, TelemetrySpanProcessor, activeContext, activeContext as activeContext$1, als, createLogExporter, createMetricExporter, createMetricsPipeline, createTraceExporter, diag, jsonAttr, omitUndefined, otlpHeaders, propagateAttributes, propagatedFromContext, reportError, resolveEnv, sessionIdOf, sessionRootTracerProvider, sessionSampler, setLogLevel, withContext, withContext as withContext$1, withSessionParent } from "@telemetry-dev/otel";
 import { SeverityNumber } from "@opentelemetry/api-logs";
 function resolveConfig(options = {}) {
 	const env = resolveEnv();
@@ -48,6 +48,10 @@ let activeClient;
 function currentClient() {
 	return activeClient ?? NOOP_CLIENT;
 }
+function captureEnabled(kind) {
+	const config = currentClient().core?.config;
+	return kind === "input" ? config?.captureInput ?? false : config?.captureOutput ?? false;
+}
 function flush() {
 	return currentClient().flush();
 }
@@ -186,6 +190,137 @@ function initInner(options, overrides) {
 //#endregion
 //#region src/capture.ts
 const TRUNCATION_MARKER = "...[truncated]";
+const jsonStringByteLength = (value, limit) => {
+	let bytes = 2;
+	for (let index = 0; index < value.length && bytes <= limit; index += 1) {
+		const code = value.charCodeAt(index);
+		if (code === 34 || code === 92 || code === 8 || code === 9 || code === 10 || code === 12 || code === 13) bytes += 2;
+		else if (code < 32) bytes += 6;
+		else if (code < 128) bytes += 1;
+		else if (code < 2048) bytes += 2;
+		else if (code >= 55296 && code <= 56319) {
+			const next = value.charCodeAt(index + 1);
+			if (next >= 56320 && next <= 57343) {
+				bytes += 4;
+				index += 1;
+			} else bytes += 6;
+		} else if (code >= 56320 && code <= 57343) bytes += 6;
+		else bytes += 3;
+	}
+	return bytes;
+};
+const captureLimit = (name, value, fallback) => {
+	if (value === void 0) return fallback;
+	if (!Number.isSafeInteger(value) || value < 0) throw new RangeError(`${name} must be a non-negative safe integer`);
+	return value;
+};
+function boundedCaptureDetails(input, options = {}) {
+	const maxBytes = captureLimit("maxBytes", options.maxBytes, 48 * 1024);
+	const maxDepth = captureLimit("maxDepth", options.maxDepth, 32);
+	const maxItems = captureLimit("maxItems", options.maxItems, 1e3);
+	const ancestors = /* @__PURE__ */ new WeakSet();
+	let bytes = 0;
+	let items = 0;
+	let truncated = false;
+	const visit = (value, depth, path) => {
+		if (items >= maxItems) {
+			truncated = true;
+			return;
+		}
+		items += 1;
+		if (value === null || typeof value === "boolean" || typeof value === "number" || typeof value === "string") {
+			const length = typeof value === "string" ? jsonStringByteLength(value, maxBytes - bytes) : JSON.stringify(value)?.length ?? 0;
+			if (bytes + length > maxBytes) {
+				truncated = true;
+				return;
+			}
+			bytes += length;
+			return value;
+		}
+		if (typeof value !== "object") return void 0;
+		if (depth >= maxDepth || ancestors.has(value) || bytes + 2 > maxBytes) {
+			truncated = true;
+			return;
+		}
+		ancestors.add(value);
+		bytes += 2;
+		try {
+			if (Array.isArray(value)) {
+				const result = [];
+				for (const item of value) {
+					if (items >= maxItems) {
+						truncated = true;
+						break;
+					}
+					const previousBytes = bytes;
+					if (result.length > 0) bytes += 1;
+					const converted = visit(item, depth + 1, path);
+					if (converted === void 0) bytes = previousBytes;
+					else result.push(converted);
+				}
+				return result;
+			}
+			const result = {};
+			let emitted = false;
+			for (const key in value) {
+				if (items >= maxItems) {
+					truncated = true;
+					break;
+				}
+				if (!Object.hasOwn(value, key)) {
+					items += 1;
+					continue;
+				}
+				const keyBytes = jsonStringByteLength(key, maxBytes - bytes) + 1 + (emitted ? 1 : 0);
+				if (bytes + keyBytes > maxBytes) {
+					items += 1;
+					truncated = true;
+					continue;
+				}
+				let item;
+				try {
+					const descriptor = Object.getOwnPropertyDescriptor(value, key);
+					item = descriptor?.get ? descriptor.get.call(value) : descriptor?.value;
+					if (options.skip?.(key, item, value, path)) {
+						items += 1;
+						continue;
+					}
+				} catch {
+					items += 1;
+					truncated = true;
+					continue;
+				}
+				const previousBytes = bytes;
+				bytes += keyBytes;
+				const converted = visit(item, depth + 1, [...path, key]);
+				if (converted === void 0) bytes = previousBytes;
+				else {
+					result[key] = converted;
+					emitted = true;
+				}
+			}
+			return result;
+		} catch {
+			truncated = true;
+			return;
+		} finally {
+			ancestors.delete(value);
+		}
+	};
+	return {
+		value: visit(input, 0, []),
+		truncated,
+		bytes,
+		items
+	};
+}
+function boundedCapture(input, options = {}) {
+	const { value, truncated } = boundedCaptureDetails(input, options);
+	return {
+		value,
+		truncated
+	};
+}
 function truncate(value, maxLength) {
 	if (value.length <= maxLength) return value;
 	return value.slice(0, Math.max(maxLength - 14, 0)) + TRUNCATION_MARKER;
@@ -308,6 +443,15 @@ function fieldsToAttributes(fields, type, cfg) {
 		"gen_ai.usage.cache_read.input_tokens": fields.usage?.cacheReadInputTokens,
 		"gen_ai.usage.cache_creation.input_tokens": fields.usage?.cacheCreationInputTokens,
 		"gen_ai.usage.reasoning.output_tokens": fields.usage?.reasoningOutputTokens,
+		"gen_ai.usage.text.input_tokens": fields.usage?.textInputTokens,
+		"gen_ai.usage.text.output_tokens": fields.usage?.textOutputTokens,
+		"gen_ai.usage.text.cache_read.input_tokens": fields.usage?.textCacheReadInputTokens,
+		"gen_ai.usage.image.input_tokens": fields.usage?.imageInputTokens,
+		"gen_ai.usage.image.output_tokens": fields.usage?.imageOutputTokens,
+		"gen_ai.usage.image.cache_read.input_tokens": fields.usage?.imageCacheReadInputTokens,
+		"gen_ai.usage.audio.input_tokens": fields.usage?.audioInputTokens,
+		"gen_ai.usage.audio.output_tokens": fields.usage?.audioOutputTokens,
+		"gen_ai.usage.audio.cache_read.input_tokens": fields.usage?.audioCacheReadInputTokens,
 		"gen_ai.usage.cost": fields.costUsd,
 		"gen_ai.response.finish_reasons": fields.finishReason ? [fields.finishReason] : void 0,
 		"gen_ai.output.type": fields.outputType,
@@ -363,6 +507,7 @@ const NOOP_SPAN_HANDLE = {
 	traceparent: null,
 	isRecording: false,
 	update: () => NOOP_SPAN_HANDLE,
+	recordOutputChunk: () => {},
 	end: () => {}
 };
 //#endregion
@@ -456,6 +601,7 @@ function createSpanHandle(core, name, options = {}) {
 	if (options.name) span.updateName(options.name);
 	if (options.error !== void 0) applyError(span, options.error);
 	const spanContext = span.spanContext();
+	let previousOutputChunkTime;
 	const flags = (spanContext.traceFlags & 255).toString(16).padStart(2, "0");
 	const handle = {
 		span,
@@ -474,6 +620,28 @@ function createSpanHandle(core, name, options = {}) {
 			}
 			return handle;
 		},
+		recordOutputChunk(timestampMs) {
+			const now = timestampMs ?? performance.now();
+			if (!span.isRecording() || !Number.isFinite(now) || previousOutputChunkTime !== void 0 && now < previousOutputChunkTime) return;
+			if (previousOutputChunkTime !== void 0) {
+				const seconds = Math.max(0, now - previousOutputChunkTime) / 1e3;
+				const target = span;
+				const histogram = target[OUTPUT_CHUNK_HISTOGRAM] ??= {
+					count: 0,
+					sum: 0,
+					min: seconds,
+					max: seconds,
+					bucketCounts: Array.from({ length: DURATION_BUCKETS.length + 1 }, () => 0)
+				};
+				histogram.count++;
+				histogram.sum += seconds;
+				histogram.min = Math.min(histogram.min, seconds);
+				histogram.max = Math.max(histogram.max, seconds);
+				const bucket = DURATION_BUCKETS.findIndex((boundary) => seconds <= boundary);
+				histogram.bucketCounts[bucket < 0 ? DURATION_BUCKETS.length : bucket]++;
+			}
+			previousOutputChunkTime = now;
+		},
 		end(fields) {
 			try {
 				if (fields) applyFields(span, meta, fields);
@@ -543,7 +711,9 @@ function injectW3cContext(context, carrier, options = {}) {
 	const propagator = options.includeBaggage === true ? W3C_PROPAGATOR : TRACE_CONTEXT_PROPAGATOR;
 	for (const key of Object.keys(carrier)) {
 		const normalized = key.toLowerCase();
-		if (normalized === "traceparent" || normalized === "tracestate" || normalized === "baggage") delete carrier[key];
+		if (normalized === "traceparent" || normalized === "tracestate" || normalized === "baggage") {
+			if (!Reflect.deleteProperty(carrier, key)) throw new TypeError(`Cannot delete stale W3C carrier property: ${key}`);
+		}
 	}
 	propagator.inject(context, carrier, defaultTextMapSetter);
 }
@@ -599,4 +769,4 @@ function observe(fn, options) {
 	return wrapped;
 }
 //#endregion
-export { SCOPE_NAME, TelemetrySpanProcessor, activeContext, extractW3cContext, flush, getTraceparent, init, injectW3cContext, log, observe, propagateAttributes, shutdown, startActiveSpan, startSpan, updateActiveSpan, withContext };
+export { SCOPE_NAME, TelemetrySpanProcessor, activeContext, boundedCapture, boundedCaptureDetails, captureEnabled, extractW3cContext, flush, getTraceparent, init, injectW3cContext, log, observe, propagateAttributes, shutdown, startActiveSpan, startSpan, updateActiveSpan, withContext };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telemetry-dev/sdk",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "description": "Pure TypeScript SDK for telemetry.dev: LLM traces, logs, and GenAI metrics on OpenTelemetry, for Node and edge runtimes.",
   "keywords": [
     "genai",
@@ -16,7 +16,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/telemetry-dev/sdks.git",
+    "url": "git+https://github.com/telemetry-dev/telemetry.git",
     "directory": "packages/sdk"
   },
   "files": [
@@ -42,7 +42,7 @@
     "@opentelemetry/sdk-logs": "^0.218.0",
     "@opentelemetry/sdk-metrics": "^2.7.1",
     "@opentelemetry/sdk-trace-base": "^2.7.1",
-    "@telemetry-dev/otel": "^0.1.3"
+    "@telemetry-dev/otel": "^0.1.5"
   },
   "devDependencies": {
     "@opentelemetry/api": "^1.9.1",

package/src/attrs.ts

@@ -32,6 +32,15 @@ export interface TokenUsage {
   cacheReadInputTokens?: number;
   cacheCreationInputTokens?: number;
   reasoningOutputTokens?: number;
+  textInputTokens?: number;
+  textOutputTokens?: number;
+  textCacheReadInputTokens?: number;
+  imageInputTokens?: number;
+  imageOutputTokens?: number;
+  imageCacheReadInputTokens?: number;
+  audioInputTokens?: number;
+  audioOutputTokens?: number;
+  audioCacheReadInputTokens?: number;
 }
 
 export interface GenerationFields {
@@ -103,6 +112,15 @@ export function fieldsToAttributes(
     "gen_ai.usage.cache_read.input_tokens": fields.usage?.cacheReadInputTokens,
     "gen_ai.usage.cache_creation.input_tokens": fields.usage?.cacheCreationInputTokens,
     "gen_ai.usage.reasoning.output_tokens": fields.usage?.reasoningOutputTokens,
+    "gen_ai.usage.text.input_tokens": fields.usage?.textInputTokens,
+    "gen_ai.usage.text.output_tokens": fields.usage?.textOutputTokens,
+    "gen_ai.usage.text.cache_read.input_tokens": fields.usage?.textCacheReadInputTokens,
+    "gen_ai.usage.image.input_tokens": fields.usage?.imageInputTokens,
+    "gen_ai.usage.image.output_tokens": fields.usage?.imageOutputTokens,
+    "gen_ai.usage.image.cache_read.input_tokens": fields.usage?.imageCacheReadInputTokens,
+    "gen_ai.usage.audio.input_tokens": fields.usage?.audioInputTokens,
+    "gen_ai.usage.audio.output_tokens": fields.usage?.audioOutputTokens,
+    "gen_ai.usage.audio.cache_read.input_tokens": fields.usage?.audioCacheReadInputTokens,
     "gen_ai.usage.cost": fields.costUsd,
     "gen_ai.response.finish_reasons": fields.finishReason ? [fields.finishReason] : undefined,
     "gen_ai.output.type": fields.outputType,
@@ -126,32 +144,42 @@ export function fieldsToAttributes(
 
   if (fields.systemInstructions !== undefined && cfg.captureInput) {
     const value = prepareCaptureValue("gen_ai.system_instructions", fields.systemInstructions, cfg);
+
     if (value !== undefined) attrs["gen_ai.system_instructions"] = value;
   }
+
   if (fields.input !== undefined && cfg.captureInput) {
     const key = inputKeyFor(type);
     const value = prepareCaptureValue(key, fields.input, cfg);
+
     if (value !== undefined) attrs[key] = value;
   }
+
   if (fields.output !== undefined && cfg.captureOutput) {
     const key = outputKeyFor(type);
     const value = prepareCaptureValue(key, fields.output, cfg);
+
     if (value !== undefined) attrs[key] = value;
   }
+
   if (fields.metadata) {
     for (const [key, value] of Object.entries(fields.metadata)) {
       if (RESERVED_METADATA_KEYS.has(key)) {
         diag.debug(`metadata key "${key}" is reserved; pass it via propagateAttributes instead`);
         continue;
       }
+
       const attr = typeof value === "string" ? value : jsonAttr(value);
+
       if (attr !== undefined) {
         attrs[`td.metadata.${key}`] = truncate(attr, cfg.maxAttributeLength);
       }
     }
   }
+
   if (fields.attributes) {
     Object.assign(attrs, omitUndefined(fields.attributes));
   }
+
   return attrs;
 }

package/src/capture.ts

@@ -11,8 +11,238 @@ export interface CaptureConfig {
   onError?: (cause: Error) => void;
 }
 
+export interface BoundedCaptureOptions {
+  maxBytes?: number;
+  maxDepth?: number;
+  maxItems?: number;
+  skip?: (key: string, value: unknown, parent: unknown, path: readonly string[]) => boolean;
+}
+
+export interface BoundedCaptureResult {
+  value: unknown;
+  truncated: boolean;
+}
+
+export interface BoundedCaptureDetails extends BoundedCaptureResult {
+  bytes: number;
+  items: number;
+}
+
+interface CapturedObject {
+  [key: string]: CapturedValue;
+}
+
+type CapturedValue = null | boolean | number | string | CapturedValue[] | CapturedObject;
+
+const jsonStringByteLength = (value: string, limit: number) => {
+  let bytes = 2;
+
+  for (let index = 0; index < value.length && bytes <= limit; index += 1) {
+    const code = value.charCodeAt(index);
+
+    if (
+      code === 0x22 ||
+      code === 0x5c ||
+      code === 0x08 ||
+      code === 0x09 ||
+      code === 0x0a ||
+      code === 0x0c ||
+      code === 0x0d
+    ) {
+      bytes += 2;
+    } else if (code < 0x20) {
+      bytes += 6;
+    } else if (code < 0x80) {
+      bytes += 1;
+    } else if (code < 0x800) {
+      bytes += 2;
+    } else if (code >= 0xd800 && code <= 0xdbff) {
+      const next = value.charCodeAt(index + 1);
+
+      if (next >= 0xdc00 && next <= 0xdfff) {
+        bytes += 4;
+        index += 1;
+      } else {
+        bytes += 6;
+      }
+    } else if (code >= 0xdc00 && code <= 0xdfff) {
+      bytes += 6;
+    } else {
+      bytes += 3;
+    }
+  }
+
+  return bytes;
+};
+
+const captureLimit = (name: string, value: number | undefined, fallback: number) => {
+  if (value === undefined) return fallback;
+
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new RangeError(`${name} must be a non-negative safe integer`);
+  }
+
+  return value;
+};
+
+export function boundedCaptureDetails(
+  input: unknown,
+  options: BoundedCaptureOptions = {},
+): BoundedCaptureDetails {
+  const maxBytes = captureLimit("maxBytes", options.maxBytes, 48 * 1024);
+  const maxDepth = captureLimit("maxDepth", options.maxDepth, 32);
+  const maxItems = captureLimit("maxItems", options.maxItems, 1_000);
+  const ancestors = new WeakSet<object>();
+  let bytes = 0;
+  let items = 0;
+  let truncated = false;
+
+  const visit = (
+    value: unknown,
+    depth: number,
+    path: readonly string[],
+  ): CapturedValue | undefined => {
+    if (items >= maxItems) {
+      truncated = true;
+
+      return undefined;
+    }
+
+    items += 1;
+
+    if (
+      value === null ||
+      typeof value === "boolean" ||
+      typeof value === "number" ||
+      typeof value === "string"
+    ) {
+      const length =
+        typeof value === "string"
+          ? jsonStringByteLength(value, maxBytes - bytes)
+          : (JSON.stringify(value)?.length ?? 0);
+
+      if (bytes + length > maxBytes) {
+        truncated = true;
+
+        return undefined;
+      }
+
+      bytes += length;
+
+      return value;
+    }
+
+    if (typeof value !== "object") return undefined;
+
+    if (depth >= maxDepth || ancestors.has(value) || bytes + 2 > maxBytes) {
+      truncated = true;
+
+      return undefined;
+    }
+
+    ancestors.add(value);
+    bytes += 2;
+
+    try {
+      if (Array.isArray(value)) {
+        const result: CapturedValue[] = [];
+
+        for (const item of value) {
+          if (items >= maxItems) {
+            truncated = true;
+            break;
+          }
+
+          const previousBytes = bytes;
+
+          if (result.length > 0) bytes += 1;
+          const converted = visit(item, depth + 1, path);
+
+          if (converted === undefined) {
+            bytes = previousBytes;
+          } else {
+            result.push(converted);
+          }
+        }
+
+        return result;
+      }
+
+      const result: CapturedObject = {};
+      let emitted = false;
+
+      for (const key in value) {
+        if (items >= maxItems) {
+          truncated = true;
+          break;
+        }
+
+        if (!Object.hasOwn(value, key)) {
+          items += 1;
+          continue;
+        }
+
+        const keyBytes = jsonStringByteLength(key, maxBytes - bytes) + 1 + (emitted ? 1 : 0);
+
+        if (bytes + keyBytes > maxBytes) {
+          items += 1;
+          truncated = true;
+          continue;
+        }
+
+        let item: unknown;
+
+        try {
+          const descriptor = Object.getOwnPropertyDescriptor(value, key);
+          item = descriptor?.get ? descriptor.get.call(value) : descriptor?.value;
+
+          if (options.skip?.(key, item, value, path)) {
+            items += 1;
+            continue;
+          }
+        } catch {
+          items += 1;
+          truncated = true;
+          continue;
+        }
+
+        const previousBytes = bytes;
+        bytes += keyBytes;
+        const converted = visit(item, depth + 1, [...path, key]);
+
+        if (converted === undefined) {
+          bytes = previousBytes;
+        } else {
+          result[key] = converted;
+          emitted = true;
+        }
+      }
+
+      return result;
+    } catch {
+      truncated = true;
+
+      return undefined;
+    } finally {
+      ancestors.delete(value);
+    }
+  };
+
+  return { value: visit(input, 0, []), truncated, bytes, items };
+}
+
+export function boundedCapture(
+  input: unknown,
+  options: BoundedCaptureOptions = {},
+): BoundedCaptureResult {
+  const { value, truncated } = boundedCaptureDetails(input, options);
+
+  return { value, truncated };
+}
+
 export function truncate(value: string, maxLength: number): string {
   if (value.length <= maxLength) return value;
+
   // Total stays within maxLength so the provider's attributeValueLengthLimit backstop
   // (set to the same cap) never slices the marker off.
   return value.slice(0, Math.max(maxLength - TRUNCATION_MARKER.length, 0)) + TRUNCATION_MARKER;
@@ -25,15 +255,20 @@ export function prepareCaptureValue(
   cfg: CaptureConfig,
 ): string | undefined {
   let masked = value;
+
   if (cfg.mask) {
     try {
       masked = cfg.mask(value, { key });
     } catch (error) {
       reportError(cfg.onError, error instanceof Error ? error : new Error(String(error)));
+
       return undefined;
     }
   }
+
   const serialized = jsonAttr(masked);
+
   if (serialized === undefined) return undefined;
+
   return truncate(serialized, cfg.maxAttributeLength);
 }

package/src/client.ts

@@ -75,6 +75,12 @@ export function currentClient(): ClientHandle {
   return activeClient ?? NOOP_CLIENT;
 }
 
+export function captureEnabled(kind: "input" | "output"): boolean {
+  const config = currentClient().core?.config;
+
+  return kind === "input" ? (config?.captureInput ?? false) : (config?.captureOutput ?? false);
+}
+
 export function flush(): Promise<void> {
   return currentClient().flush();
 }
@@ -89,6 +95,7 @@ export function init(options?: TelemetryOptions, overrides?: ClientOverrides): T
   } catch (error) {
     reportError(options?.onError, error instanceof Error ? error : new Error(String(error)));
     activeClient = NOOP_CLIENT;
+
     return NOOP_CLIENT;
   }
 }
@@ -104,11 +111,14 @@ function initInner(options?: TelemetryOptions, overrides?: ClientOverrides): Tel
   }
 
   const enabled = config.enabled && Boolean(config.apiKey ?? overrides?.spanExporter);
+
   if (!enabled) {
     if (config.enabled && !config.apiKey) {
       diag.debug("no api key (apiKey option or TELEMETRY_DEV_API_KEY); telemetry disabled");
     }
+
     activeClient = NOOP_CLIENT;
+
     return NOOP_CLIENT;
   }
 
@@ -119,6 +129,7 @@ function initInner(options?: TelemetryOptions, overrides?: ClientOverrides): Tel
     "deployment.environment.name": config.environment,
     ...config.resourceAttributes,
   });
+
   const transport: Transport = { fetchImpl: config.fetchImpl, onError: config.onError };
   const headers = config.apiKey ? otlpHeaders(config.apiKey, config.sdkName) : undefined;
 
@@ -131,6 +142,7 @@ function initInner(options?: TelemetryOptions, overrides?: ClientOverrides): Tel
     (headers
       ? createMetricExporter({ url: `${config.baseUrl}/v1/metrics`, headers }, transport)
       : undefined);
+
   const metrics = metricExporter
     ? createMetricsPipeline({
         resource,
@@ -161,21 +173,26 @@ function initInner(options?: TelemetryOptions, overrides?: ClientOverrides): Tel
     spanProcessors: [processor],
     spanLimits: { attributeValueLengthLimit: config.maxAttributeLength },
   });
+
   const tracer = provider.getTracer(SCOPE_NAME, SCOPE_VERSION);
 
   let registeredTrace = false;
   let registeredContext = false;
   let registeredPropagation = false;
+
   if (config.registerGlobal) {
     registeredTrace = trace.setGlobalTracerProvider(
       config.sessionRootOf
         ? sessionRootTracerProvider(provider, config.apiKey, config.sessionRootOf, config.onError)
         : provider,
     );
+
     if (als) {
       registeredContext = apiContext.setGlobalContextManager(new AlsContextManager(als));
     }
+
     registeredPropagation = propagation.setGlobalPropagator(new W3CTraceContextPropagator());
+
     if (!registeredTrace) {
       diag.warn(
         "a global TracerProvider is already registered; attach the TelemetrySpanProcessor from '@telemetry-dev/otel' to your own provider instead",
@@ -188,43 +205,56 @@ function initInner(options?: TelemetryOptions, overrides?: ClientOverrides): Tel
     (headers
       ? createLogExporter({ url: `${config.baseUrl}/v1/logs`, headers }, transport)
       : undefined);
+
   // Lazy: the log pipeline only exists once log() is first called.
   let logs: { logger: Logger; forceFlush(): Promise<void>; shutdown(): Promise<void> } | undefined;
+
   const ensureLogger = (): Logger | undefined => {
     if (!logExporter) return undefined;
+
     if (!logs) {
       const logProcessor =
         config.exportMode === "immediate"
           ? new SimpleLogRecordProcessor(logExporter)
           : new BatchLogRecordProcessor(logExporter);
+
       const loggerProvider = new LoggerProvider({
         resource,
         logRecordLimits: { attributeValueLengthLimit: config.maxAttributeLength },
         processors: [logProcessor],
       });
+
       logs = {
         logger: loggerProvider.getLogger(SCOPE_NAME, SCOPE_VERSION),
         forceFlush: () => loggerProvider.forceFlush(),
         shutdown: () => loggerProvider.shutdown(),
       };
     }
+
     return logs.logger;
   };
 
   let torn = false;
+
   const collect = (op: "forceFlush" | "shutdown"): Promise<void> => {
     const parts: Promise<void>[] = [provider[op]()];
+
     if (logs) parts.push(logs[op]());
+
     if (metrics) parts.push(metrics[op]());
+
     return Promise.all(parts)
       .then(() => undefined)
       .catch((error: Error) => reportError(config.onError, error));
   };
+
   const handoff = (p: Promise<void>): Promise<void> => {
     if (config.waitUntil) {
       config.waitUntil(p);
+
       return Promise.resolve();
     }
+
     return p;
   };
 
@@ -236,14 +266,20 @@ function initInner(options?: TelemetryOptions, overrides?: ClientOverrides): Tel
     shutdown: () => {
       if (torn) return Promise.resolve();
       torn = true;
+
       if (registeredTrace) trace.disable();
+
       if (registeredContext) apiContext.disable();
+
       if (registeredPropagation) propagation.disable();
       handle.core = undefined;
+
       return handoff(collect("shutdown"));
     },
   };
+
   handle.core = { config, tracer, ensureLogger };
   activeClient = handle;
+
   return handle;
 }

package/src/config.ts

@@ -95,6 +95,7 @@ export const DEFAULT_MAX_ATTRIBUTE_LENGTH = 65536;
 
 export function resolveConfig(options: TelemetryOptions = {}): ResolvedConfig {
   const env = resolveEnv();
+
   if (
     options.sessionMode !== undefined &&
     options.sessionMode !== "explicit" &&
@@ -102,10 +103,12 @@ export function resolveConfig(options: TelemetryOptions = {}): ResolvedConfig {
   ) {
     throw new TypeError(`Invalid sessionMode: ${String(options.sessionMode)}`);
   }
+
   const baseUrl = (options.baseUrl ?? env.TELEMETRY_DEV_BASE_URL ?? DEFAULT_BASE_URL).replace(
     /\/+$/,
     "",
   );
+
   return {
     apiKey: options.apiKey ?? env.TELEMETRY_DEV_API_KEY,
     baseUrl,

package/src/index.ts

@@ -6,7 +6,16 @@ export type {
   TokenUsage,
   ToolFields,
 } from "./attrs.ts";
-export { type ClientOverrides, flush, init, shutdown, type TelemetryClient } from "./client.ts";
+
+export {
+  captureEnabled,
+  type ClientOverrides,
+  flush,
+  init,
+  shutdown,
+  type TelemetryClient,
+} from "./client.ts";
+
 export type {
   BatchOptions,
   ExportMode,
@@ -15,6 +24,15 @@ export type {
   SdkLogLevel,
   TelemetryOptions,
 } from "./config.ts";
+
+export {
+  boundedCapture,
+  boundedCaptureDetails,
+  type BoundedCaptureDetails,
+  type BoundedCaptureOptions,
+  type BoundedCaptureResult,
+} from "./capture.ts";
+
 export {
   propagateAttributes,
   type PropagatedAttributes,
@@ -22,8 +40,11 @@ export {
   TelemetrySpanProcessor,
   type TelemetrySpanProcessorOptions,
 } from "@telemetry-dev/otel";
+
 export { log, type LogOptions } from "./logs.ts";
+
 export { observe, type ObserveOptions } from "./observe.ts";
+
 export {
   activeContext,
   extractW3cContext,

package/src/logs.ts

@@ -34,26 +34,33 @@ export interface LogOptions {
  */
 export function log(message: string, options?: LogOptions): void {
   const core = currentClient().core;
+
   if (!core) return;
+
   try {
     const logger = core.ensureLogger();
+
     if (!logger) return;
     const cfg = core.config;
+
     const captureCfg = {
       mask: cfg.mask,
       maxAttributeLength: cfg.maxAttributeLength,
       onError: cfg.onError,
     };
+
     const severity = SEVERITIES[options?.level ?? "info"];
     const active = activeContext();
     const explicitSession = options?.attributes?.["gen_ai.conversation.id"];
     const propagatedSession = propagatedFromContext(active)?.["gen_ai.conversation.id"];
+
     const sessionId =
       explicitSession !== undefined
         ? undefined
         : typeof propagatedSession === "string"
           ? propagatedSession
           : cfg.processSessionId;
+
     const ctx =
       sessionId === undefined
         ? active
@@ -63,16 +70,22 @@ export function log(message: string, options?: LogOptions): void {
           });
 
     const attributes: Record<string, AttributeValue> = {};
+
     for (const [key, value] of Object.entries(options?.attributes ?? {})) {
       if (value === undefined) continue;
+
       if (typeof value === "number" || typeof value === "boolean") {
         attributes[key] = value;
         continue;
       }
+
       const prepared = prepareCaptureValue(key, value, captureCfg);
+
       if (prepared !== undefined) attributes[key] = prepared;
     }
+
     const propagated = propagatedFromContext(ctx);
+
     if (propagated) {
       for (const [key, value] of Object.entries(propagated)) {
         if (value !== undefined) {

package/src/noop.ts

@@ -13,5 +13,6 @@ export const NOOP_SPAN_HANDLE: SpanHandle = {
   traceparent: null,
   isRecording: false,
   update: () => NOOP_SPAN_HANDLE,
+  recordOutputChunk: () => {},
   end: () => {},
 };

package/src/observe.ts

@@ -19,11 +19,14 @@ export function observe<TThis, TArgs extends unknown[], TReturn>(
 ): (...args: TArgs) => TReturn {
   const wrapped = function (this: TThis, ...args: TArgs): TReturn {
     const core = currentClient().core;
+
     if (!core) return fn.apply(this, args);
 
     let handle: SpanHandle;
+
     try {
       const name = options?.name ?? (fn.name || "anonymous");
+
       const input =
         options?.input !== undefined
           ? options.input
@@ -32,18 +35,22 @@ export function observe<TThis, TArgs extends unknown[], TReturn>(
             : args.length === 1
               ? args[0]
               : args;
+
       handle = createSpanHandle(core, name, { ...options, input });
     } catch (error) {
       reportError(core.config.onError, error instanceof Error ? error : new Error(String(error)));
+
       return fn.apply(this, args);
     }
 
     try {
       const result = withContext(handle.context, () => fn.apply(this, args));
+
       if (isThenable(result)) {
         return result.then(
           (value) => {
             handle.end({ output: value });
+
             return value;
           },
           (error: Error) => {
@@ -52,13 +59,17 @@ export function observe<TThis, TArgs extends unknown[], TReturn>(
           },
         ) as TReturn;
       }
+
       handle.end({ output: result });
+
       return result;
     } catch (error) {
       handle.end({ error: error instanceof Error ? error : new Error(String(error)) });
       throw error;
     }
   };
+
   Object.defineProperty(wrapped, "name", { value: fn.name || "anonymous", configurable: true });
+
   return wrapped;
 }

package/src/span.ts

@@ -19,7 +19,10 @@ import {
 
 import {
   activeContext,
+  DURATION_BUCKETS,
   omitUndefined,
+  OUTPUT_CHUNK_HISTOGRAM,
+  type OutputChunkHistogram,
   PROPAGATED_KEY,
   propagatedFromContext,
   reportError,
@@ -67,6 +70,8 @@ export interface SpanHandle {
   readonly traceparent: string | null;
   readonly isRecording: boolean;
   update(fields: SpanFields): SpanHandle;
+  /** Records an output chunk arrival. Pull-based streams include consumer delay between pulls. */
+  recordOutputChunk(timestampMs?: number): void;
   end(fields?: SpanFields & { endTime?: Date | number }): void;
 }
 
@@ -104,25 +109,35 @@ function isSpanHandle(value: Exclude<ParentRef, string>): value is SpanHandle {
 function withAmbientPropagated(ctx: Context): Context {
   if (propagatedFromContext(ctx)) return ctx;
   const ambient = propagatedFromContext(activeContext());
+
   return ambient ? ctx.setValue(PROPAGATED_KEY, ambient) : ctx;
 }
 
 function resolveParent(parent: ParentRef | undefined): Context {
   const base = activeContext();
+
   if (parent === undefined) return base;
+
   if (typeof parent === "string") {
     const parsed = parseTraceParent(parent);
+
     if (!parsed) return base;
+
     return trace.setSpanContext(base, { ...parsed, isRemote: true });
   }
+
   const ref = parent as Exclude<ParentRef, string>;
+
   if (isSpanHandle(ref)) return withAmbientPropagated(ref.context);
+
   if (isContext(ref)) return withAmbientPropagated(ref);
+
   return trace.setSpanContext(base, ref);
 }
 
 function applyError(span: Span, error: unknown): void {
   const err = error instanceof Error ? error : undefined;
+
   // Prefer the specific subclass name (Python parity: type(error).__name__) — many SDK
   // error classes (e.g. openai's BadRequestError) never override the inherited "Error" name.
   const errorType =
@@ -131,6 +146,7 @@ function applyError(span: Span, error: unknown): void {
       : err.name !== "Error" && err.name.length > 0
         ? err.name
         : (err.constructor?.name ?? "Error") || "Error";
+
   const message = err?.message ?? String(error);
   span.setStatus({ code: SpanStatusCode.ERROR });
   span.setAttribute("error.type", errorType);
@@ -148,12 +164,15 @@ function applyError(span: Span, error: unknown): void {
 function applyFields(span: Span, meta: SpanMeta, fields: SpanFields): void {
   if (fields.name) span.updateName(fields.name);
   const attrs = fieldsToAttributes(fields, meta.type, meta.capture);
+
   if (Object.keys(attrs).length > 0) span.setAttributes(attrs);
+
   if (fields.error !== undefined) applyError(span, fields.error);
 }
 
 function metaFor(core: ClientCore, options?: StartSpanOptions): SpanMeta {
   const cfg = core.config;
+
   return {
     type: options?.type ?? "span",
     capture: {
@@ -175,6 +194,7 @@ export function createSpanHandle(
   const meta = metaFor(core, options);
   const resolved = resolveParent(options.parent);
   const sessionId = sessionIdOf(resolved, options.attributes) ?? core.config.processSessionId;
+
   const sessionContext =
     sessionId === undefined
       ? resolved
@@ -182,8 +202,10 @@ export function createSpanHandle(
           ...propagatedFromContext(resolved),
           "gen_ai.conversation.id": sessionId,
         });
+
   const parentCtx = withSessionParent(sessionContext, sessionId, core.config.apiKey);
   const attrs = fieldsToAttributes(options, meta.type, meta.capture);
+
   const span = core.tracer.startSpan(
     name,
     {
@@ -198,14 +220,20 @@ export function createSpanHandle(
     },
     parentCtx,
   );
+
   SPAN_META.set(span, meta);
+
   // The processor stamps propagation on start; explicit fields still win.
   if (Object.keys(attrs).length > 0) span.setAttributes(attrs);
+
   if (options.name) span.updateName(options.name);
+
   if (options.error !== undefined) applyError(span, options.error);
 
   const spanContext = span.spanContext();
+  let previousOutputChunkTime: number | undefined;
   const flags = (spanContext.traceFlags & 0xff).toString(16).padStart(2, "0");
+
   const handle: SpanHandle = {
     span,
     context: trace.setSpan(parentCtx, span),
@@ -221,28 +249,69 @@ export function createSpanHandle(
       } catch (error) {
         reportError(meta.onError, error instanceof Error ? error : new Error(String(error)));
       }
+
       return handle;
     },
+    recordOutputChunk(timestampMs) {
+      const now = timestampMs ?? performance.now();
+
+      if (
+        !span.isRecording() ||
+        !Number.isFinite(now) ||
+        (previousOutputChunkTime !== undefined && now < previousOutputChunkTime)
+      )
+        return;
+
+      if (previousOutputChunkTime !== undefined) {
+        const seconds = Math.max(0, now - previousOutputChunkTime) / 1000;
+
+        const target = span as Span & {
+          [OUTPUT_CHUNK_HISTOGRAM]?: OutputChunkHistogram;
+        };
+
+        const histogram = (target[OUTPUT_CHUNK_HISTOGRAM] ??= {
+          count: 0,
+          sum: 0,
+          min: seconds,
+          max: seconds,
+          bucketCounts: Array.from({ length: DURATION_BUCKETS.length + 1 }, () => 0),
+        });
+
+        histogram.count++;
+        histogram.sum += seconds;
+        histogram.min = Math.min(histogram.min, seconds);
+        histogram.max = Math.max(histogram.max, seconds);
+        const bucket = DURATION_BUCKETS.findIndex((boundary) => seconds <= boundary);
+        histogram.bucketCounts[bucket < 0 ? DURATION_BUCKETS.length : bucket]++;
+      }
+
+      previousOutputChunkTime = now;
+    },
     end(fields) {
       try {
         if (fields) applyFields(span, meta, fields);
       } catch (error) {
         reportError(meta.onError, error instanceof Error ? error : new Error(String(error)));
       }
+
       span.end(fields?.endTime);
     },
   };
+
   return handle;
 }
 
 /** Start a span WITHOUT activating context; the caller must call .end(). */
 export function startSpan(name: string, options?: StartSpanOptions): SpanHandle {
   const core = currentClient().core;
+
   if (!core) return NOOP_SPAN_HANDLE;
+
   try {
     return createSpanHandle(core, name, options);
   } catch (error) {
     reportError(core.config.onError, error instanceof Error ? error : new Error(String(error)));
+
     return NOOP_SPAN_HANDLE;
   }
 }
@@ -250,10 +319,12 @@ export function startSpan(name: string, options?: StartSpanOptions): SpanHandle
 export function runWithHandle<T>(handle: SpanHandle, fn: (span: SpanHandle) => T): T {
   try {
     const result = withContext(handle.context, () => fn(handle));
+
     if (isThenable(result)) {
       return result.then(
         (value) => {
           handle.end();
+
           return value;
         },
         (error: unknown) => {
@@ -262,7 +333,9 @@ export function runWithHandle<T>(handle: SpanHandle, fn: (span: SpanHandle) => T
         },
       ) as T;
     }
+
     handle.end();
+
     return result;
   } catch (error) {
     handle.end({ error });
@@ -285,16 +358,21 @@ export function startActiveSpan<T>(
   const fn = isFn ? optionsOrFn : maybeFn!;
   const options = isFn ? undefined : optionsOrFn;
   const handle = startSpan(name, options);
+
   if (handle === NOOP_SPAN_HANDLE) return fn(handle);
+
   return runWithHandle(handle, fn);
 }
 
 /** Update the innermost active span; no-op when none is recording. */
 export function updateActiveSpan(fields: SpanFields): void {
   const core = currentClient().core;
+
   if (!core) return;
+
   try {
     const span = trace.getSpan(activeContext());
+
     if (!span?.isRecording()) return;
     const meta = SPAN_META.get(span) ?? metaFor(core);
     applyFields(span, meta, fields);
@@ -304,6 +382,7 @@ export function updateActiveSpan(fields: SpanFields): void {
 }
 
 const TRACE_CONTEXT_PROPAGATOR = new W3CTraceContextPropagator();
+
 const W3C_PROPAGATOR = new CompositePropagator({
   propagators: [TRACE_CONTEXT_PROPAGATOR, new W3CBaggagePropagator()],
 });
@@ -316,6 +395,7 @@ export function extractW3cContext(
   options: { includeBaggage?: boolean } = {},
 ): Context {
   const propagator = options.includeBaggage === true ? W3C_PROPAGATOR : TRACE_CONTEXT_PROPAGATOR;
+
   return propagator.extract(ROOT_CONTEXT, carrier, defaultTextMapGetter);
 }
 
@@ -326,12 +406,17 @@ export function injectW3cContext(
   options: { includeBaggage?: boolean } = {},
 ): void {
   const propagator = options.includeBaggage === true ? W3C_PROPAGATOR : TRACE_CONTEXT_PROPAGATOR;
+
   for (const key of Object.keys(carrier)) {
     const normalized = key.toLowerCase();
+
     if (normalized === "traceparent" || normalized === "tracestate" || normalized === "baggage") {
-      delete carrier[key];
+      if (!Reflect.deleteProperty(carrier, key)) {
+        throw new TypeError(`Cannot delete stale W3C carrier property: ${key}`);
+      }
     }
   }
+
   propagator.inject(context, carrier, defaultTextMapSetter);
 }
 
@@ -339,5 +424,6 @@ export function injectW3cContext(
 export function getTraceparent(): string | null {
   const carrier = { traceparent: undefined };
   TRACE_CONTEXT_PROPAGATOR.inject(activeContext(), carrier, defaultTextMapSetter);
+
   return carrier.traceparent ?? null;
 }