@telemetry-dev/sdk 0.1.0 → 0.1.2

package/README.md

@@ -60,6 +60,11 @@ Other `init()` options: `enabled` (kill switch), `registerGlobal`, `exportMode:
 `exportTimeoutMillis` 30000), `spanFilter`, `resourceAttributes`, `logLevel` (SDK diagnostics,
 default `"warn"`), `fetch`, `waitUntil`, `onError`.
 
+`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.
+The SDK installs the [session sampling wrapper](../otel/README.md#correlation-attributes) on its provider. This includes the global provider that Eve uses.
+
 ## API
 
 - `init(options?)` — create the client (isolated OTel TracerProvider by default).
@@ -74,6 +79,10 @@ default `"warn"`), `fetch`, `waitUntil`, `onError`.
 - `log(message, { level, eventName, attributes }?)` — log record correlated to the active trace.
 - `getTraceparent()` — W3C traceparent of the active span (pass to other services; accept it via
   `startSpan(name, { parent })`).
+- `activeContext()` / `withContext(context, fn)` — read or temporarily activate an OpenTelemetry
+  context.
+- `extractW3cContext(carrier, options?)` / `injectW3cContext(context, carrier, options?)` — extract
+  or inject W3C trace context. Baggage is omitted unless `includeBaggage` is true.
 - `flush()` / `shutdown()` — export pending data; required before serverless freeze/exit.
 
 Span types: `span` (default) | `generation` | `tool` | `agent` | `embedding` — mapped to

package/dist/index.d.mts

@@ -1,14 +1,14 @@
-import { AttributeValue, Context, Span, SpanContext } from "@opentelemetry/api";
+import { AttributeValue, Context, Link, Span, SpanContext, SpanKind } from "@opentelemetry/api";
 import { LogRecordExporter } from "@opentelemetry/sdk-logs";
-import { ReadableSpan, SpanExporter } from "@opentelemetry/sdk-trace-base";
-import { BatchOptions, BatchOptions as BatchOptions$1, ExportMode, ExportMode as ExportMode$1, LogLevel, PropagatedAttributes, SdkLogLevel, SdkLogLevel as SdkLogLevel$1, propagateAttributes } from "@telemetry-dev/otel";
+import { ReadableSpan, Sampler, SpanExporter } from "@opentelemetry/sdk-trace-base";
+import { BatchOptions, BatchOptions as BatchOptions$1, ExportMode, ExportMode as ExportMode$1, LogLevel, PropagatedAttributes, SCOPE_NAME, SdkLogLevel, SdkLogLevel as SdkLogLevel$1, SessionRootOf, TelemetrySpanProcessor, TelemetrySpanProcessorOptions, activeContext, propagateAttributes, withContext } from "@telemetry-dev/otel";
 import { PushMetricExporter } from "@opentelemetry/sdk-metrics";
 
 //#region src/config.d.ts
 /** Redaction hook applied to captured content (input/output/log message) before JSON stringification. */
-type MaskFn = (value: unknown, ctx: {
+type MaskFn<T = unknown> = (value: T, ctx: {
   key: string;
-}) => unknown;
+}) => T;
 interface TelemetryOptions {
   /** telemetry.dev ingest key (`td_live_…`). Falls back to `TELEMETRY_DEV_API_KEY`. When absent the SDK is a no-op. */
   apiKey?: string;
@@ -24,6 +24,8 @@ interface TelemetryOptions {
   registerGlobal?: boolean;
   /** "batched" (default) buffers spans; "immediate" exports per span (serverless). */
   exportMode?: ExportMode$1;
+  /** OTel sampling policy. Defaults to OTEL_TRACES_SAMPLER / OTEL_TRACES_SAMPLER_ARG. */
+  sampler?: Sampler;
   /** Capture span inputs (args, prompts) by default. Default true. */
   captureInput?: boolean;
   /** Capture span outputs (results, completions) by default. Default true. */
@@ -35,6 +37,12 @@ interface TelemetryOptions {
   batch?: BatchOptions$1;
   /** Export filter. Default when registerGlobal: only spans from this SDK's instrumentation scope. */
   spanFilter?: (span: ReadableSpan) => boolean;
+  /**
+   * With registerGlobal: spans from other tracers that this returns a session id for are
+   * parented under the session trace even when a parent span is active. Use it for frameworks
+   * that start each turn inside their own engine span.
+   */
+  sessionRootOf?: SessionRootOf;
   /** Extra resource attributes merged onto service.name / deployment.environment.name. */
   resourceAttributes?: Record<string, AttributeValue>;
   /** SDK self-diagnostics console level. Default "warn"; "silent" disables. */
@@ -44,7 +52,9 @@ interface TelemetryOptions {
   /** Serverless extender (e.g. Cloudflare `ctx.waitUntil`). When provided, `flush()` does not await exports. */
   waitUntil?: (p: Promise<unknown>) => void;
   /** Receives any error raised while emitting telemetry; the SDK never throws into user code. */
-  onError?: (error: unknown) => void;
+  onError?: (cause: Error) => void;
+  /** Header value for a custom telemetry.dev integration. */
+  sdkName?: string;
 }
 //#endregion
 //#region src/attrs.d.ts
@@ -60,7 +70,7 @@ interface TokenUsage {
 interface GenerationFields {
   model?: string;
   provider?: string;
-  systemInstructions?: unknown;
+  systemInstructions?: Parameters<MaskFn>[0];
   responseModel?: string;
   responseId?: string;
   usage?: TokenUsage;
@@ -90,12 +100,12 @@ interface AgentFields {
 interface SpanFields extends GenerationFields, ToolFields, AgentFields {
   /** Rename the span (update only). */
   name?: string;
-  input?: unknown;
-  output?: unknown;
+  input?: Parameters<MaskFn>[0];
+  output?: Parameters<MaskFn>[0];
   /** Marks the span failed: status ERROR + error.type + an "exception" event. */
   error?: unknown;
   /** td.metadata.<key> on this span only; use propagateAttributes for scope-wide metadata. */
-  metadata?: Record<string, unknown>;
+  metadata?: Record<string, Parameters<MaskFn>[0]>;
   /** Raw attribute escape hatch, merged last. */
   attributes?: Record<string, AttributeValue>;
 }
@@ -122,7 +132,7 @@ declare function init(options?: TelemetryOptions, overrides?: ClientOverrides):
 interface LogOptions {
   /** Default "info". */
   level?: LogLevel;
-  attributes?: Record<string, unknown>;
+  attributes?: Record<string, Parameters<MaskFn>[0]>;
   eventName?: string;
   timestamp?: Date | number;
 }
@@ -137,8 +147,12 @@ type ParentRef = string | SpanHandle | SpanContext | Context;
 interface StartSpanOptions extends SpanFields {
   /** Default "span" → operation "function". */
   type?: SpanType;
+  /** OpenTelemetry span kind; defaults to INTERNAL. */
+  kind?: SpanKind;
   /** Parent override; defaults to the active context. */
   parent?: ParentRef;
+  /** Links to associate with the span. */
+  links?: Link[];
   startTime?: Date | number;
   /** Per-call override of the global captureInput. */
   captureInput?: boolean;
@@ -166,6 +180,14 @@ declare function startActiveSpan<T>(name: string, fn: (span: SpanHandle) => T):
 declare function startActiveSpan<T>(name: string, options: StartSpanOptions, fn: (span: SpanHandle) => T): T;
 /** Update the innermost active span; no-op when none is recording. */
 declare function updateActiveSpan(fields: SpanFields): void;
+/** Extract W3C trace context; baggage is omitted unless includeBaggage is true. */
+declare function extractW3cContext(carrier: Record<string, unknown>, options?: {
+  includeBaggage?: boolean;
+}): Context;
+/** Inject W3C trace context; baggage is omitted unless includeBaggage is true. */
+declare function injectW3cContext(context: Context, carrier: Record<string, unknown>, options?: {
+  includeBaggage?: boolean;
+}): void;
 /** Serialize the active span context as a W3C traceparent; null when there is none. */
 declare function getTraceparent(): string | null;
 //#endregion
@@ -179,6 +201,6 @@ interface ObserveOptions extends StartSpanOptions {
  * output, thrown/rejected errors captured and rethrown. Activates context so nested SDK calls
  * parent to it. Resolves the client at call time, so wrapping at module load before init() works.
  */
-declare function observe<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn, options?: ObserveOptions): (...args: TArgs) => TReturn;
+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, type SdkLogLevel, type SpanFields, type SpanHandle, type SpanType, type StartSpanOptions, type TelemetryClient, type TelemetryOptions, type TokenUsage, type ToolFields, flush, getTraceparent, init, log, observe, propagateAttributes, shutdown, startActiveSpan, startSpan, updateActiveSpan };
+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 };

package/dist/index.mjs

@@ -1,9 +1,9 @@
-import { INVALID_SPAN_CONTEXT, ROOT_CONTEXT, SpanKind, SpanStatusCode, context, defaultTextMapSetter, propagation, trace } from "@opentelemetry/api";
-import { W3CTraceContextPropagator, parseTraceParent } from "@opentelemetry/core";
+import { INVALID_SPAN_CONTEXT, ROOT_CONTEXT, SpanKind, SpanStatusCode, context, defaultTextMapGetter, defaultTextMapSetter, propagation, trace } from "@opentelemetry/api";
+import { CompositePropagator, W3CBaggagePropagator, W3CTraceContextPropagator, parseTraceParent } from "@opentelemetry/core";
 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_VERSION, StampingSpanProcessor, activeContext, als, createLogExporter, createMetricExporter, createMetricsPipeline, createTraceExporter, diag, jsonAttr, omitUndefined, otlpHeaders, propagateAttributes, propagatedFromContext, reportError, resolveEnv, setLogLevel, withContext } from "@telemetry-dev/otel";
+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 { SeverityNumber } from "@opentelemetry/api-logs";
 function resolveConfig(options = {}) {
 	const env = resolveEnv();
@@ -16,6 +16,7 @@ function resolveConfig(options = {}) {
 		enabled: options.enabled ?? true,
 		registerGlobal: options.registerGlobal ?? false,
 		exportMode: options.exportMode ?? "batched",
+		sampler: options.sampler,
 		captureInput: options.captureInput ?? true,
 		captureOutput: options.captureOutput ?? true,
 		mask: options.mask,
@@ -25,11 +26,13 @@ function resolveConfig(options = {}) {
 			...options.batch
 		},
 		spanFilter: options.spanFilter,
+		sessionRootOf: options.sessionRootOf,
 		resourceAttributes: options.resourceAttributes,
 		logLevel: options.logLevel ?? "warn",
 		fetchImpl: options.fetch ?? globalThis.fetch,
 		waitUntil: options.waitUntil,
-		onError: options.onError
+		onError: options.onError,
+		sdkName: options.sdkName ?? "@telemetry-dev/sdk"
 	};
 }
 //#endregion
@@ -53,7 +56,7 @@ function init(options, overrides) {
 	try {
 		return initInner(options, overrides);
 	} catch (error) {
-		reportError(options?.onError, error);
+		reportError(options?.onError, error instanceof Error ? error : new Error(String(error)));
 		activeClient = NOOP_CLIENT;
 		return NOOP_CLIENT;
 	}
@@ -79,7 +82,7 @@ function initInner(options, overrides) {
 		fetchImpl: config.fetchImpl,
 		onError: config.onError
 	};
-	const headers = config.apiKey ? otlpHeaders(config.apiKey) : void 0;
+	const headers = config.apiKey ? otlpHeaders(config.apiKey, config.sdkName) : void 0;
 	const spanExporter = overrides?.spanExporter ?? createTraceExporter({
 		url: `${config.baseUrl}/v1/traces`,
 		headers
@@ -93,25 +96,27 @@ function initInner(options, overrides) {
 		exporter: metricExporter,
 		exportIntervalMillis: config.exportMode === "batched" ? BATCHED_METRIC_INTERVAL_MS : DORMANT_INTERVAL_MS
 	}) : void 0;
-	const spanFilter = config.spanFilter ?? (config.registerGlobal ? (span) => span.instrumentationScope.name === SCOPE_NAME : void 0);
+	const spanFilter = config.spanFilter ?? (config.registerGlobal ? (span) => span.instrumentationScope.name === SCOPE_NAME$1 : void 0);
+	const processor = new StampingSpanProcessor({
+		exporter: spanExporter,
+		exportMode: config.exportMode,
+		batch: config.batch,
+		spanFilter,
+		recordMetrics: metrics ? (span) => metrics.record(span) : void 0,
+		onError: config.onError
+	});
 	const provider = new BasicTracerProvider({
 		resource,
-		spanProcessors: [new StampingSpanProcessor({
-			exporter: spanExporter,
-			exportMode: config.exportMode,
-			batch: config.batch,
-			spanFilter,
-			recordMetrics: metrics ? (span) => metrics.record(span) : void 0,
-			onError: config.onError
-		})],
+		sampler: sessionSampler(config.sampler),
+		spanProcessors: [processor],
 		spanLimits: { attributeValueLengthLimit: config.maxAttributeLength }
 	});
-	const tracer = provider.getTracer(SCOPE_NAME, SCOPE_VERSION);
+	const tracer = provider.getTracer(SCOPE_NAME$1, SCOPE_VERSION);
 	let registeredTrace = false;
 	let registeredContext = false;
 	let registeredPropagation = false;
 	if (config.registerGlobal) {
-		registeredTrace = trace.setGlobalTracerProvider(provider);
+		registeredTrace = trace.setGlobalTracerProvider(config.sessionRootOf ? sessionRootTracerProvider(provider, config.apiKey, config.sessionRootOf, config.onError) : provider);
 		if (als) registeredContext = context.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");
@@ -131,7 +136,7 @@ function initInner(options, overrides) {
 				processors: [logProcessor]
 			});
 			logs = {
-				logger: loggerProvider.getLogger(SCOPE_NAME, SCOPE_VERSION),
+				logger: loggerProvider.getLogger(SCOPE_NAME$1, SCOPE_VERSION),
 				forceFlush: () => loggerProvider.forceFlush(),
 				shutdown: () => loggerProvider.shutdown()
 			};
@@ -188,7 +193,7 @@ function prepareCaptureValue(key, value, cfg) {
 	if (cfg.mask) try {
 		masked = cfg.mask(value, { key });
 	} catch (error) {
-		reportError(cfg.onError, error);
+		reportError(cfg.onError, error instanceof Error ? error : new Error(String(error)));
 		return;
 	}
 	const serialized = jsonAttr(masked);
@@ -232,7 +237,7 @@ function log(message, options) {
 			onError: cfg.onError
 		};
 		const severity = SEVERITIES[options?.level ?? "info"];
-		const ctx = activeContext();
+		const ctx = activeContext$1();
 		const attributes = {};
 		for (const [key, value] of Object.entries(options?.attributes ?? {})) {
 			if (value === void 0) continue;
@@ -245,7 +250,7 @@ function log(message, options) {
 		}
 		const propagated = propagatedFromContext(ctx);
 		if (propagated) {
-			for (const [key, value] of Object.entries(propagated)) if (value !== void 0) attributes[key] = typeof value === "string" ? truncate(value, cfg.maxAttributeLength) : value;
+			for (const [key, value] of Object.entries(propagated)) if (value !== void 0) attributes[key] = value.constructor === String ? truncate(String(value), cfg.maxAttributeLength) : value;
 		}
 		logger.emit({
 			body: prepareCaptureValue("log.message", message, captureCfg) ?? "",
@@ -257,7 +262,7 @@ function log(message, options) {
 			attributes
 		});
 	} catch (error) {
-		reportError(core.config.onError, error);
+		reportError(core.config.onError, error instanceof Error ? error : new Error(String(error)));
 	}
 }
 //#endregion
@@ -379,13 +384,14 @@ function resolveParent(parent) {
 			isRemote: true
 		});
 	}
-	if (isSpanHandle(parent)) return withAmbientPropagated(parent.context);
-	if (isContext(parent)) return withAmbientPropagated(parent);
-	return trace.setSpanContext(base, parent);
+	const ref = parent;
+	if (isSpanHandle(ref)) return withAmbientPropagated(ref.context);
+	if (isContext(ref)) return withAmbientPropagated(ref);
+	return trace.setSpanContext(base, ref);
 }
 function applyError(span, error) {
 	const err = error instanceof Error ? error : void 0;
-	const errorType = err?.name ?? "Error";
+	const errorType = err === void 0 ? "Error" : 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);
@@ -418,14 +424,23 @@ function metaFor(core, options) {
 }
 function createSpanHandle(core, name, options = {}) {
 	const meta = metaFor(core, options);
-	const parentCtx = resolveParent(options.parent);
+	const resolved = resolveParent(options.parent);
+	const parentCtx = withSessionParent(resolved, sessionIdOf(resolved, options.attributes), core.config.apiKey);
+	const attrs = fieldsToAttributes(options, meta.type, meta.capture);
 	const span = core.tracer.startSpan(name, {
-		kind: SpanKind.INTERNAL,
+		kind: options.kind ?? SpanKind.INTERNAL,
 		startTime: options.startTime,
-		attributes: { "gen_ai.operation.name": SPAN_TYPE_OPERATIONS[meta.type] }
+		links: options.links,
+		attributes: {
+			"gen_ai.operation.name": SPAN_TYPE_OPERATIONS[meta.type],
+			...propagatedFromContext(parentCtx),
+			...attrs
+		}
 	}, parentCtx);
 	SPAN_META.set(span, meta);
-	applyFields(span, meta, options);
+	if (Object.keys(attrs).length > 0) span.setAttributes(attrs);
+	if (options.name) span.updateName(options.name);
+	if (options.error !== void 0) applyError(span, options.error);
 	const spanContext = span.spanContext();
 	const flags = (spanContext.traceFlags & 255).toString(16).padStart(2, "0");
 	const handle = {
@@ -441,7 +456,7 @@ function createSpanHandle(core, name, options = {}) {
 			try {
 				applyFields(span, meta, fields);
 			} catch (error) {
-				reportError(meta.onError, error);
+				reportError(meta.onError, error instanceof Error ? error : new Error(String(error)));
 			}
 			return handle;
 		},
@@ -449,7 +464,7 @@ function createSpanHandle(core, name, options = {}) {
 			try {
 				if (fields) applyFields(span, meta, fields);
 			} catch (error) {
-				reportError(meta.onError, error);
+				reportError(meta.onError, error instanceof Error ? error : new Error(String(error)));
 			}
 			span.end(fields?.endTime);
 		}
@@ -463,7 +478,7 @@ function startSpan(name, options) {
 	try {
 		return createSpanHandle(core, name, options);
 	} catch (error) {
-		reportError(core.config.onError, error);
+		reportError(core.config.onError, error instanceof Error ? error : new Error(String(error)));
 		return NOOP_SPAN_HANDLE;
 	}
 }
@@ -485,9 +500,10 @@ function runWithHandle(handle, fn) {
 	}
 }
 function startActiveSpan(name, optionsOrFn, maybeFn) {
-	const fn = typeof optionsOrFn === "function" ? optionsOrFn : maybeFn;
-	const handle = startSpan(name, typeof optionsOrFn === "function" ? void 0 : optionsOrFn);
-	if (!handle.isRecording) return fn(handle);
+	const isFn = typeof optionsOrFn === "function";
+	const fn = isFn ? optionsOrFn : maybeFn;
+	const handle = startSpan(name, isFn ? void 0 : optionsOrFn);
+	if (handle === NOOP_SPAN_HANDLE) return fn(handle);
 	return runWithHandle(handle, fn);
 }
 /** Update the innermost active span; no-op when none is recording. */
@@ -499,14 +515,28 @@ function updateActiveSpan(fields) {
 		if (!span?.isRecording()) return;
 		applyFields(span, SPAN_META.get(span) ?? metaFor(core), fields);
 	} catch (error) {
-		reportError(core.config.onError, error);
+		reportError(core.config.onError, error instanceof Error ? error : new Error(String(error)));
 	}
 }
-const PROPAGATOR = new W3CTraceContextPropagator();
+const TRACE_CONTEXT_PROPAGATOR = new W3CTraceContextPropagator();
+const W3C_PROPAGATOR = new CompositePropagator({ propagators: [TRACE_CONTEXT_PROPAGATOR, new W3CBaggagePropagator()] });
+/** Extract W3C trace context; baggage is omitted unless includeBaggage is true. */
+function extractW3cContext(carrier, options = {}) {
+	return (options.includeBaggage === true ? W3C_PROPAGATOR : TRACE_CONTEXT_PROPAGATOR).extract(ROOT_CONTEXT, carrier, defaultTextMapGetter);
+}
+/** Inject W3C trace context; baggage is omitted unless includeBaggage is true. */
+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];
+	}
+	propagator.inject(context, carrier, defaultTextMapSetter);
+}
 /** Serialize the active span context as a W3C traceparent; null when there is none. */
 function getTraceparent() {
-	const carrier = {};
-	PROPAGATOR.inject(activeContext(), carrier, defaultTextMapSetter);
+	const carrier = { traceparent: void 0 };
+	TRACE_CONTEXT_PROPAGATOR.inject(activeContext(), carrier, defaultTextMapSetter);
 	return carrier.traceparent ?? null;
 }
 //#endregion
@@ -529,22 +559,22 @@ function observe(fn, options) {
 				input
 			});
 		} catch (error) {
-			reportError(core.config.onError, 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));
+			const result = withContext$1(handle.context, () => fn.apply(this, args));
 			if (isThenable(result)) return result.then((value) => {
 				handle.end({ output: value });
 				return value;
 			}, (error) => {
-				handle.end({ error });
+				handle.end({ error: error instanceof Error ? error : new Error(String(error)) });
 				throw error;
 			});
 			handle.end({ output: result });
 			return result;
 		} catch (error) {
-			handle.end({ error });
+			handle.end({ error: error instanceof Error ? error : new Error(String(error)) });
 			throw error;
 		}
 	};
@@ -555,4 +585,4 @@ function observe(fn, options) {
 	return wrapped;
 }
 //#endregion
-export { flush, getTraceparent, init, log, observe, propagateAttributes, shutdown, startActiveSpan, startSpan, updateActiveSpan };
+export { SCOPE_NAME, TelemetrySpanProcessor, activeContext, 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.0",
+  "version": "0.1.2",
   "description": "Pure TypeScript SDK for telemetry.dev: LLM traces, logs, and GenAI metrics on OpenTelemetry, for Node and edge runtimes.",
   "keywords": [
     "genai",
@@ -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.0"
+    "@telemetry-dev/otel": "^0.1.2"
   },
   "devDependencies": {
     "@opentelemetry/api": "^1.9.1",

package/src/attrs.ts

@@ -9,13 +9,13 @@ export type SpanType = "span" | "generation" | "tool" | "agent" | "embedding";
 // Operation names are taken verbatim by the ingest's deriveOperation. Plain spans always get an
 // explicit "function": without one, the propagated gen_ai.conversation.id would trip the ingest's
 // hasGenAi heuristic and misclassify them as "llm".
-export const SPAN_TYPE_OPERATIONS: Record<SpanType, string> = {
+export const SPAN_TYPE_OPERATIONS = {
   span: "function",
   generation: "chat",
   tool: "execute_tool",
   agent: "invoke_agent",
   embedding: "embeddings",
-};
+} satisfies Record<SpanType, string>;
 
 export function inputKeyFor(type: SpanType): string {
   return type === "tool" ? "gen_ai.tool.call.arguments" : "gen_ai.input.messages";
@@ -37,7 +37,7 @@ export interface TokenUsage {
 export interface GenerationFields {
   model?: string;
   provider?: string;
-  systemInstructions?: unknown;
+  systemInstructions?: Parameters<import("./config.ts").MaskFn>[0];
   responseModel?: string;
   responseId?: string;
   usage?: TokenUsage;
@@ -70,12 +70,12 @@ export interface AgentFields {
 export interface SpanFields extends GenerationFields, ToolFields, AgentFields {
   /** Rename the span (update only). */
   name?: string;
-  input?: unknown;
-  output?: unknown;
+  input?: Parameters<import("./config.ts").MaskFn>[0];
+  output?: Parameters<import("./config.ts").MaskFn>[0];
   /** Marks the span failed: status ERROR + error.type + an "exception" event. */
   error?: unknown;
   /** td.metadata.<key> on this span only; use propagateAttributes for scope-wide metadata. */
-  metadata?: Record<string, unknown>;
+  metadata?: Record<string, Parameters<import("./config.ts").MaskFn>[0]>;
   /** Raw attribute escape hatch, merged last. */
   attributes?: Record<string, AttributeValue>;
 }

package/src/capture.ts

@@ -8,7 +8,7 @@ export const TRUNCATION_MARKER = "...[truncated]";
 export interface CaptureConfig {
   mask?: MaskFn;
   maxAttributeLength: number;
-  onError?: (error: unknown) => void;
+  onError?: (cause: Error) => void;
 }
 
 export function truncate(value: string, maxLength: number): string {
@@ -21,7 +21,7 @@ export function truncate(value: string, maxLength: number): string {
 /** The single content funnel: mask → JSON stringify → truncate. */
 export function prepareCaptureValue(
   key: string,
-  value: unknown,
+  value: Parameters<MaskFn>[0],
   cfg: CaptureConfig,
 ): string | undefined {
   let masked = value;
@@ -29,7 +29,7 @@ export function prepareCaptureValue(
     try {
       masked = cfg.mask(value, { key });
     } catch (error) {
-      reportError(cfg.onError, error);
+      reportError(cfg.onError, error instanceof Error ? error : new Error(String(error)));
       return undefined;
     }
   }

package/src/client.ts

@@ -29,6 +29,8 @@ import {
   reportError,
   SCOPE_NAME,
   SCOPE_VERSION,
+  sessionRootTracerProvider,
+  sessionSampler,
   setLogLevel,
   StampingSpanProcessor,
   type Transport,
@@ -85,7 +87,7 @@ export function init(options?: TelemetryOptions, overrides?: ClientOverrides): T
   try {
     return initInner(options, overrides);
   } catch (error) {
-    reportError(options?.onError, error);
+    reportError(options?.onError, error instanceof Error ? error : new Error(String(error)));
     activeClient = NOOP_CLIENT;
     return NOOP_CLIENT;
   }
@@ -98,7 +100,7 @@ function initInner(options?: TelemetryOptions, overrides?: ClientOverrides): Tel
   if (activeClient && activeClient !== NOOP_CLIENT) {
     diag.warn("init() called again; replacing the previous client");
     // shutdown() synchronously releases global registrations before this init claims them.
-    void activeClient.shutdown().catch((error: unknown) => reportError(config.onError, error));
+    void activeClient.shutdown().catch((error: Error) => reportError(config.onError, error));
   }
 
   const enabled = config.enabled && Boolean(config.apiKey ?? overrides?.spanExporter);
@@ -116,7 +118,7 @@ function initInner(options?: TelemetryOptions, overrides?: ClientOverrides): Tel
     ...config.resourceAttributes,
   });
   const transport: Transport = { fetchImpl: config.fetchImpl, onError: config.onError };
-  const headers = config.apiKey ? otlpHeaders(config.apiKey) : undefined;
+  const headers = config.apiKey ? otlpHeaders(config.apiKey, config.sdkName) : undefined;
 
   const spanExporter =
     overrides?.spanExporter ??
@@ -153,6 +155,7 @@ function initInner(options?: TelemetryOptions, overrides?: ClientOverrides): Tel
 
   const provider = new BasicTracerProvider({
     resource,
+    sampler: sessionSampler(config.sampler),
     spanProcessors: [processor],
     spanLimits: { attributeValueLengthLimit: config.maxAttributeLength },
   });
@@ -162,7 +165,11 @@ function initInner(options?: TelemetryOptions, overrides?: ClientOverrides): Tel
   let registeredContext = false;
   let registeredPropagation = false;
   if (config.registerGlobal) {
-    registeredTrace = trace.setGlobalTracerProvider(provider);
+    registeredTrace = trace.setGlobalTracerProvider(
+      config.sessionRootOf
+        ? sessionRootTracerProvider(provider, config.apiKey, config.sessionRootOf, config.onError)
+        : provider,
+    );
     if (als) {
       registeredContext = apiContext.setGlobalContextManager(new AlsContextManager(als));
     }
@@ -204,12 +211,12 @@ function initInner(options?: TelemetryOptions, overrides?: ClientOverrides): Tel
 
   let torn = false;
   const collect = (op: "forceFlush" | "shutdown"): Promise<void> => {
-    const parts: Promise<unknown>[] = [provider[op]()];
+    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: unknown) => reportError(config.onError, error));
+      .catch((error: Error) => reportError(config.onError, error));
   };
   const handoff = (p: Promise<void>): Promise<void> => {
     if (config.waitUntil) {

package/src/config.ts

@@ -1,5 +1,5 @@
 import type { AttributeValue } from "@opentelemetry/api";
-import type { ReadableSpan } from "@opentelemetry/sdk-trace-base";
+import type { ReadableSpan, Sampler } from "@opentelemetry/sdk-trace-base";
 import {
   type BatchOptions,
   DEFAULT_BASE_URL,
@@ -7,12 +7,13 @@ import {
   type ExportMode,
   resolveEnv,
   type SdkLogLevel,
+  type SessionRootOf,
 } from "@telemetry-dev/otel";
 
 export type { BatchOptions, ExportMode, LogLevel, SdkLogLevel } from "@telemetry-dev/otel";
 
 /** Redaction hook applied to captured content (input/output/log message) before JSON stringification. */
-export type MaskFn = (value: unknown, ctx: { key: string }) => unknown;
+export type MaskFn<T = unknown> = (value: T, ctx: { key: string }) => T;
 
 export interface TelemetryOptions {
   /** telemetry.dev ingest key (`td_live_…`). Falls back to `TELEMETRY_DEV_API_KEY`. When absent the SDK is a no-op. */
@@ -29,6 +30,8 @@ export interface TelemetryOptions {
   registerGlobal?: boolean;
   /** "batched" (default) buffers spans; "immediate" exports per span (serverless). */
   exportMode?: ExportMode;
+  /** OTel sampling policy. Defaults to OTEL_TRACES_SAMPLER / OTEL_TRACES_SAMPLER_ARG. */
+  sampler?: Sampler;
   /** Capture span inputs (args, prompts) by default. Default true. */
   captureInput?: boolean;
   /** Capture span outputs (results, completions) by default. Default true. */
@@ -40,6 +43,12 @@ export interface TelemetryOptions {
   batch?: BatchOptions;
   /** Export filter. Default when registerGlobal: only spans from this SDK's instrumentation scope. */
   spanFilter?: (span: ReadableSpan) => boolean;
+  /**
+   * With registerGlobal: spans from other tracers that this returns a session id for are
+   * parented under the session trace even when a parent span is active. Use it for frameworks
+   * that start each turn inside their own engine span.
+   */
+  sessionRootOf?: SessionRootOf;
   /** Extra resource attributes merged onto service.name / deployment.environment.name. */
   resourceAttributes?: Record<string, AttributeValue>;
   /** SDK self-diagnostics console level. Default "warn"; "silent" disables. */
@@ -49,7 +58,9 @@ export interface TelemetryOptions {
   /** Serverless extender (e.g. Cloudflare `ctx.waitUntil`). When provided, `flush()` does not await exports. */
   waitUntil?: (p: Promise<unknown>) => void;
   /** Receives any error raised while emitting telemetry; the SDK never throws into user code. */
-  onError?: (error: unknown) => void;
+  onError?: (cause: Error) => void;
+  /** Header value for a custom telemetry.dev integration. */
+  sdkName?: string;
 }
 
 export interface ResolvedConfig {
@@ -60,17 +71,20 @@ export interface ResolvedConfig {
   enabled: boolean;
   registerGlobal: boolean;
   exportMode: ExportMode;
+  sampler?: Sampler;
   captureInput: boolean;
   captureOutput: boolean;
   mask?: MaskFn;
   maxAttributeLength: number;
   batch: Required<BatchOptions>;
   spanFilter?: (span: ReadableSpan) => boolean;
+  sessionRootOf?: SessionRootOf;
   resourceAttributes?: Record<string, AttributeValue>;
   logLevel: SdkLogLevel;
   fetchImpl: typeof fetch;
   waitUntil?: (p: Promise<unknown>) => void;
-  onError?: (error: unknown) => void;
+  onError?: (cause: Error) => void;
+  sdkName: string;
 }
 
 export const DEFAULT_MAX_ATTRIBUTE_LENGTH = 65536;
@@ -89,16 +103,19 @@ export function resolveConfig(options: TelemetryOptions = {}): ResolvedConfig {
     enabled: options.enabled ?? true,
     registerGlobal: options.registerGlobal ?? false,
     exportMode: options.exportMode ?? "batched",
+    sampler: options.sampler,
     captureInput: options.captureInput ?? true,
     captureOutput: options.captureOutput ?? true,
     mask: options.mask,
     maxAttributeLength: options.maxAttributeLength ?? DEFAULT_MAX_ATTRIBUTE_LENGTH,
     batch: { ...DEFAULT_BATCH, ...options.batch },
     spanFilter: options.spanFilter,
+    sessionRootOf: options.sessionRootOf,
     resourceAttributes: options.resourceAttributes,
     logLevel: options.logLevel ?? "warn",
     fetchImpl: options.fetch ?? globalThis.fetch,
     waitUntil: options.waitUntil,
     onError: options.onError,
+    sdkName: options.sdkName ?? "@telemetry-dev/sdk",
   };
 }

package/src/index.ts

@@ -15,15 +15,25 @@ export type {
   SdkLogLevel,
   TelemetryOptions,
 } from "./config.ts";
-export { propagateAttributes, type PropagatedAttributes } from "@telemetry-dev/otel";
+export {
+  propagateAttributes,
+  type PropagatedAttributes,
+  SCOPE_NAME,
+  TelemetrySpanProcessor,
+  type TelemetrySpanProcessorOptions,
+} from "@telemetry-dev/otel";
 export { log, type LogOptions } from "./logs.ts";
 export { observe, type ObserveOptions } from "./observe.ts";
 export {
+  activeContext,
+  extractW3cContext,
   getTraceparent,
+  injectW3cContext,
   type ParentRef,
   type SpanHandle,
   startActiveSpan,
   startSpan,
   type StartSpanOptions,
   updateActiveSpan,
+  withContext,
 } from "./span.ts";

package/src/logs.ts

@@ -8,17 +8,17 @@ import { currentClient } from "./client.ts";
 import type { LogLevel } from "./config.ts";
 
 // Severity numbers match the ingest's severityFromNumber buckets exactly.
-const SEVERITIES: Record<LogLevel, { number: SeverityNumber; text: string }> = {
+const SEVERITIES = {
   debug: { number: SeverityNumber.DEBUG, text: "DEBUG" },
   info: { number: SeverityNumber.INFO, text: "INFO" },
   warn: { number: SeverityNumber.WARN, text: "WARN" },
   error: { number: SeverityNumber.ERROR, text: "ERROR" },
-};
+} satisfies Record<LogLevel, { number: SeverityNumber; text: string }>;
 
 export interface LogOptions {
   /** Default "info". */
   level?: LogLevel;
-  attributes?: Record<string, unknown>;
+  attributes?: Record<string, Parameters<import("./config.ts").MaskFn>[0]>;
   eventName?: string;
   timestamp?: Date | number;
 }
@@ -57,7 +57,7 @@ export function log(message: string, options?: LogOptions): void {
       for (const [key, value] of Object.entries(propagated)) {
         if (value !== undefined) {
           attributes[key] =
-            typeof value === "string" ? truncate(value, cfg.maxAttributeLength) : value;
+            value.constructor === String ? truncate(String(value), cfg.maxAttributeLength) : value;
         }
       }
     }
@@ -72,6 +72,6 @@ export function log(message: string, options?: LogOptions): void {
       attributes,
     });
   } catch (error) {
-    reportError(core.config.onError, error);
+    reportError(core.config.onError, error instanceof Error ? error : new Error(String(error)));
   }
 }

package/src/observe.ts

@@ -13,11 +13,11 @@ export interface ObserveOptions extends StartSpanOptions {
  * output, thrown/rejected errors captured and rethrown. Activates context so nested SDK calls
  * parent to it. Resolves the client at call time, so wrapping at module load before init() works.
  */
-export function observe<TArgs extends unknown[], TReturn>(
-  fn: (...args: TArgs) => TReturn,
+export function observe<TThis, TArgs extends unknown[], TReturn>(
+  fn: (this: TThis, ...args: TArgs) => TReturn,
   options?: ObserveOptions,
 ): (...args: TArgs) => TReturn {
-  const wrapped = function (this: unknown, ...args: TArgs): TReturn {
+  const wrapped = function (this: TThis, ...args: TArgs): TReturn {
     const core = currentClient().core;
     if (!core) return fn.apply(this, args);
 
@@ -34,20 +34,20 @@ export function observe<TArgs extends unknown[], TReturn>(
               : args;
       handle = createSpanHandle(core, name, { ...options, input });
     } catch (error) {
-      reportError(core.config.onError, 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 as unknown as Promise<unknown>).then(
+        return result.then(
           (value) => {
             handle.end({ output: value });
             return value;
           },
-          (error: unknown) => {
-            handle.end({ error });
+          (error: Error) => {
+            handle.end({ error: error instanceof Error ? error : new Error(String(error)) });
             throw error;
           },
         ) as TReturn;
@@ -55,7 +55,7 @@ export function observe<TArgs extends unknown[], TReturn>(
       handle.end({ output: result });
       return result;
     } catch (error) {
-      handle.end({ error });
+      handle.end({ error: error instanceof Error ? error : new Error(String(error)) });
       throw error;
     }
   };

package/src/span.ts

@@ -1,13 +1,21 @@
 import {
   type Context,
+  defaultTextMapGetter,
   defaultTextMapSetter,
+  type Link,
+  ROOT_CONTEXT,
   type Span,
   type SpanContext,
   SpanKind,
   SpanStatusCode,
   trace,
 } from "@opentelemetry/api";
-import { parseTraceParent, W3CTraceContextPropagator } from "@opentelemetry/core";
+import {
+  CompositePropagator,
+  parseTraceParent,
+  W3CBaggagePropagator,
+  W3CTraceContextPropagator,
+} from "@opentelemetry/core";
 
 import {
   activeContext,
@@ -15,7 +23,9 @@ import {
   PROPAGATED_KEY,
   propagatedFromContext,
   reportError,
+  sessionIdOf,
   withContext,
+  withSessionParent,
 } from "@telemetry-dev/otel";
 
 import {
@@ -33,8 +43,12 @@ export type ParentRef = string /* W3C traceparent */ | SpanHandle | SpanContext
 export interface StartSpanOptions extends SpanFields {
   /** Default "span" → operation "function". */
   type?: SpanType;
+  /** OpenTelemetry span kind; defaults to INTERNAL. */
+  kind?: SpanKind;
   /** Parent override; defaults to the active context. */
   parent?: ParentRef;
+  /** Links to associate with the span. */
+  links?: Link[];
   startTime?: Date | number;
   /** Per-call override of the global captureInput. */
   captureInput?: boolean;
@@ -59,7 +73,7 @@ export interface SpanHandle {
 interface SpanMeta {
   type: SpanType;
   capture: FieldCaptureConfig;
-  onError?: (error: unknown) => void;
+  onError?: (cause: Error) => void;
 }
 
 // Remembers each span's type + capture flags so update()/end()/updateActiveSpan map
@@ -68,7 +82,7 @@ const SPAN_META = new WeakMap<Span, SpanMeta>();
 
 const SEVERITY_ERROR = 17;
 
-export function isThenable(value: unknown): value is PromiseLike<unknown> {
+export function isThenable<T>(value: T): value is T & PromiseLike<Awaited<T>> {
   return (
     value != null &&
     (typeof value === "object" || typeof value === "function") &&
@@ -77,11 +91,11 @@ export function isThenable(value: unknown): value is PromiseLike<unknown> {
   );
 }
 
-function isContext(value: object): value is Context {
+function isContext(value: Exclude<ParentRef, string>): value is Context {
   return "getValue" in value && typeof value.getValue === "function";
 }
 
-function isSpanHandle(value: object): value is SpanHandle {
+function isSpanHandle(value: Exclude<ParentRef, string>): value is SpanHandle {
   return "span" in value && "context" in value && "update" in value;
 }
 
@@ -101,14 +115,22 @@ function resolveParent(parent: ParentRef | undefined): Context {
     if (!parsed) return base;
     return trace.setSpanContext(base, { ...parsed, isRemote: true });
   }
-  if (isSpanHandle(parent)) return withAmbientPropagated(parent.context);
-  if (isContext(parent)) return withAmbientPropagated(parent);
-  return trace.setSpanContext(base, parent);
+  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;
-  const errorType = err?.name ?? "Error";
+  // 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 =
+    err === undefined
+      ? "Error"
+      : 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);
@@ -151,18 +173,32 @@ export function createSpanHandle(
   options: StartSpanOptions = {},
 ): SpanHandle {
   const meta = metaFor(core, options);
-  const parentCtx = resolveParent(options.parent);
+  const resolved = resolveParent(options.parent);
+  const parentCtx = withSessionParent(
+    resolved,
+    sessionIdOf(resolved, options.attributes),
+    core.config.apiKey,
+  );
+  const attrs = fieldsToAttributes(options, meta.type, meta.capture);
   const span = core.tracer.startSpan(
     name,
     {
-      kind: SpanKind.INTERNAL,
+      kind: options.kind ?? SpanKind.INTERNAL,
       startTime: options.startTime,
-      attributes: { "gen_ai.operation.name": SPAN_TYPE_OPERATIONS[meta.type] },
+      links: options.links,
+      attributes: {
+        "gen_ai.operation.name": SPAN_TYPE_OPERATIONS[meta.type],
+        ...propagatedFromContext(parentCtx),
+        ...attrs,
+      },
     },
     parentCtx,
   );
   SPAN_META.set(span, meta);
-  applyFields(span, meta, options);
+  // 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();
   const flags = (spanContext.traceFlags & 0xff).toString(16).padStart(2, "0");
@@ -179,7 +215,7 @@ export function createSpanHandle(
       try {
         applyFields(span, meta, fields);
       } catch (error) {
-        reportError(meta.onError, error);
+        reportError(meta.onError, error instanceof Error ? error : new Error(String(error)));
       }
       return handle;
     },
@@ -187,7 +223,7 @@ export function createSpanHandle(
       try {
         if (fields) applyFields(span, meta, fields);
       } catch (error) {
-        reportError(meta.onError, error);
+        reportError(meta.onError, error instanceof Error ? error : new Error(String(error)));
       }
       span.end(fields?.endTime);
     },
@@ -202,7 +238,7 @@ export function startSpan(name: string, options?: StartSpanOptions): SpanHandle
   try {
     return createSpanHandle(core, name, options);
   } catch (error) {
-    reportError(core.config.onError, error);
+    reportError(core.config.onError, error instanceof Error ? error : new Error(String(error)));
     return NOOP_SPAN_HANDLE;
   }
 }
@@ -211,7 +247,7 @@ export function runWithHandle<T>(handle: SpanHandle, fn: (span: SpanHandle) => T
   try {
     const result = withContext(handle.context, () => fn(handle));
     if (isThenable(result)) {
-      return (result as unknown as Promise<unknown>).then(
+      return result.then(
         (value) => {
           handle.end();
           return value;
@@ -241,10 +277,11 @@ export function startActiveSpan<T>(
   optionsOrFn: StartSpanOptions | ((span: SpanHandle) => T),
   maybeFn?: (span: SpanHandle) => T,
 ): T {
-  const fn = typeof optionsOrFn === "function" ? optionsOrFn : maybeFn!;
-  const options = typeof optionsOrFn === "function" ? undefined : optionsOrFn;
+  const isFn = typeof optionsOrFn === "function";
+  const fn = isFn ? optionsOrFn : maybeFn!;
+  const options = isFn ? undefined : optionsOrFn;
   const handle = startSpan(name, options);
-  if (!handle.isRecording) return fn(handle);
+  if (handle === NOOP_SPAN_HANDLE) return fn(handle);
   return runWithHandle(handle, fn);
 }
 
@@ -258,15 +295,45 @@ export function updateActiveSpan(fields: SpanFields): void {
     const meta = SPAN_META.get(span) ?? metaFor(core);
     applyFields(span, meta, fields);
   } catch (error) {
-    reportError(core.config.onError, error);
+    reportError(core.config.onError, error instanceof Error ? error : new Error(String(error)));
   }
 }
 
-const PROPAGATOR = new W3CTraceContextPropagator();
+const TRACE_CONTEXT_PROPAGATOR = new W3CTraceContextPropagator();
+const W3C_PROPAGATOR = new CompositePropagator({
+  propagators: [TRACE_CONTEXT_PROPAGATOR, new W3CBaggagePropagator()],
+});
+
+export { activeContext, withContext };
+
+/** Extract W3C trace context; baggage is omitted unless includeBaggage is true. */
+export function extractW3cContext(
+  carrier: Record<string, unknown>,
+  options: { includeBaggage?: boolean } = {},
+): Context {
+  const propagator = options.includeBaggage === true ? W3C_PROPAGATOR : TRACE_CONTEXT_PROPAGATOR;
+  return propagator.extract(ROOT_CONTEXT, carrier, defaultTextMapGetter);
+}
+
+/** Inject W3C trace context; baggage is omitted unless includeBaggage is true. */
+export function injectW3cContext(
+  context: Context,
+  carrier: Record<string, unknown>,
+  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];
+    }
+  }
+  propagator.inject(context, carrier, defaultTextMapSetter);
+}
 
 /** Serialize the active span context as a W3C traceparent; null when there is none. */
 export function getTraceparent(): string | null {
-  const carrier: { traceparent?: string } = {};
-  PROPAGATOR.inject(activeContext(), carrier, defaultTextMapSetter);
+  const carrier = { traceparent: undefined };
+  TRACE_CONTEXT_PROPAGATOR.inject(activeContext(), carrier, defaultTextMapSetter);
   return carrier.traceparent ?? null;
 }