@telemetry-dev/sdk 0.1.3 → 0.1.5

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`,
@@ -99,6 +100,18 @@ GenAI semantic conventions; cost is computed server-side from usage unless `cost
 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

@@ -172,6 +172,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;

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();
@@ -363,6 +363,7 @@ const NOOP_SPAN_HANDLE = {
 	traceparent: null,
 	isRecording: false,
 	update: () => NOOP_SPAN_HANDLE,
+	recordOutputChunk: () => {},
 	end: () => {}
 };
 //#endregion
@@ -456,6 +457,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 +476,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 +567,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);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telemetry-dev/sdk",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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

@@ -126,32 +126,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

@@ -13,6 +13,7 @@ export interface CaptureConfig {
 
 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 +26,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

@@ -89,6 +89,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 +105,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 +123,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 +136,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 +167,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 +199,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 +260,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,9 @@ export type {
   TokenUsage,
   ToolFields,
 } from "./attrs.ts";
+
 export { type ClientOverrides, flush, init, shutdown, type TelemetryClient } from "./client.ts";
+
 export type {
   BatchOptions,
   ExportMode,
@@ -15,6 +17,7 @@ export type {
   SdkLogLevel,
   TelemetryOptions,
 } from "./config.ts";
+
 export {
   propagateAttributes,
   type PropagatedAttributes,
@@ -22,8 +25,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;
 }