@telemetry-dev/sdk 0.1.1 → 0.1.3

package/README.md

@@ -60,6 +60,17 @@ 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.
+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).

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 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, activeContext, propagateAttributes, withContext } 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
@@ -20,10 +20,14 @@ 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). */
   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 +39,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. */
@@ -195,4 +205,4 @@ interface ObserveOptions extends StartSpanOptions {
  */
 declare function observe<TThis, TArgs extends unknown[], TReturn>(fn: (this: TThis, ...args: TArgs) => TReturn, options?: ObserveOptions): (...args: TArgs) => TReturn;
 //#endregion
-export { type AgentFields, type BatchOptions, type ClientOverrides, type ExportMode, type GenerationFields, type LogLevel, type LogOptions, type MaskFn, type ObserveOptions, type ParentRef, type PropagatedAttributes, type SdkLogLevel, type SpanFields, type SpanHandle, type SpanType, type StartSpanOptions, type TelemetryClient, type TelemetryOptions, type TokenUsage, type ToolFields, activeContext, extractW3cContext, flush, getTraceparent, init, injectW3cContext, log, observe, propagateAttributes, shutdown, startActiveSpan, startSpan, updateActiveSpan, withContext };
+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

@@ -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_VERSION, StampingSpanProcessor, activeContext, activeContext as activeContext$1, als, createLogExporter, createMetricExporter, createMetricsPipeline, createTraceExporter, diag, jsonAttr, omitUndefined, otlpHeaders, propagateAttributes, propagatedFromContext, reportError, resolveEnv, setLogLevel, withContext, withContext as withContext$1 } 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();
+	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,8 +15,10 @@ 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,
 		captureInput: options.captureInput ?? true,
 		captureOutput: options.captureOutput ?? true,
 		mask: options.mask,
@@ -25,6 +28,7 @@ function resolveConfig(options = {}) {
 			...options.batch
 		},
 		spanFilter: options.spanFilter,
+		sessionRootOf: options.sessionRootOf,
 		resourceAttributes: options.resourceAttributes,
 		logLevel: options.logLevel ?? "warn",
 		fetchImpl: options.fetch ?? globalThis.fetch,
@@ -71,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,
@@ -94,25 +99,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");
@@ -132,7 +139,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()
 			};
@@ -233,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;
@@ -420,15 +434,27 @@ 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 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,
 		startTime: options.startTime,
 		links: options.links,
-		attributes: { "gen_ai.operation.name": SPAN_TYPE_OPERATIONS[meta.type] }
+		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 = {
@@ -491,7 +517,7 @@ function startActiveSpan(name, optionsOrFn, maybeFn) {
 	const isFn = typeof optionsOrFn === "function";
 	const fn = isFn ? optionsOrFn : maybeFn;
 	const handle = startSpan(name, isFn ? void 0 : optionsOrFn);
-	if (!handle.isRecording) return fn(handle);
+	if (handle === NOOP_SPAN_HANDLE) return fn(handle);
 	return runWithHandle(handle, fn);
 }
 /** Update the innermost active span; no-op when none is recording. */
@@ -573,4 +599,4 @@ function observe(fn, options) {
 	return wrapped;
 }
 //#endregion
-export { activeContext, extractW3cContext, flush, getTraceparent, init, injectW3cContext, log, observe, propagateAttributes, shutdown, startActiveSpan, startSpan, updateActiveSpan, withContext };
+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.1",
+  "version": "0.1.3",
   "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/sdks.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.1"
+    "@telemetry-dev/otel": "^0.1.3"
   },
   "devDependencies": {
     "@opentelemetry/api": "^1.9.1",

package/src/client.ts

@@ -29,6 +29,8 @@ import {
   reportError,
   SCOPE_NAME,
   SCOPE_VERSION,
+  sessionRootTracerProvider,
+  sessionSampler,
   setLogLevel,
   StampingSpanProcessor,
   type Transport,
@@ -110,6 +112,8 @@ function initInner(options?: TelemetryOptions, overrides?: ClientOverrides): Tel
     return NOOP_CLIENT;
   }
 
+  if (config.sessionMode === "process") config.processSessionId = globalThis.crypto.randomUUID();
+
   const resource = resourceFromAttributes({
     "service.name": config.serviceName,
     "deployment.environment.name": config.environment,
@@ -153,6 +157,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 +167,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));
     }

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,6 +7,7 @@ import {
   type ExportMode,
   resolveEnv,
   type SdkLogLevel,
+  type SessionRootOf,
 } from "@telemetry-dev/otel";
 
 export type { BatchOptions, ExportMode, LogLevel, SdkLogLevel } from "@telemetry-dev/otel";
@@ -25,10 +26,14 @@ 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). */
   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 +45,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. */
@@ -60,14 +71,18 @@ export interface ResolvedConfig {
   environment: string;
   serviceName: string;
   enabled: boolean;
+  sessionMode: "explicit" | "process";
+  processSessionId?: string;
   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;
@@ -80,6 +95,13 @@ 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(
     /\/+$/,
     "",
@@ -90,14 +112,17 @@ export function resolveConfig(options: TelemetryOptions = {}): ResolvedConfig {
     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,
     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,

package/src/index.ts

@@ -15,7 +15,13 @@ 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 {

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";
@@ -40,7 +45,22 @@ export function log(message: string, options?: LogOptions): void {
       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 ?? {})) {

package/src/span.ts

@@ -23,7 +23,9 @@ import {
   PROPAGATED_KEY,
   propagatedFromContext,
   reportError,
+  sessionIdOf,
   withContext,
+  withSessionParent,
 } from "@telemetry-dev/otel";
 
 import {
@@ -171,19 +173,36 @@ export function createSpanHandle(
   options: StartSpanOptions = {},
 ): SpanHandle {
   const meta = metaFor(core, options);
-  const parentCtx = resolveParent(options.parent);
+  const resolved = resolveParent(options.parent);
+  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,
     {
       kind: options.kind ?? SpanKind.INTERNAL,
       startTime: options.startTime,
       links: options.links,
-      attributes: { "gen_ai.operation.name": SPAN_TYPE_OPERATIONS[meta.type] },
+      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");
@@ -266,7 +285,7 @@ export function startActiveSpan<T>(
   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);
 }