@telemetry-dev/sdk 0.1.2 → 0.1.3

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.

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). */

package/dist/index.mjs

@@ -7,6 +7,7 @@ import { AlsContextManager, BATCHED_METRIC_INTERVAL_MS, DEFAULT_BASE_URL, DEFAUL
 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;
@@ -425,7 +435,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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telemetry-dev/sdk",
-  "version": "0.1.2",
+  "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.2"
+    "@telemetry-dev/otel": "^0.1.3"
   },
   "devDependencies": {
     "@opentelemetry/api": "^1.9.1",

package/src/client.ts

@@ -112,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,

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,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(
     /\/+$/,
     "",
@@ -101,6 +112,7 @@ 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,

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

@@ -174,11 +174,15 @@ 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,