@telemetry-dev/sdk 0.1.5 → 0.1.6

package/README.md

@@ -90,12 +90,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.

package/dist/index.d.mts

@@ -59,6 +59,24 @@ interface TelemetryOptions {
   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;
@@ -207,4 +235,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 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

@@ -48,6 +48,10 @@ let activeClient;
 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();
 }
@@ -186,6 +190,137 @@ 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 {
+					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;
@@ -308,6 +443,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,
@@ -625,4 +769,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.6",
   "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,6 +11,235 @@ 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: 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 {
+          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;
 

package/src/client.ts

@@ -75,6 +75,12 @@ 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();
 }

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,