@telemetry-dev/sdk 0.1.5 → 0.1.7

package/README.md

@@ -55,11 +55,21 @@ Without an API key every call is a silent no-op — the SDK never throws into yo
 
 Other `init()` options: `enabled` (kill switch), `registerGlobal`, `exportMode: "batched" |
 "immediate"`, `captureInput` / `captureOutput`, `mask(value, { key })` redaction hook,
-`maxAttributeLength` (default 65536, truncated values end with `...[truncated]`), `batch`
+`maxAttributeLength` (a non-negative safe integer or `Infinity`; default 65536; `null` and
+`undefined` select the default, while other invalid values disable telemetry and are reported
+through `onError`; truncated values use `...[truncated]`, or its prefix when the cap is shorter than
+the marker; the cap also applies, with the marker, to string metadata and log attributes, and any
+other string attribute is cut at the cap without a marker, except that a cap of `0` leaves those at
+65536), `batch`
 (`maxExportBatchSize` 64, `scheduledDelayMillis` 1000, `maxQueueSize` 2048,
 `exportTimeoutMillis` 30000), `spanFilter`, `resourceAttributes`, `logLevel` (SDK diagnostics,
 default `"warn"`), `fetch`, `waitUntil`, `onError`.
 
+`captureInput: false` and `captureOutput: false` omit captured content. Provider integrations may
+still record non-content metadata such as response IDs and models, finish reasons, usage, timing,
+and errors. Capture flags do not gate stop sequences, tool descriptions and definitions (`gen_ai.tool.description`, `gen_ai.tool.definitions`), caller-supplied metadata or raw attributes,
+or exception messages and stack traces; redact those separately when needed.
+
 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.
@@ -90,12 +100,19 @@ The SDK installs the [session sampling wrapper](../otel/README.md#correlation-at
   context.
 - `extractW3cContext(carrier, options?)` / `injectW3cContext(context, carrier, options?)` — extract
   or inject W3C trace context. Baggage is omitted unless `includeBaggage` is true.
+- `captureEnabled("input" | "output")` — report whether the active initialized client permits that
+  capture direction. Returns `false` when no client is initialized.
+- `boundedCapture(value, options?)` — copy a JSON-compatible value within bounded work and retained
+  size. Defaults to 48 KiB, depth 32, and 1,000 traversal items. Returns `{ value, truncated }`;
+  `value` can be partial or `undefined` when a limit, cycle, getter, or skip rule prevents capture.
 - `flush()` / `shutdown()` — export pending data; required before serverless freeze/exit.
 
 Span types: `span` (default) | `generation` | `tool` | `agent` | `embedding` — mapped to
 `gen_ai.operation.name` `function` / `chat` / `execute_tool` / `invoke_agent` / `embeddings`.
 Generation fields (`model`, `provider`, `usage`, `costUsd`, sampling params, …) map to the OTel
-GenAI semantic conventions; cost is computed server-side from usage unless `costUsd` is set.
+GenAI semantic conventions. An explicit `costUsd` takes precedence; otherwise, the server estimates
+standard token cost when reported usage and matching model pricing are available. Missing pricing leaves cost
+unavailable, not zero, and does not prevent tracing or token accounting.
 
 Duration and token-usage histograms (`gen_ai.client.operation.duration`,
 `gen_ai.client.token.usage`) are recorded automatically for generation/agent/embedding/tool spans.
@@ -108,9 +125,13 @@ after the ended span passes `spanFilter`, including interrupted streams. Chunk t
 histogram state and does not retain individual intervals. Pull-based timing includes consumer delay
 between reads. An explicit timestamp uses the same monotonic millisecond clock for every chunk.
 
-Provider integrations feature-detect chunk recording. With an older core SDK that lacks
-`recordOutputChunk`, streams and existing tracing continue normally, but chunk-interval metrics are
-unavailable. Upgrade the core SDK with provider integrations to enable the new metric.
+Provider integrations feature-detect stream APIs. With an older core SDK that lacks the stream
+capture policy, streams are still traced with usage, model, finish reason, and timing, but output
+retention assumes the default 65536 limit and treats a mask as configured, so incomplete output is
+withheld. Instrumentation failures are not reported to `onError` with such a core. If only
+`recordOutputChunk` is unavailable, tracing and reconstruction continue but chunk-interval metrics
+are unavailable. Upgrade the core SDK with provider integrations to enable the full stream
+telemetry.
 
 ## Serverless
 

package/dist/index.d.mts

@@ -34,7 +34,7 @@ interface TelemetryOptions {
   captureOutput?: boolean;
   /** Redaction hook run on captured content before stringify/truncate. */
   mask?: MaskFn;
-  /** Truncation cap (chars) for content attributes; also set as the provider's attributeValueLengthLimit. Default 65536. */
+  /** Non-negative safe-integer truncation cap for content attributes; Infinity disables truncation. The cap also applies, with the marker, to string metadata and log attributes; any other string attribute is cut at the cap without a marker, except that a cap of 0 leaves those at 65536. init() reports invalid values through onError and returns a disabled client. Default 65536. */
   maxAttributeLength?: number;
   batch?: BatchOptions$1;
   /** Export filter. Default when registerGlobal: only spans from this SDK's instrumentation scope. */
@@ -53,12 +53,30 @@ interface TelemetryOptions {
   fetch?: typeof fetch;
   /** 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. */
+  /** Receives errors raised while emitting telemetry; repeated instrumentation failures from one stream may be coalesced into one report. The SDK never throws into user code. */
   onError?: (cause: Error) => void;
   /** Header value for a custom telemetry.dev integration. */
   sdkName?: string;
 }
 //#endregion
+//#region src/capture.d.ts
+interface BoundedCaptureOptions {
+  maxBytes?: number;
+  maxDepth?: number;
+  maxItems?: number;
+  skip?: (key: string, value: unknown, parent: unknown, path: readonly string[]) => boolean;
+}
+interface BoundedCaptureResult {
+  value: unknown;
+  truncated: boolean;
+}
+interface BoundedCaptureDetails extends BoundedCaptureResult {
+  bytes: number;
+  items: number;
+}
+declare function boundedCaptureDetails(input: unknown, options?: BoundedCaptureOptions): BoundedCaptureDetails;
+declare function boundedCapture(input: unknown, options?: BoundedCaptureOptions): BoundedCaptureResult;
+//#endregion
 //#region src/attrs.d.ts
 type SpanType = "span" | "generation" | "tool" | "agent" | "embedding";
 interface TokenUsage {
@@ -68,6 +86,15 @@ interface TokenUsage {
   cacheReadInputTokens?: number;
   cacheCreationInputTokens?: number;
   reasoningOutputTokens?: number;
+  textInputTokens?: number;
+  textOutputTokens?: number;
+  textCacheReadInputTokens?: number;
+  imageInputTokens?: number;
+  imageOutputTokens?: number;
+  imageCacheReadInputTokens?: number;
+  audioInputTokens?: number;
+  audioOutputTokens?: number;
+  audioCacheReadInputTokens?: number;
 }
 interface GenerationFields {
   model?: string;
@@ -126,6 +153,7 @@ interface TelemetryClient {
   /** Flush + teardown + unregister globals; the client becomes a no-op afterwards. */
   shutdown(): Promise<void>;
 }
+declare function captureEnabled(kind: "input" | "output"): boolean;
 declare function flush(): Promise<void>;
 declare function shutdown(): Promise<void>;
 declare function init(options?: TelemetryOptions, overrides?: ClientOverrides): TelemetryClient;
@@ -161,6 +189,11 @@ interface StartSpanOptions extends SpanFields {
   /** Per-call override of the global captureOutput. */
   captureOutput?: boolean;
 }
+interface SpanCapturePolicy {
+  readonly output: boolean;
+  readonly mask: boolean;
+  readonly maxAttributeLength: number;
+}
 interface SpanHandle {
   /** Raw OTel span (interop escape hatch). */
   readonly span: Span;
@@ -171,9 +204,11 @@ interface SpanHandle {
   /** W3C traceparent for this span; null for the no-op handle. */
   readonly traceparent: string | null;
   readonly isRecording: boolean;
+  readonly capturePolicy?: SpanCapturePolicy;
   update(fields: SpanFields): SpanHandle;
   /** Records an output chunk arrival. Pull-based streams include consumer delay between pulls. */
   recordOutputChunk(timestampMs?: number): void;
+  reportError?(cause: unknown): void;
   end(fields?: SpanFields & {
     endTime?: Date | number;
   }): void;
@@ -207,4 +242,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, 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 };
+export { type AgentFields, type BatchOptions, type BoundedCaptureDetails, type BoundedCaptureOptions, type BoundedCaptureResult, type ClientOverrides, type ExportMode, type GenerationFields, type LogLevel, type LogOptions, type MaskFn, type ObserveOptions, type ParentRef, type PropagatedAttributes, SCOPE_NAME, type SdkLogLevel, type SpanCapturePolicy, type SpanFields, type SpanHandle, type SpanType, type StartSpanOptions, type TelemetryClient, type TelemetryOptions, TelemetrySpanProcessor, type TelemetrySpanProcessorOptions, type TokenUsage, type ToolFields, activeContext, boundedCapture, boundedCaptureDetails, captureEnabled, extractW3cContext, flush, getTraceparent, init, injectW3cContext, log, observe, propagateAttributes, shutdown, startActiveSpan, startSpan, updateActiveSpan, withContext };

package/dist/index.mjs

@@ -5,9 +5,13 @@ import { BatchLogRecordProcessor, LoggerProvider, SimpleLogRecordProcessor } fro
 import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
 import { AlsContextManager, BATCHED_METRIC_INTERVAL_MS, DEFAULT_BASE_URL, DEFAULT_BATCH, DORMANT_INTERVAL_MS, DURATION_BUCKETS, OUTPUT_CHUNK_HISTOGRAM, PROPAGATED_KEY, SCOPE_NAME, SCOPE_NAME as SCOPE_NAME$1, SCOPE_VERSION, StampingSpanProcessor, TelemetrySpanProcessor, activeContext, activeContext as activeContext$1, als, createLogExporter, createMetricExporter, createMetricsPipeline, createTraceExporter, diag, jsonAttr, omitUndefined, otlpHeaders, propagateAttributes, propagatedFromContext, reportError, resolveEnv, sessionIdOf, sessionRootTracerProvider, sessionSampler, setLogLevel, withContext, withContext as withContext$1, withSessionParent } from "@telemetry-dev/otel";
 import { SeverityNumber } from "@opentelemetry/api-logs";
+//#region src/config.ts
+const DEFAULT_MAX_ATTRIBUTE_LENGTH = 65536;
 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 maxAttributeLength = options.maxAttributeLength == null ? DEFAULT_MAX_ATTRIBUTE_LENGTH : options.maxAttributeLength;
+	if (maxAttributeLength !== Number.POSITIVE_INFINITY && (!Number.isSafeInteger(maxAttributeLength) || maxAttributeLength < 0)) throw new RangeError("maxAttributeLength must be a non-negative safe integer or Infinity");
 	const baseUrl = (options.baseUrl ?? env.TELEMETRY_DEV_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
 	return {
 		apiKey: options.apiKey ?? env.TELEMETRY_DEV_API_KEY,
@@ -22,7 +26,7 @@ function resolveConfig(options = {}) {
 		captureInput: options.captureInput ?? true,
 		captureOutput: options.captureOutput ?? true,
 		mask: options.mask,
-		maxAttributeLength: options.maxAttributeLength ?? 65536,
+		maxAttributeLength,
 		batch: {
 			...DEFAULT_BATCH,
 			...options.batch
@@ -45,9 +49,20 @@ const NOOP_CLIENT = {
 	shutdown: () => Promise.resolve()
 };
 let activeClient;
+function shutdownClient(client, onError) {
+	try {
+		client.shutdown().catch((error) => reportError(onError, error));
+	} catch (error) {
+		reportError(onError, error instanceof Error ? error : new Error(String(error)));
+	}
+}
 function currentClient() {
 	return activeClient ?? NOOP_CLIENT;
 }
+function captureEnabled(kind) {
+	const config = currentClient().core?.config;
+	return kind === "input" ? config?.captureInput ?? false : config?.captureOutput ?? false;
+}
 function flush() {
 	return currentClient().flush();
 }
@@ -55,20 +70,22 @@ function shutdown() {
 	return currentClient().shutdown();
 }
 function init(options, overrides) {
+	const previousClient = activeClient;
 	try {
+		setLogLevel(options?.logLevel ?? "warn");
 		return initInner(options, overrides);
 	} catch (error) {
 		reportError(options?.onError, error instanceof Error ? error : new Error(String(error)));
-		activeClient = NOOP_CLIENT;
+		if (previousClient && previousClient !== NOOP_CLIENT) shutdownClient(previousClient, options?.onError);
+		if (activeClient === previousClient) activeClient = NOOP_CLIENT;
 		return NOOP_CLIENT;
 	}
 }
 function initInner(options, overrides) {
 	const config = resolveConfig(options);
-	setLogLevel(config.logLevel);
 	if (activeClient && activeClient !== NOOP_CLIENT) {
 		diag.warn("init() called again; replacing the previous client");
-		activeClient.shutdown().catch((error) => reportError(config.onError, error));
+		shutdownClient(activeClient, config.onError);
 	}
 	if (!(config.enabled && Boolean(config.apiKey ?? overrides?.spanExporter))) {
 		if (config.enabled && !config.apiKey) diag.debug("no api key (apiKey option or TELEMETRY_DEV_API_KEY); telemetry disabled");
@@ -108,11 +125,12 @@ function initInner(options, overrides) {
 		recordMetrics: metrics ? (span) => metrics.record(span) : void 0,
 		onError: config.onError
 	});
+	const backstopLength = config.maxAttributeLength || 65536;
 	const provider = new BasicTracerProvider({
 		resource,
 		sampler: sessionSampler(config.sampler),
 		spanProcessors: [processor],
-		spanLimits: { attributeValueLengthLimit: config.maxAttributeLength }
+		spanLimits: { attributeValueLengthLimit: backstopLength }
 	});
 	const tracer = provider.getTracer(SCOPE_NAME$1, SCOPE_VERSION);
 	let registeredTrace = false;
@@ -135,7 +153,7 @@ function initInner(options, overrides) {
 			const logProcessor = config.exportMode === "immediate" ? new SimpleLogRecordProcessor(logExporter) : new BatchLogRecordProcessor(logExporter);
 			const loggerProvider = new LoggerProvider({
 				resource,
-				logRecordLimits: { attributeValueLengthLimit: config.maxAttributeLength },
+				logRecordLimits: { attributeValueLengthLimit: backstopLength },
 				processors: [logProcessor]
 			});
 			logs = {
@@ -186,9 +204,148 @@ function initInner(options, overrides) {
 //#endregion
 //#region src/capture.ts
 const TRUNCATION_MARKER = "...[truncated]";
+const jsonStringByteLength = (value, limit) => {
+	let bytes = 2;
+	for (let index = 0; index < value.length && bytes <= limit; index += 1) {
+		const code = value.charCodeAt(index);
+		if (code === 34 || code === 92 || code === 8 || code === 9 || code === 10 || code === 12 || code === 13) bytes += 2;
+		else if (code < 32) bytes += 6;
+		else if (code < 128) bytes += 1;
+		else if (code < 2048) bytes += 2;
+		else if (code >= 55296 && code <= 56319) {
+			const next = value.charCodeAt(index + 1);
+			if (next >= 56320 && next <= 57343) {
+				bytes += 4;
+				index += 1;
+			} else bytes += 6;
+		} else if (code >= 56320 && code <= 57343) bytes += 6;
+		else bytes += 3;
+	}
+	return bytes;
+};
+const captureLimit = (name, value, fallback) => {
+	if (value === void 0) return fallback;
+	if (!Number.isSafeInteger(value) || value < 0) throw new RangeError(`${name} must be a non-negative safe integer`);
+	return value;
+};
+function boundedCaptureDetails(input, options = {}) {
+	const maxBytes = captureLimit("maxBytes", options.maxBytes, 48 * 1024);
+	const maxDepth = captureLimit("maxDepth", options.maxDepth, 32);
+	const maxItems = captureLimit("maxItems", options.maxItems, 1e3);
+	const ancestors = /* @__PURE__ */ new WeakSet();
+	let bytes = 0;
+	let items = 0;
+	let truncated = false;
+	const visit = (value, depth, path) => {
+		if (items >= maxItems) {
+			truncated = true;
+			return;
+		}
+		items += 1;
+		if (value === null || typeof value === "boolean" || typeof value === "number" || typeof value === "string") {
+			const length = typeof value === "string" ? jsonStringByteLength(value, maxBytes - bytes) : JSON.stringify(value)?.length ?? 0;
+			if (bytes + length > maxBytes) {
+				truncated = true;
+				return;
+			}
+			bytes += length;
+			return value;
+		}
+		if (typeof value !== "object") return void 0;
+		if (depth >= maxDepth || ancestors.has(value) || bytes + 2 > maxBytes) {
+			truncated = true;
+			return;
+		}
+		ancestors.add(value);
+		bytes += 2;
+		try {
+			if (Array.isArray(value)) {
+				const result = [];
+				for (const item of value) {
+					if (items >= maxItems) {
+						truncated = true;
+						break;
+					}
+					const previousBytes = bytes;
+					if (result.length > 0) bytes += 1;
+					const converted = visit(item, depth + 1, path);
+					if (converted === void 0) bytes = previousBytes;
+					else result.push(converted);
+				}
+				return result;
+			}
+			const result = {};
+			let emitted = false;
+			for (const key in value) {
+				if (items >= maxItems) {
+					truncated = true;
+					break;
+				}
+				if (!Object.hasOwn(value, key)) {
+					items += 1;
+					continue;
+				}
+				const keyBytes = jsonStringByteLength(key, maxBytes - bytes) + 1 + (emitted ? 1 : 0);
+				if (bytes + keyBytes > maxBytes) {
+					items += 1;
+					truncated = true;
+					continue;
+				}
+				let item;
+				try {
+					const descriptor = Object.getOwnPropertyDescriptor(value, key);
+					item = descriptor?.get ? descriptor.get.call(value) : descriptor?.value;
+					if (options.skip?.(key, item, value, path)) {
+						items += 1;
+						continue;
+					}
+				} catch {
+					items += 1;
+					truncated = true;
+					continue;
+				}
+				const previousBytes = bytes;
+				bytes += keyBytes;
+				const converted = visit(item, depth + 1, [...path, key]);
+				if (converted === void 0) bytes = previousBytes;
+				else {
+					if (key === "__proto__") Object.defineProperty(result, key, {
+						configurable: true,
+						enumerable: true,
+						value: converted,
+						writable: true
+					});
+					else result[key] = converted;
+					emitted = true;
+				}
+			}
+			return result;
+		} catch {
+			truncated = true;
+			return;
+		} finally {
+			ancestors.delete(value);
+		}
+	};
+	return {
+		value: visit(input, 0, []),
+		truncated,
+		bytes,
+		items
+	};
+}
+function boundedCapture(input, options = {}) {
+	const { value, truncated } = boundedCaptureDetails(input, options);
+	return {
+		value,
+		truncated
+	};
+}
 function truncate(value, maxLength) {
 	if (value.length <= maxLength) return value;
-	return value.slice(0, Math.max(maxLength - 14, 0)) + TRUNCATION_MARKER;
+	const limit = Math.max(maxLength, 0);
+	const marker = TRUNCATION_MARKER.slice(0, limit);
+	return value.slice(0, limit - marker.length) + marker;
 }
 /** The single content funnel: mask → JSON stringify → truncate. */
 function prepareCaptureValue(key, value, cfg) {
@@ -308,6 +465,15 @@ function fieldsToAttributes(fields, type, cfg) {
 		"gen_ai.usage.cache_read.input_tokens": fields.usage?.cacheReadInputTokens,
 		"gen_ai.usage.cache_creation.input_tokens": fields.usage?.cacheCreationInputTokens,
 		"gen_ai.usage.reasoning.output_tokens": fields.usage?.reasoningOutputTokens,
+		"gen_ai.usage.text.input_tokens": fields.usage?.textInputTokens,
+		"gen_ai.usage.text.output_tokens": fields.usage?.textOutputTokens,
+		"gen_ai.usage.text.cache_read.input_tokens": fields.usage?.textCacheReadInputTokens,
+		"gen_ai.usage.image.input_tokens": fields.usage?.imageInputTokens,
+		"gen_ai.usage.image.output_tokens": fields.usage?.imageOutputTokens,
+		"gen_ai.usage.image.cache_read.input_tokens": fields.usage?.imageCacheReadInputTokens,
+		"gen_ai.usage.audio.input_tokens": fields.usage?.audioInputTokens,
+		"gen_ai.usage.audio.output_tokens": fields.usage?.audioOutputTokens,
+		"gen_ai.usage.audio.cache_read.input_tokens": fields.usage?.audioCacheReadInputTokens,
 		"gen_ai.usage.cost": fields.costUsd,
 		"gen_ai.response.finish_reasons": fields.finishReason ? [fields.finishReason] : void 0,
 		"gen_ai.output.type": fields.outputType,
@@ -362,8 +528,14 @@ const NOOP_SPAN_HANDLE = {
 	spanId: INVALID_SPAN_CONTEXT.spanId,
 	traceparent: null,
 	isRecording: false,
+	capturePolicy: {
+		output: false,
+		mask: false,
+		maxAttributeLength: 0
+	},
 	update: () => NOOP_SPAN_HANDLE,
 	recordOutputChunk: () => {},
+	reportError: () => {},
 	end: () => {}
 };
 //#endregion
@@ -465,6 +637,11 @@ function createSpanHandle(core, name, options = {}) {
 		traceId: spanContext.traceId,
 		spanId: spanContext.spanId,
 		traceparent: `00-${spanContext.traceId}-${spanContext.spanId}-${flags}`,
+		capturePolicy: {
+			output: meta.capture.captureOutput,
+			mask: meta.capture.mask !== void 0,
+			maxAttributeLength: meta.capture.maxAttributeLength
+		},
 		get isRecording() {
 			return span.isRecording();
 		},
@@ -498,6 +675,9 @@ function createSpanHandle(core, name, options = {}) {
 			}
 			previousOutputChunkTime = now;
 		},
+		reportError(cause) {
+			reportError(meta.onError, cause instanceof Error ? cause : new Error(String(cause)));
+		},
 		end(fields) {
 			try {
 				if (fields) applyFields(span, meta, fields);
@@ -625,4 +805,4 @@ function observe(fn, options) {
 	return wrapped;
 }
 //#endregion
-export { SCOPE_NAME, TelemetrySpanProcessor, activeContext, extractW3cContext, flush, getTraceparent, init, injectW3cContext, log, observe, propagateAttributes, shutdown, startActiveSpan, startSpan, updateActiveSpan, withContext };
+export { SCOPE_NAME, TelemetrySpanProcessor, activeContext, boundedCapture, boundedCaptureDetails, captureEnabled, 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.5",
+  "version": "0.1.7",
   "description": "Pure TypeScript SDK for telemetry.dev: LLM traces, logs, and GenAI metrics on OpenTelemetry, for Node and edge runtimes.",
   "keywords": [
     "genai",

package/src/attrs.ts

@@ -32,6 +32,15 @@ export interface TokenUsage {
   cacheReadInputTokens?: number;
   cacheCreationInputTokens?: number;
   reasoningOutputTokens?: number;
+  textInputTokens?: number;
+  textOutputTokens?: number;
+  textCacheReadInputTokens?: number;
+  imageInputTokens?: number;
+  imageOutputTokens?: number;
+  imageCacheReadInputTokens?: number;
+  audioInputTokens?: number;
+  audioOutputTokens?: number;
+  audioCacheReadInputTokens?: number;
 }
 
 export interface GenerationFields {
@@ -103,6 +112,15 @@ export function fieldsToAttributes(
     "gen_ai.usage.cache_read.input_tokens": fields.usage?.cacheReadInputTokens,
     "gen_ai.usage.cache_creation.input_tokens": fields.usage?.cacheCreationInputTokens,
     "gen_ai.usage.reasoning.output_tokens": fields.usage?.reasoningOutputTokens,
+    "gen_ai.usage.text.input_tokens": fields.usage?.textInputTokens,
+    "gen_ai.usage.text.output_tokens": fields.usage?.textOutputTokens,
+    "gen_ai.usage.text.cache_read.input_tokens": fields.usage?.textCacheReadInputTokens,
+    "gen_ai.usage.image.input_tokens": fields.usage?.imageInputTokens,
+    "gen_ai.usage.image.output_tokens": fields.usage?.imageOutputTokens,
+    "gen_ai.usage.image.cache_read.input_tokens": fields.usage?.imageCacheReadInputTokens,
+    "gen_ai.usage.audio.input_tokens": fields.usage?.audioInputTokens,
+    "gen_ai.usage.audio.output_tokens": fields.usage?.audioOutputTokens,
+    "gen_ai.usage.audio.cache_read.input_tokens": fields.usage?.audioCacheReadInputTokens,
     "gen_ai.usage.cost": fields.costUsd,
     "gen_ai.response.finish_reasons": fields.finishReason ? [fields.finishReason] : undefined,
     "gen_ai.output.type": fields.outputType,

package/src/capture.ts

@@ -11,12 +11,252 @@ export interface CaptureConfig {
   onError?: (cause: Error) => void;
 }
 
+export interface BoundedCaptureOptions {
+  maxBytes?: number;
+  maxDepth?: number;
+  maxItems?: number;
+  skip?: (key: string, value: unknown, parent: unknown, path: readonly string[]) => boolean;
+}
+
+export interface BoundedCaptureResult {
+  value: unknown;
+  truncated: boolean;
+}
+
+export interface BoundedCaptureDetails extends BoundedCaptureResult {
+  bytes: number;
+  items: number;
+}
+
+interface CapturedObject {
+  [key: string]: CapturedValue;
+}
+
+type CapturedValue = null | boolean | number | string | CapturedValue[] | CapturedObject;
+
+const jsonStringByteLength = (value: string, limit: number) => {
+  let bytes = 2;
+
+  for (let index = 0; index < value.length && bytes <= limit; index += 1) {
+    const code = value.charCodeAt(index);
+
+    if (
+      code === 0x22 ||
+      code === 0x5c ||
+      code === 0x08 ||
+      code === 0x09 ||
+      code === 0x0a ||
+      code === 0x0c ||
+      code === 0x0d
+    ) {
+      bytes += 2;
+    } else if (code < 0x20) {
+      bytes += 6;
+    } else if (code < 0x80) {
+      bytes += 1;
+    } else if (code < 0x800) {
+      bytes += 2;
+    } else if (code >= 0xd800 && code <= 0xdbff) {
+      const next = value.charCodeAt(index + 1);
+
+      if (next >= 0xdc00 && next <= 0xdfff) {
+        bytes += 4;
+        index += 1;
+      } else {
+        bytes += 6;
+      }
+    } else if (code >= 0xdc00 && code <= 0xdfff) {
+      bytes += 6;
+    } else {
+      bytes += 3;
+    }
+  }
+
+  return bytes;
+};
+
+const captureLimit = (name: string, value: number | undefined, fallback: number) => {
+  if (value === undefined) return fallback;
+
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new RangeError(`${name} must be a non-negative safe integer`);
+  }
+
+  return value;
+};
+
+export function boundedCaptureDetails(
+  input: unknown,
+  options: BoundedCaptureOptions = {},
+): BoundedCaptureDetails {
+  const maxBytes = captureLimit("maxBytes", options.maxBytes, 48 * 1024);
+  const maxDepth = captureLimit("maxDepth", options.maxDepth, 32);
+  const maxItems = captureLimit("maxItems", options.maxItems, 1_000);
+  const ancestors = new WeakSet<object>();
+  let bytes = 0;
+  let items = 0;
+  let truncated = false;
+
+  const visit = (
+    value: unknown,
+    depth: number,
+    path: readonly string[],
+  ): CapturedValue | undefined => {
+    if (items >= maxItems) {
+      truncated = true;
+
+      return undefined;
+    }
+
+    items += 1;
+
+    if (
+      value === null ||
+      typeof value === "boolean" ||
+      typeof value === "number" ||
+      typeof value === "string"
+    ) {
+      const length =
+        typeof value === "string"
+          ? jsonStringByteLength(value, maxBytes - bytes)
+          : (JSON.stringify(value)?.length ?? 0);
+
+      if (bytes + length > maxBytes) {
+        truncated = true;
+
+        return undefined;
+      }
+
+      bytes += length;
+
+      return value;
+    }
+
+    if (typeof value !== "object") return undefined;
+
+    if (depth >= maxDepth || ancestors.has(value) || bytes + 2 > maxBytes) {
+      truncated = true;
+
+      return undefined;
+    }
+
+    ancestors.add(value);
+    bytes += 2;
+
+    try {
+      if (Array.isArray(value)) {
+        const result: CapturedValue[] = [];
+
+        for (const item of value) {
+          if (items >= maxItems) {
+            truncated = true;
+            break;
+          }
+
+          const previousBytes = bytes;
+
+          if (result.length > 0) bytes += 1;
+          const converted = visit(item, depth + 1, path);
+
+          if (converted === undefined) {
+            bytes = previousBytes;
+          } else {
+            result.push(converted);
+          }
+        }
+
+        return result;
+      }
+
+      const result = {} as CapturedObject;
+      let emitted = false;
+
+      for (const key in value) {
+        if (items >= maxItems) {
+          truncated = true;
+          break;
+        }
+
+        if (!Object.hasOwn(value, key)) {
+          items += 1;
+          continue;
+        }
+
+        const keyBytes = jsonStringByteLength(key, maxBytes - bytes) + 1 + (emitted ? 1 : 0);
+
+        if (bytes + keyBytes > maxBytes) {
+          items += 1;
+          truncated = true;
+          continue;
+        }
+
+        let item: unknown;
+
+        try {
+          const descriptor = Object.getOwnPropertyDescriptor(value, key);
+          item = descriptor?.get ? descriptor.get.call(value) : descriptor?.value;
+
+          if (options.skip?.(key, item, value, path)) {
+            items += 1;
+            continue;
+          }
+        } catch {
+          items += 1;
+          truncated = true;
+          continue;
+        }
+
+        const previousBytes = bytes;
+        bytes += keyBytes;
+        const converted = visit(item, depth + 1, [...path, key]);
+
+        if (converted === undefined) {
+          bytes = previousBytes;
+        } else {
+          if (key === "__proto__") {
+            Object.defineProperty(result, key, {
+              configurable: true,
+              enumerable: true,
+              value: converted,
+              writable: true,
+            });
+          } else {
+            result[key] = converted;
+          }
+
+          emitted = true;
+        }
+      }
+
+      return result;
+    } catch {
+      truncated = true;
+
+      return undefined;
+    } finally {
+      ancestors.delete(value);
+    }
+  };
+
+  return { value: visit(input, 0, []), truncated, bytes, items };
+}
+
+export function boundedCapture(
+  input: unknown,
+  options: BoundedCaptureOptions = {},
+): BoundedCaptureResult {
+  const { value, truncated } = boundedCaptureDetails(input, options);
+
+  return { value, truncated };
+}
+
 export function truncate(value: string, maxLength: number): string {
   if (value.length <= maxLength) return value;
 
-  // Total stays within maxLength so the provider's attributeValueLengthLimit backstop
-  // (set to the same cap) never slices the marker off.
-  return value.slice(0, Math.max(maxLength - TRUNCATION_MARKER.length, 0)) + TRUNCATION_MARKER;
+  const limit = Math.max(maxLength, 0);
+  const marker = TRUNCATION_MARKER.slice(0, limit);
+
+  return value.slice(0, limit - marker.length) + marker;
 }
 
 /** The single content funnel: mask → JSON stringify → truncate. */

package/src/client.ts

@@ -36,7 +36,12 @@ import {
   type Transport,
 } from "@telemetry-dev/otel";
 
-import { type ResolvedConfig, resolveConfig, type TelemetryOptions } from "./config.ts";
+import {
+  DEFAULT_MAX_ATTRIBUTE_LENGTH,
+  type ResolvedConfig,
+  resolveConfig,
+  type TelemetryOptions,
+} from "./config.ts";
 
 /** Test seam: inject in-memory exporters instead of the OTLP fetch transport. */
 export interface ClientOverrides {
@@ -71,10 +76,24 @@ const NOOP_CLIENT: ClientHandle = {
 
 let activeClient: ClientHandle | undefined;
 
+function shutdownClient(client: ClientHandle, onError?: (cause: Error) => void): void {
+  try {
+    void client.shutdown().catch((error: Error) => reportError(onError, error));
+  } catch (error) {
+    reportError(onError, error instanceof Error ? error : new Error(String(error)));
+  }
+}
+
 export function currentClient(): ClientHandle {
   return activeClient ?? NOOP_CLIENT;
 }
 
+export function captureEnabled(kind: "input" | "output"): boolean {
+  const config = currentClient().core?.config;
+
+  return kind === "input" ? (config?.captureInput ?? false) : (config?.captureOutput ?? false);
+}
+
 export function flush(): Promise<void> {
   return currentClient().flush();
 }
@@ -84,11 +103,20 @@ export function shutdown(): Promise<void> {
 }
 
 export function init(options?: TelemetryOptions, overrides?: ClientOverrides): TelemetryClient {
+  const previousClient = activeClient;
+
   try {
+    setLogLevel(options?.logLevel ?? "warn");
+
     return initInner(options, overrides);
   } catch (error) {
     reportError(options?.onError, error instanceof Error ? error : new Error(String(error)));
-    activeClient = NOOP_CLIENT;
+
+    if (previousClient && previousClient !== NOOP_CLIENT) {
+      shutdownClient(previousClient, options?.onError);
+    }
+
+    if (activeClient === previousClient) activeClient = NOOP_CLIENT;
 
     return NOOP_CLIENT;
   }
@@ -96,12 +124,11 @@ export function init(options?: TelemetryOptions, overrides?: ClientOverrides): T
 
 function initInner(options?: TelemetryOptions, overrides?: ClientOverrides): TelemetryClient {
   const config = resolveConfig(options);
-  setLogLevel(config.logLevel);
 
   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: Error) => reportError(config.onError, error));
+    shutdownClient(activeClient, config.onError);
   }
 
   const enabled = config.enabled && Boolean(config.apiKey ?? overrides?.spanExporter);
@@ -161,11 +188,14 @@ function initInner(options?: TelemetryOptions, overrides?: ClientOverrides): Tel
     onError: config.onError,
   });
 
+  // A zero cap only drops content; OpenTelemetry rejects it as a provider limit.
+  const backstopLength = config.maxAttributeLength || DEFAULT_MAX_ATTRIBUTE_LENGTH;
+
   const provider = new BasicTracerProvider({
     resource,
     sampler: sessionSampler(config.sampler),
     spanProcessors: [processor],
-    spanLimits: { attributeValueLengthLimit: config.maxAttributeLength },
+    spanLimits: { attributeValueLengthLimit: backstopLength },
   });
 
   const tracer = provider.getTracer(SCOPE_NAME, SCOPE_VERSION);
@@ -214,7 +244,7 @@ function initInner(options?: TelemetryOptions, overrides?: ClientOverrides): Tel
 
       const loggerProvider = new LoggerProvider({
         resource,
-        logRecordLimits: { attributeValueLengthLimit: config.maxAttributeLength },
+        logRecordLimits: { attributeValueLengthLimit: backstopLength },
         processors: [logProcessor],
       });
 

package/src/config.ts

@@ -40,7 +40,7 @@ export interface TelemetryOptions {
   captureOutput?: boolean;
   /** Redaction hook run on captured content before stringify/truncate. */
   mask?: MaskFn;
-  /** Truncation cap (chars) for content attributes; also set as the provider's attributeValueLengthLimit. Default 65536. */
+  /** Non-negative safe-integer truncation cap for content attributes; Infinity disables truncation. The cap also applies, with the marker, to string metadata and log attributes; any other string attribute is cut at the cap without a marker, except that a cap of 0 leaves those at 65536. init() reports invalid values through onError and returns a disabled client. Default 65536. */
   maxAttributeLength?: number;
   batch?: BatchOptions;
   /** Export filter. Default when registerGlobal: only spans from this SDK's instrumentation scope. */
@@ -59,7 +59,7 @@ export interface TelemetryOptions {
   fetch?: typeof fetch;
   /** 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. */
+  /** Receives errors raised while emitting telemetry; repeated instrumentation failures from one stream may be coalesced into one report. The SDK never throws into user code. */
   onError?: (cause: Error) => void;
   /** Header value for a custom telemetry.dev integration. */
   sdkName?: string;
@@ -104,6 +104,16 @@ export function resolveConfig(options: TelemetryOptions = {}): ResolvedConfig {
     throw new TypeError(`Invalid sessionMode: ${String(options.sessionMode)}`);
   }
 
+  const maxAttributeLength =
+    options.maxAttributeLength == null ? DEFAULT_MAX_ATTRIBUTE_LENGTH : options.maxAttributeLength;
+
+  if (
+    maxAttributeLength !== Number.POSITIVE_INFINITY &&
+    (!Number.isSafeInteger(maxAttributeLength) || maxAttributeLength < 0)
+  ) {
+    throw new RangeError("maxAttributeLength must be a non-negative safe integer or Infinity");
+  }
+
   const baseUrl = (options.baseUrl ?? env.TELEMETRY_DEV_BASE_URL ?? DEFAULT_BASE_URL).replace(
     /\/+$/,
     "",
@@ -122,7 +132,7 @@ export function resolveConfig(options: TelemetryOptions = {}): ResolvedConfig {
     captureInput: options.captureInput ?? true,
     captureOutput: options.captureOutput ?? true,
     mask: options.mask,
-    maxAttributeLength: options.maxAttributeLength ?? DEFAULT_MAX_ATTRIBUTE_LENGTH,
+    maxAttributeLength,
     batch: { ...DEFAULT_BATCH, ...options.batch },
     spanFilter: options.spanFilter,
     sessionRootOf: options.sessionRootOf,

package/src/index.ts

@@ -7,7 +7,14 @@ export type {
   ToolFields,
 } from "./attrs.ts";
 
-export { type ClientOverrides, flush, init, shutdown, type TelemetryClient } from "./client.ts";
+export {
+  captureEnabled,
+  type ClientOverrides,
+  flush,
+  init,
+  shutdown,
+  type TelemetryClient,
+} from "./client.ts";
 
 export type {
   BatchOptions,
@@ -18,6 +25,14 @@ export type {
   TelemetryOptions,
 } from "./config.ts";
 
+export {
+  boundedCapture,
+  boundedCaptureDetails,
+  type BoundedCaptureDetails,
+  type BoundedCaptureOptions,
+  type BoundedCaptureResult,
+} from "./capture.ts";
+
 export {
   propagateAttributes,
   type PropagatedAttributes,
@@ -36,6 +51,7 @@ export {
   getTraceparent,
   injectW3cContext,
   type ParentRef,
+  type SpanCapturePolicy,
   type SpanHandle,
   startActiveSpan,
   startSpan,

package/src/noop.ts

@@ -12,7 +12,9 @@ export const NOOP_SPAN_HANDLE: SpanHandle = {
   spanId: INVALID_SPAN_CONTEXT.spanId,
   traceparent: null,
   isRecording: false,
+  capturePolicy: { output: false, mask: false, maxAttributeLength: 0 },
   update: () => NOOP_SPAN_HANDLE,
   recordOutputChunk: () => {},
+  reportError: () => {},
   end: () => {},
 };

package/src/span.ts

@@ -59,6 +59,12 @@ export interface StartSpanOptions extends SpanFields {
   captureOutput?: boolean;
 }
 
+export interface SpanCapturePolicy {
+  readonly output: boolean;
+  readonly mask: boolean;
+  readonly maxAttributeLength: number;
+}
+
 export interface SpanHandle {
   /** Raw OTel span (interop escape hatch). */
   readonly span: Span;
@@ -69,9 +75,11 @@ export interface SpanHandle {
   /** W3C traceparent for this span; null for the no-op handle. */
   readonly traceparent: string | null;
   readonly isRecording: boolean;
+  readonly capturePolicy?: SpanCapturePolicy;
   update(fields: SpanFields): SpanHandle;
   /** Records an output chunk arrival. Pull-based streams include consumer delay between pulls. */
   recordOutputChunk(timestampMs?: number): void;
+  reportError?(cause: unknown): void;
   end(fields?: SpanFields & { endTime?: Date | number }): void;
 }
 
@@ -240,6 +248,11 @@ export function createSpanHandle(
     traceId: spanContext.traceId,
     spanId: spanContext.spanId,
     traceparent: `00-${spanContext.traceId}-${spanContext.spanId}-${flags}`,
+    capturePolicy: {
+      output: meta.capture.captureOutput,
+      mask: meta.capture.mask !== undefined,
+      maxAttributeLength: meta.capture.maxAttributeLength,
+    },
     get isRecording() {
       return span.isRecording();
     },
@@ -287,6 +300,9 @@ export function createSpanHandle(
 
       previousOutputChunkTime = now;
     },
+    reportError(cause) {
+      reportError(meta.onError, cause instanceof Error ? cause : new Error(String(cause)));
+    },
     end(fields) {
       try {
         if (fields) applyFields(span, meta, fields);