@telemetry-dev/sdk 0.1.2 → 0.1.5

package/README.md

@@ -60,6 +60,12 @@ Other `init()` options: `enabled` (kill switch), `registerGlobal`, `exportMode:
 `exportTimeoutMillis` 30000), `spanFilter`, `resourceAttributes`, `logLevel` (SDK diagnostics,
 default `"warn"`), `fetch`, `waitUntil`, `onError`.
 
+Root spans remain independent by default. `init({ sessionMode: "process" })` groups otherwise
+uncorrelated spans and logs using a fresh opaque UUID for each enabled SDK initialization.
+Explicit and propagated session IDs take precedence, and valid parent trace context is preserved.
+The generated session ends when the client is shut down or replaced; a later `init()` generates a
+new ID. It is not persisted across processes.
+
 `sampler` accepts an OpenTelemetry `Sampler` and overrides `OTEL_TRACES_SAMPLER` / `OTEL_TRACES_SAMPLER_ARG`.
 The default is parent-based always-on. Session roots keep the configured root policy.
 Nested spans and explicitly parented spans keep the real parent's policy.
@@ -71,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`,
@@ -93,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

@@ -20,6 +20,8 @@ interface TelemetryOptions {
   serviceName?: string;
   /** Kill switch: `false` makes the SDK a complete no-op (tests). Default true. */
   enabled?: boolean;
+  /** Group otherwise uncorrelated spans and logs for this SDK initialization. Default "explicit". */
+  sessionMode?: "explicit" | "process";
   /** Register this SDK's TracerProvider/context manager/propagator globally. Default false (isolated). */
   registerGlobal?: boolean;
   /** "batched" (default) buffers spans; "immediate" exports per span (serverless). */
@@ -170,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,10 +3,11 @@ 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();
+	if (options.sessionMode !== void 0 && options.sessionMode !== "explicit" && options.sessionMode !== "process") 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,
@@ -14,6 +15,7 @@ function resolveConfig(options = {}) {
 		environment: options.environment ?? env.TELEMETRY_DEV_ENVIRONMENT ?? "production",
 		serviceName: options.serviceName ?? env.OTEL_SERVICE_NAME ?? "unknown_service",
 		enabled: options.enabled ?? true,
+		sessionMode: options.sessionMode ?? "explicit",
 		registerGlobal: options.registerGlobal ?? false,
 		exportMode: options.exportMode ?? "batched",
 		sampler: options.sampler,
@@ -73,6 +75,7 @@ function initInner(options, overrides) {
 		activeClient = NOOP_CLIENT;
 		return NOOP_CLIENT;
 	}
+	if (config.sessionMode === "process") config.processSessionId = globalThis.crypto.randomUUID();
 	const resource = resourceFromAttributes({
 		"service.name": config.serviceName,
 		"deployment.environment.name": config.environment,
@@ -237,7 +240,14 @@ function log(message, options) {
 			onError: cfg.onError
 		};
 		const severity = SEVERITIES[options?.level ?? "info"];
-		const ctx = activeContext$1();
+		const active = activeContext$1();
+		const explicitSession = options?.attributes?.["gen_ai.conversation.id"];
+		const propagatedSession = propagatedFromContext(active)?.["gen_ai.conversation.id"];
+		const sessionId = explicitSession !== void 0 ? void 0 : typeof propagatedSession === "string" ? propagatedSession : cfg.processSessionId;
+		const ctx = sessionId === void 0 ? active : active.setValue(PROPAGATED_KEY, {
+			...propagatedFromContext(active),
+			"gen_ai.conversation.id": sessionId
+		});
 		const attributes = {};
 		for (const [key, value] of Object.entries(options?.attributes ?? {})) {
 			if (value === void 0) continue;
@@ -353,6 +363,7 @@ const NOOP_SPAN_HANDLE = {
 	traceparent: null,
 	isRecording: false,
 	update: () => NOOP_SPAN_HANDLE,
+	recordOutputChunk: () => {},
 	end: () => {}
 };
 //#endregion
@@ -425,7 +436,11 @@ function metaFor(core, options) {
 function createSpanHandle(core, name, options = {}) {
 	const meta = metaFor(core, options);
 	const resolved = resolveParent(options.parent);
-	const parentCtx = withSessionParent(resolved, sessionIdOf(resolved, options.attributes), core.config.apiKey);
+	const sessionId = sessionIdOf(resolved, options.attributes) ?? core.config.processSessionId;
+	const parentCtx = withSessionParent(sessionId === void 0 ? resolved : resolved.setValue(PROPAGATED_KEY, {
+		...propagatedFromContext(resolved),
+		"gen_ai.conversation.id": sessionId
+	}), sessionId, core.config.apiKey);
 	const attrs = fieldsToAttributes(options, meta.type, meta.capture);
 	const span = core.tracer.startSpan(name, {
 		kind: options.kind ?? SpanKind.INTERNAL,
@@ -442,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,
@@ -460,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);
@@ -529,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.2",
+  "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/telemetry.dev.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.2"
+    "@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,19 +105,25 @@ 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;
   }
 
+  if (config.sessionMode === "process") config.processSessionId = globalThis.crypto.randomUUID();
+
   const resource = resourceFromAttributes({
     "service.name": config.serviceName,
     "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;
 
@@ -129,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,
@@ -159,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",
@@ -186,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;
   };
 
@@ -234,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

@@ -26,6 +26,8 @@ export interface TelemetryOptions {
   serviceName?: string;
   /** Kill switch: `false` makes the SDK a complete no-op (tests). Default true. */
   enabled?: boolean;
+  /** Group otherwise uncorrelated spans and logs for this SDK initialization. Default "explicit". */
+  sessionMode?: "explicit" | "process";
   /** Register this SDK's TracerProvider/context manager/propagator globally. Default false (isolated). */
   registerGlobal?: boolean;
   /** "batched" (default) buffers spans; "immediate" exports per span (serverless). */
@@ -69,6 +71,8 @@ export interface ResolvedConfig {
   environment: string;
   serviceName: string;
   enabled: boolean;
+  sessionMode: "explicit" | "process";
+  processSessionId?: string;
   registerGlobal: boolean;
   exportMode: ExportMode;
   sampler?: Sampler;
@@ -91,16 +95,27 @@ export const DEFAULT_MAX_ATTRIBUTE_LENGTH = 65536;
 
 export function resolveConfig(options: TelemetryOptions = {}): ResolvedConfig {
   const env = resolveEnv();
+
+  if (
+    options.sessionMode !== undefined &&
+    options.sessionMode !== "explicit" &&
+    options.sessionMode !== "process"
+  ) {
+    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,
     environment: options.environment ?? env.TELEMETRY_DEV_ENVIRONMENT ?? "production",
     serviceName: options.serviceName ?? env.OTEL_SERVICE_NAME ?? "unknown_service",
     enabled: options.enabled ?? true,
+    sessionMode: options.sessionMode ?? "explicit",
     registerGlobal: options.registerGlobal ?? false,
     exportMode: options.exportMode ?? "batched",
     sampler: options.sampler,

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

@@ -1,7 +1,12 @@
 import type { AttributeValue } from "@opentelemetry/api";
 import { SeverityNumber } from "@opentelemetry/api-logs";
 
-import { activeContext, propagatedFromContext, reportError } from "@telemetry-dev/otel";
+import {
+  activeContext,
+  PROPAGATED_KEY,
+  propagatedFromContext,
+  reportError,
+} from "@telemetry-dev/otel";
 
 import { prepareCaptureValue, truncate } from "./capture.ts";
 import { currentClient } from "./client.ts";
@@ -29,30 +34,58 @@ 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 ctx = activeContext();
+    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
+        : active.setValue(PROPAGATED_KEY, {
+            ...propagatedFromContext(active),
+            "gen_ai.conversation.id": sessionId,
+          });
 
     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: {
@@ -174,12 +193,19 @@ export function createSpanHandle(
 ): SpanHandle {
   const meta = metaFor(core, options);
   const resolved = resolveParent(options.parent);
-  const parentCtx = withSessionParent(
-    resolved,
-    sessionIdOf(resolved, options.attributes),
-    core.config.apiKey,
-  );
+  const sessionId = sessionIdOf(resolved, options.attributes) ?? core.config.processSessionId;
+
+  const sessionContext =
+    sessionId === undefined
+      ? resolved
+      : resolved.setValue(PROPAGATED_KEY, {
+          ...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,
     {
@@ -194,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),
@@ -217,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;
   }
 }
@@ -246,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) => {
@@ -258,7 +333,9 @@ export function runWithHandle<T>(handle: SpanHandle, fn: (span: SpanHandle) => T
         },
       ) as T;
     }
+
     handle.end();
+
     return result;
   } catch (error) {
     handle.end({ error });
@@ -281,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);
@@ -300,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()],
 });
@@ -312,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);
 }
 
@@ -322,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);
 }
 
@@ -335,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;
 }