@telemetry-dev/sdk 0.1.1 → 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).

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
@@ -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. */
@@ -195,4 +203,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,7 +3,7 @@ import { CompositePropagator, W3CBaggagePropagator, W3CTraceContextPropagator, p
 import { resourceFromAttributes } from "@opentelemetry/resources";
 import { BatchLogRecordProcessor, LoggerProvider, SimpleLogRecordProcessor } from "@opentelemetry/sdk-logs";
 import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
-import { AlsContextManager, BATCHED_METRIC_INTERVAL_MS, DEFAULT_BASE_URL, DEFAULT_BATCH, DORMANT_INTERVAL_MS, PROPAGATED_KEY, SCOPE_NAME, SCOPE_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();
@@ -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,6 +26,7 @@ function resolveConfig(options = {}) {
 			...options.batch
 		},
 		spanFilter: options.spanFilter,
+		sessionRootOf: options.sessionRootOf,
 		resourceAttributes: options.resourceAttributes,
 		logLevel: options.logLevel ?? "warn",
 		fetchImpl: options.fetch ?? globalThis.fetch,
@@ -94,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");
@@ -132,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()
 			};
@@ -420,15 +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: 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 +503,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 +585,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.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.1"
+    "@telemetry-dev/otel": "^0.1.2"
   },
   "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,
@@ -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));
     }

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";
@@ -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. */
@@ -62,12 +71,14 @@ 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;
@@ -92,12 +103,14 @@ 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,

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/span.ts

@@ -23,7 +23,9 @@ import {
   PROPAGATED_KEY,
   propagatedFromContext,
   reportError,
+  sessionIdOf,
   withContext,
+  withSessionParent,
 } from "@telemetry-dev/otel";
 
 import {
@@ -171,19 +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: 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 +281,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);
 }