feat(core): add stringify helper and make AI-tracing serializers safe

packages/core/src/shared-exports.ts

@@ -322,7 +322,7 @@ export {
  stackParserFromStackParserOptions,
  stripSentryFramesAndReverse,
 } from './utils/stacktrace';
-export { isMatchingPattern, safeJoin, snipLine, stringMatchesSomePattern, truncate } from './utils/string';
+export { isMatchingPattern, safeJoin, stringify, snipLine, stringMatchesSomePattern, truncate } from './utils/string';
 export {
  isNativeFunction,
  supportsDOMException,

packages/core/src/tracing/ai/utils.ts

@@ -192,34 +192,23 @@ export function endStreamSpan(span: Span, state: StreamResponseState, recordOutp
 }
 
 /**
- * Serialize a value to a JSON string without truncation.
- * Strings are returned as-is, arrays and objects are JSON-stringified.
- */
-export function getJsonString<T>(value: T | T[]): string {
- if (typeof value === 'string') {
- return value;
- }
- return JSON.stringify(value);
-}
-
-/**
- * Get the truncated JSON string for a string or array of strings.
+ * Get the truncated JSON string for a string, an array of messages, or an object.
  *
- * @param value - The string or array of strings to truncate
+ * @param value - The value to truncate and serialize
  * @returns The truncated JSON string
  */
 export function getTruncatedJsonString<T>(value: T | T[]): string {
  if (typeof value === 'string') {
  // Some values are already JSON strings, so we don't need to duplicate the JSON parsing
  return truncateGenAiStringInput(value);
  }
- if (Array.isArray(value)) {
- // truncateGenAiMessages returns an array of strings, so we need to stringify it
- const truncatedMessages = truncateGenAiMessages(value);
- return JSON.stringify(truncatedMessages);
+ // Both truncation (media stripping recurses the value) and `JSON.stringify` can throw on
+ // circular refs or non-serializable values (e.g. BigInt); never let that crash instrumentation.
+ try {
+ return JSON.stringify(Array.isArray(value) ? truncateGenAiMessages(value) : value);
+ } catch {
+ return '[unserializable]';
  }
- // value is an object, so we need to stringify it
- return JSON.stringify(value);
 }
 
 /**

packages/core/src/tracing/anthropic-ai/utils.ts

@@ -7,7 +7,8 @@ import {
  GEN_AI_INPUT_MESSAGES_ORIGINAL_LENGTH_ATTRIBUTE,
  GEN_AI_SYSTEM_INSTRUCTIONS_ATTRIBUTE,
 } from '../ai/gen-ai-attributes';
-import { extractSystemInstructions, getJsonString, getTruncatedJsonString } from '../ai/utils';
+import { extractSystemInstructions, getTruncatedJsonString } from '../ai/utils';
+import { stringify } from '../../utils/string';
 import type { AnthropicAiResponse } from './types';
 
 /**
@@ -31,7 +32,7 @@ export function setMessagesAttribute(span: Span, messages: unknown, enableTrunca
  span.setAttributes({
  [GEN_AI_INPUT_MESSAGES_ATTRIBUTE]: enableTruncation
  ? getTruncatedJsonString(filteredMessages)
- : getJsonString(filteredMessages),
+ : stringify(filteredMessages),
  [GEN_AI_INPUT_MESSAGES_ORIGINAL_LENGTH_ATTRIBUTE]: filteredLength,
  });
 }

packages/core/src/tracing/google-genai/index.ts

@@ -28,10 +28,10 @@ import {
  GEN_AI_USAGE_TOTAL_TOKENS_ATTRIBUTE,
 } from '../ai/gen-ai-attributes';
 import type { InstrumentedMethodEntry } from '../ai/utils';
+import { stringify } from '../../utils/string';
 import {
  buildMethodPath,
  extractSystemInstructions,
- getJsonString,
  getTruncatedJsonString,
  resolveAIRecordingOptions,
  shouldEnableTruncation,
@@ -197,7 +197,7 @@ export function addPrivateRequestAttributes(
  [GEN_AI_INPUT_MESSAGES_ORIGINAL_LENGTH_ATTRIBUTE]: filteredLength,
  [GEN_AI_INPUT_MESSAGES_ATTRIBUTE]: enableTruncation
  ? getTruncatedJsonString(filteredMessages)
- : getJsonString(filteredMessages),
+ : stringify(filteredMessages),
  });
  }
 }

packages/core/src/tracing/langchain/utils.ts

@@ -1,5 +1,6 @@
 import { SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '../../semanticAttributes';
 import type { SpanAttributeValue } from '../../types/span';
+import { stringify } from '../../utils/string';
 import {
  GEN_AI_AGENT_NAME_ATTRIBUTE,
  GEN_AI_INPUT_MESSAGES_ATTRIBUTE,
@@ -27,7 +28,7 @@ import {
  GEN_AI_USAGE_TOTAL_TOKENS_ATTRIBUTE,
 } from '../ai/gen-ai-attributes';
 import { isContentMedia, stripInlineMediaFromSingleMessage } from '../ai/mediaStripping';
-import { extractSystemInstructions, getJsonString, getTruncatedJsonString } from '../ai/utils';
+import { extractSystemInstructions, getTruncatedJsonString } from '../ai/utils';
 import { LANGCHAIN_ORIGIN, ROLE_MAP } from './constants';
 import type { LangChainLLMResult, LangChainMessage, LangChainSerialized } from './types';
 
@@ -37,32 +38,23 @@ import type { LangChainLLMResult, LangChainMessage, LangChainSerialized } from '
  * We keep this tiny helper because call sites are repetitive and easy to miswrite.
  * It also preserves falsy-but-valid values like `0` and `""`.
  */
-const setIfDefined = (target: Record<string, SpanAttributeValue>, key: string, value: unknown): void => {
+const setIfDefined = (target: Record<string, SpanAttributeValue | undefined>, key: string, value: unknown): void => {
  if (value != null) target[key] = value as SpanAttributeValue;
 };
 
 /**
  * Like `setIfDefined`, but converts the value with `Number()` and skips only when the
  * result is `NaN`. This ensures numeric 0 makes it through (unlike truthy checks).
  */
-const setNumberIfDefined = (target: Record<string, SpanAttributeValue>, key: string, value: unknown): void => {
+const setNumberIfDefined = (
+ target: Record<string, SpanAttributeValue | undefined>,
+ key: string,
+ value: unknown,
+): void => {
  const n = Number(value);
  if (!Number.isNaN(n)) target[key] = n;
 };
 
-/**
- * Converts a value to a string. Avoids double-quoted JSON strings where a plain
- * string is desired, but still handles objects/arrays safely.
- */
-function asString(v: unknown): string {
- if (typeof v === 'string') return v;
- try {
- return JSON.stringify(v);
- } catch {
- return String(v);
- }
-}
-
 /**
  * Converts message content to a string, stripping inline media (base64 images, audio, etc.)
  * from multimodal content before stringification so downstream media stripping can't miss it.
@@ -78,10 +70,10 @@ function asString(v: unknown): string {
  * ])
  * // => '[{"type":"text","text":"What color?"},{"type":"image_url","image_url":{"url":"[Blob substitute]"}}]'
  *
- * // Without this, asString() would JSON.stringify the raw array and the base64 blob
+ * // Without this, stringification would JSON.stringify the raw array and the base64 blob
  * // would end up in span attributes, since downstream stripping only works on objects.
  */
-function normalizeContent(v: unknown): string {
+function normalizeContent(v: unknown): string | undefined {
  if (Array.isArray(v)) {
  try {
  const stripped = v.map(part =>
@@ -92,7 +84,7 @@ function normalizeContent(v: unknown): string {
  return String(v);
  }
  }
- return asString(v);
+ return stringify(v, String);
 }
 
 /**
@@ -148,7 +140,9 @@ export function getInvocationParams(tags?: string[] | Record<string, unknown>):
  * @param messages Mixed LangChain messages
  * @returns Array of normalized `{ role, content }`
  */
-export function normalizeLangChainMessages(messages: LangChainMessage[]): Array<{ role: string; content: string }> {
+export function normalizeLangChainMessages(
+ messages: LangChainMessage[],
+): Array<{ role: string; content: string | undefined }> {
  return messages.map(message => {
  // 1) Prefer _getType() when present
  const maybeGetType = (message as { _getType?: () => string })._getType;
@@ -262,11 +256,11 @@ function baseRequestAttributes(
  serialized: LangChainSerialized,
  invocationParams?: Record<string, unknown>,
  langSmithMetadata?: Record<string, unknown>,
-): Record<string, SpanAttributeValue> {
+): Record<string, SpanAttributeValue | undefined> {
  return {
- [GEN_AI_SYSTEM_ATTRIBUTE]: asString(system ?? 'langchain'),
+ [GEN_AI_SYSTEM_ATTRIBUTE]: stringify(system ?? 'langchain', String),
  [GEN_AI_OPERATION_NAME_ATTRIBUTE]: 'chat',
- [GEN_AI_REQUEST_MODEL_ATTRIBUTE]: asString(modelName),
+ [GEN_AI_REQUEST_MODEL_ATTRIBUTE]: stringify(modelName, String),
  [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: LANGCHAIN_ORIGIN,
  ...extractCommonRequestAttributes(serialized, invocationParams, langSmithMetadata),
  };
@@ -287,7 +281,7 @@ export function extractLLMRequestAttributes(
  enableTruncation: boolean,
  invocationParams?: Record<string, unknown>,
  langSmithMetadata?: Record<string, unknown>,
-): Record<string, SpanAttributeValue> {
+): Record<string, SpanAttributeValue | undefined> {
  const system = langSmithMetadata?.ls_provider;
  const modelName = invocationParams?.model ?? langSmithMetadata?.ls_model_name ?? 'unknown';
 
@@ -299,7 +293,7 @@ export function extractLLMRequestAttributes(
  setIfDefined(
  attrs,
  GEN_AI_INPUT_MESSAGES_ATTRIBUTE,
- enableTruncation ? getTruncatedJsonString(messages) : getJsonString(messages),
+ enableTruncation ? getTruncatedJsonString(messages) : stringify(messages),
  );
  }
 
@@ -322,7 +316,7 @@ export function extractChatModelRequestAttributes(
  enableTruncation: boolean,
  invocationParams?: Record<string, unknown>,
  langSmithMetadata?: Record<string, unknown>,
-): Record<string, SpanAttributeValue> {
+): Record<string, SpanAttributeValue | undefined> {
  const system = langSmithMetadata?.ls_provider ?? llm.id?.[2];
  const modelName = invocationParams?.model ?? langSmithMetadata?.ls_model_name ?? 'unknown';
 
@@ -343,7 +337,7 @@ export function extractChatModelRequestAttributes(
  setIfDefined(
  attrs,
  GEN_AI_INPUT_MESSAGES_ATTRIBUTE,
- enableTruncation ? getTruncatedJsonString(filteredMessages) : getJsonString(filteredMessages),
+ enableTruncation ? getTruncatedJsonString(filteredMessages) : stringify(filteredMessages),
  );
  }
 
@@ -378,7 +372,7 @@ function addToolCallsAttributes(generations: LangChainMessage[][], attrs: Record
  }
 
  if (toolCalls.length > 0) {
- setIfDefined(attrs, GEN_AI_RESPONSE_TOOL_CALLS_ATTRIBUTE, asString(toolCalls));
+ setIfDefined(attrs, GEN_AI_RESPONSE_TOOL_CALLS_ATTRIBUTE, stringify(toolCalls, String));
  }
 }
 
@@ -466,7 +460,7 @@ export function extractLlmResponseAttributes(
  .filter((r): r is string => typeof r === 'string');
 
  if (finishReasons.length > 0) {
- setIfDefined(attrs, GEN_AI_RESPONSE_FINISH_REASONS_ATTRIBUTE, asString(finishReasons));
+ setIfDefined(attrs, GEN_AI_RESPONSE_FINISH_REASONS_ATTRIBUTE, stringify(finishReasons, String));
  }
 
  // Tool calls metadata (names, IDs) are not PII, so capture them regardless of recordOutputs
@@ -479,7 +473,7 @@ export function extractLlmResponseAttributes(
  .filter(t => typeof t === 'string');
 
  if (texts.length > 0) {
- setIfDefined(attrs, GEN_AI_RESPONSE_TEXT_ATTRIBUTE, asString(texts));
+ setIfDefined(attrs, GEN_AI_RESPONSE_TEXT_ATTRIBUTE, stringify(texts, String));
  }
  }
  }
@@ -506,7 +500,7 @@ export function extractLlmResponseAttributes(
  // Stop reason: v1 stores this in message.response_metadata.finish_reason
  const stopReason = llmOutput?.stop_reason ?? v1Message?.response_metadata?.finish_reason;
  if (stopReason) {
- setIfDefined(attrs, GEN_AI_RESPONSE_STOP_REASON_ATTRIBUTE, asString(stopReason));
+ setIfDefined(attrs, GEN_AI_RESPONSE_STOP_REASON_ATTRIBUTE, stringify(stopReason, String));
  }
 
  return attrs;

packages/core/src/tracing/langgraph/index.ts

@@ -15,11 +15,11 @@ import {
 } from '../ai/gen-ai-attributes';
 import {
  extractSystemInstructions,
- getJsonString,
  getTruncatedJsonString,
  resolveAIRecordingOptions,
  shouldEnableTruncation,
 } from '../ai/utils';
+import { stringify } from '../../utils/string';
 import { createLangChainCallbackHandler } from '../langchain';
 import type { BaseChatModel, LangChainMessage } from '../langchain/types';
 import { normalizeLangChainMessages } from '../langchain/utils';
@@ -210,7 +210,7 @@ function instrumentCompiledGraphInvoke(
  span.setAttributes({
  [GEN_AI_INPUT_MESSAGES_ATTRIBUTE]: enableTruncation
  ? getTruncatedJsonString(filteredMessages)
- : getJsonString(filteredMessages),
+ : stringify(filteredMessages),
  [GEN_AI_INPUT_MESSAGES_ORIGINAL_LENGTH_ATTRIBUTE]: filteredLength,
  });
  }

packages/core/src/tracing/openai/index.ts

@@ -16,10 +16,10 @@ import {
  GEN_AI_SYSTEM_INSTRUCTIONS_ATTRIBUTE,
 } from '../ai/gen-ai-attributes';
 import type { InstrumentedMethodEntry } from '../ai/utils';
+import { stringify } from '../../utils/string';
 import {
  buildMethodPath,
  extractSystemInstructions,
- getJsonString,
  getTruncatedJsonString,
  resolveAIRecordingOptions,
  shouldEnableTruncation,
@@ -128,7 +128,7 @@ export function addRequestAttributes(
 
  span.setAttribute(
  GEN_AI_INPUT_MESSAGES_ATTRIBUTE,
- enableTruncation ? getTruncatedJsonString(filteredMessages) : getJsonString(filteredMessages),
+ enableTruncation ? getTruncatedJsonString(filteredMessages) : stringify(filteredMessages),
  );
 
  if (Array.isArray(filteredMessages)) {

packages/core/src/tracing/vercel-ai/utils.ts

@@ -10,7 +10,8 @@ import {
  GEN_AI_USAGE_INPUT_TOKENS_ATTRIBUTE,
  GEN_AI_USAGE_OUTPUT_TOKENS_ATTRIBUTE,
 } from '../ai/gen-ai-attributes';
-import { extractSystemInstructions, getJsonString, getTruncatedJsonString } from '../ai/utils';
+import { extractSystemInstructions, getTruncatedJsonString } from '../ai/utils';
+import { stringify } from '../../utils/string';
 import { toolCallSpanContextMap } from './constants';
 import type { TokenSummary, ToolCallSpanContext } from './types';
 import { AI_PROMPT_ATTRIBUTE, AI_PROMPT_MESSAGES_ATTRIBUTE } from './vercel-ai-attributes';
@@ -241,9 +242,7 @@ export function requestMessagesFromPrompt(span: Span, attributes: SpanAttributes
  }
 
  const filteredLength = Array.isArray(filteredMessages) ? filteredMessages.length : 0;
- const messagesJson = enableTruncation
- ? getTruncatedJsonString(filteredMessages)
- : getJsonString(filteredMessages);
+ const messagesJson = enableTruncation ? getTruncatedJsonString(filteredMessages) : stringify(filteredMessages);
 
  span.setAttributes({
  [AI_PROMPT_ATTRIBUTE]: messagesJson,
@@ -275,7 +274,7 @@ export function requestMessagesFromPrompt(span: Span, attributes: SpanAttributes
  ? originalMessagesJson
  : enableTruncation
  ? getTruncatedJsonString(filteredMessages)
- : getJsonString(filteredMessages);
+ : stringify(filteredMessages);
 
  span.setAttributes({
  [AI_PROMPT_MESSAGES_ATTRIBUTE]: messagesJson,

packages/core/src/utils/string.ts

@@ -3,6 +3,31 @@ import { stringifyValue } from './normalize';
 
 export { escapeStringForRegex } from '../vendor/escapeStringForRegex';
 
+/**
+ * Coerce a value to a string without ever throwing. Strings pass through unchanged (so an
+ * already-serialized value isn't double-encoded and a plain string isn't wrapped in quotes);
+ * anything else is `JSON.stringify`-ed, falling back to `fallback` if that throws (e.g. on
+ * circular references or `BigInt`). Returns `undefined` for values `JSON.stringify` itself drops
+ * (top-level `undefined`, functions, symbols), matching `JSON.stringify`'s own runtime behavior.
+ *
+ * @param value the value to stringify
+ * @param fallback returned when serialization throws, or, if a function, called with `value` to
+ * produce the fallback. Defaults to `'[unserializable]'`.
+ */
+export function stringify(
+ value: unknown,
+ fallback: string | ((value: unknown) => string) = '[unserializable]',
+): string | undefined {
+ if (typeof value === 'string') {
+ return value;
+ }
+ try {
+ return JSON.stringify(value);
+ } catch {
+ return typeof fallback === 'function' ? fallback(value) : fallback;
+ }
+}
+
 /**
  * Truncates given string to the maximum characters count
  *

packages/core/test/lib/tracing/ai-message-truncation.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { truncateGenAiMessages, truncateGenAiStringInput } from '../../../src/tracing/ai/messageTruncation';
+import { getTruncatedJsonString } from '../../../src/tracing/ai/utils';
 
 describe('message truncation utilities', () => {
  describe('truncateGenAiMessages', () => {
@@ -610,3 +611,18 @@ describe('message truncation utilities', () => {
  });
  });
 });
+
+describe('getTruncatedJsonString', () => {
+ it('returns a fallback instead of throwing on circular references', () => {
+ const circular: Record<string, unknown> = { role: 'user', content: 'hi' };
+ circular.self = circular;
+
+ expect(getTruncatedJsonString(circular)).toBe('[unserializable]');
+ expect(getTruncatedJsonString([circular])).toBe('[unserializable]');
+ });
+
+ it('serializes normal values as before', () => {
+ expect(getTruncatedJsonString('hello')).toBe('hello');
+ expect(getTruncatedJsonString({ a: 1 })).toBe('{"a":1}');
+ });
+});