sentry-setup-ai-monitoring

所有技能 > 功能设置 > AI 监控

设置 Sentry AI Agent 监控

配置 Sentry，以跟踪大模型调用、Agent 执行、工具使用和 Token 消耗。

在以下情况下调用此技能

• 用户询问“监控 AI/大模型调用”或“跟踪 OpenAI/Anthropic 使用情况”
• 用户希望实现“AI 可观测性”或“Agent 监控”
• 用户询问 Token 使用量、模型延迟或 AI 成本

重要： 以下 SDK 版本、API 名称和代码示例仅供参考。实现前请务必查阅 docs.sentry.io 确认，因为 API 和最低版本要求可能已有变化。

前提条件

AI 监控要求启用跟踪（tracesSampleRate > 0）。

如果应用包含多轮对话，请在适当位置默认设置会话 ID，以便识别聊天会话。Sentry 使用 gen_ai.conversation.id 将相关 AI Span 归为同一对话。部分集成会自动推断此 ID，但许多配置需要显式设置。

数据捕获警告

记录提示词和输出会捕获可能包含个人身份信息（PII）的用户内容。 在 JavaScript 中，genAI 输入/输出捕获默认开启（由 dataCollection.genAI 控制）；在 Python 中，通过 send_default_pii=True 启用；在 Laravel 中，通过 SENTRY_SEND_DEFAULT_PII=true 启用。在依赖此类捕获（或针对各集成的覆盖选项——JS 中的 recordInputs/recordOutputs、Python 中的 include_prompts）之前，请确认：

• 应用的隐私政策允许捕获用户提示词和模型响应
• 捕获的数据符合适用法规（GDPR、CCPA 等）
• Sentry 数据保留设置适合数据的敏感程度

请询问用户是否希望启用提示词/输出捕获。未经明确确认，不要启用提示词/输出捕获。tracesSampleRate: 1.0 仅用于开发环境；在生产环境中，请使用较低的值或 tracesSampler 函数。

先检测

配置前务必检测已安装的 AI SDK：

# JavaScript
grep -E '"(openai|@anthropic-ai/sdk|ai|@langchain|@google/genai)"' package.json

# Python
grep -E '(openai|anthropic|langchain|huggingface)' requirements.txt pyproject.toml 2>/dev/null

# PHP / Laravel
grep -E '"(laravel/ai|openai-php|openai/|anthropic|llm)' composer.json 2>/dev/null
ls artisan 2>/dev/null && echo "Laravel detected"

采样检查

检测到 AI SDK 后，请检查当前采样配置：

# JavaScript
grep -E 'tracesSampleRate|tracesSampler' sentry.*.config.* instrument.* src/instrument.* app/instrument.* 2>/dev/null

# Python
grep -E 'traces_sample_rate|traces_sampler' *.py **/*.py 2>/dev/null

# PHP / Laravel
grep -E 'SENTRY_TRACES_SAMPLE_RATE|traces_sample_rate|traces_sampler' .env config/sentry.php 2>/dev/null

如果 tracesSampleRate / traces_sample_rate 低于 1.0，且未配置 tracesSampler / traces_sampler：

询问用户：

“您当前的采样率为 {rate}。Agent 运行会按完整的 Span 树进行采样——如果根 Span 被丢弃，所有子级 gen_ai Span 都会丢失。要全面了解 AI 活动，gen_ai 相关事务应以 100% 的采样率进行采样。您希望我设置一个 tracesSampler，以 100% 采样 AI 跟踪，同时按当前采样率采样其他流量吗？”

如果用户确认，请阅读 ${SKILL_ROOT}/references/sampling.md，了解实现模式。

支持的 SDK

JavaScript

包	集成	Sentry SDK 最低版本	自动？
openai	openAIIntegration()	10.53.0	是
@anthropic-ai/sdk	anthropicAIIntegration()	10.53.0	是
ai（Vercel）	vercelAIIntegration()	10.53.0	是*
@langchain/*	langChainIntegration()	10.53.0	是
@langchain/langgraph	langGraphIntegration()	10.53.0	是
@google/genai	googleGenAIIntegration()	10.53.0	是

*Vercel AI：需要 10.53.0 或更高版本。每次调用都需要设置 experimental_telemetry。

Python

安装 AI 包后，集成会自动启用——无需显式注册：

包	自动？	备注
openai	是	包含 OpenAI Agents SDK
anthropic	是
langchain / langgraph	是
huggingface_hub	是
google-genai	是
pydantic-ai	是
litellm	否	需要显式集成
mcp（模型上下文协议）	是

PHP / Laravel

Package	Integration	Min Sentry SDK	Auto?
laravel/ai	sentry/sentry-laravel 中的 Laravel AI 插桩	4.27.0	是

Laravel AI 支持要求使用 Laravel 12.x 或更高版本、sentry/sentry-laravel 4.27.0 或更高版本，并启用追踪。

JavaScript 配置

Node.js — 自动启用的集成

只需确保已启用追踪。安装 AI 包后，集成会自动启用：

Sentry.init({
  dsn: "YOUR_DSN",
  tracesSampleRate: 1.0, // Lower in production (e.g., 0.1)
  // OpenAI, Anthropic, Google GenAI, LangChain integrations auto-enable in Node.js
});

如需自定义（例如，在用户确认后启用提示词捕获——请参阅数据捕获警告）：

Sentry.init({
  dsn: "YOUR_DSN",
  tracesSampleRate: 1.0,
  dataCollection: {
    // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit:
    // https://docs.sentry.io/platforms/javascript/configuration/options/#dataCollection
    // userInfo: false,
    // httpBodies: [],
  },
  integrations: [
    Sentry.openAIIntegration({
      // recordInputs/recordOutputs default to true (governed by dataCollection.genAI)
    }),
  ],
});

Cloudflare Workers（不进行运行时修补）

Workers 运行时（workerd）不支持猴子补丁，因此不适用 Node.js 风格的自动插桩。withSentry 会自动对 Workers AI（env.AI）进行插桩（v10.67.0+）；openai、@anthropic-ai/sdk、@google/genai 和 ai 需要使用构建时的 Sentry Cloudflare Vite 插件（v10.68.0+，实验性），或手动包装客户端；LangChain/LangGraph 仅支持手动方式。完整设置说明请参阅 ${SKILL_ROOT}/../../references/sdks/cloudflare/ai-monitoring.md。

浏览器 / Next.js OpenAI（需要手动包装）

在浏览器端代码或 Next.js 元框架应用中，无法使用自动插桩。请手动包装客户端：

import OpenAI from "openai";
import * as Sentry from "@sentry/nextjs"; // or @sentry/react, @sentry/browser

const openai = Sentry.instrumentOpenAiClient(new OpenAI());
// Use 'openai' client as normal

LangChain / LangGraph（自动启用）

Sentry.init({
  dsn: "YOUR_DSN",
  tracesSampleRate: 1.0,
  dataCollection: {
    // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit:
    // https://docs.sentry.io/platforms/javascript/configuration/options/#dataCollection
    // userInfo: false,
    // httpBodies: [],
  },
  integrations: [
    Sentry.langChainIntegration(),
    Sentry.langGraphIntegration(),
  ],
});

Vercel AI SDK

对于 Edge 运行时，请添加到 sentry.edge.config.ts：

Sentry.init({
  dsn: "YOUR_DSN",
  tracesSampleRate: 1.0,
  dataCollection: {
    // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit:
    // https://docs.sentry.io/platforms/javascript/configuration/options/#dataCollection
    // userInfo: false,
    // httpBodies: [],
  },
  integrations: [Sentry.vercelAIIntegration()],
});

逐次调用启用遥测：

await generateText({
  model: openai("gpt-4o"),
  prompt: "Hello",
  experimental_telemetry: {
    isEnabled: true,
    recordInputs: true,
    recordOutputs: true,
  },
});

Python 配置

集成会自动启用——只需在初始化时启用追踪。仅在自定义选项时才添加显式导入：

import sentry_sdk

sentry_sdk.init(
    dsn="YOUR_DSN",
    traces_sample_rate=1.0,  # Lower in production (e.g., 0.1)
    send_default_pii=True,
    # Integrations auto-enable when the AI package is installed.
    # Only specify explicitly to customize (e.g., include_prompts):
    # integrations=[OpenAIIntegration(include_prompts=True)],
)

PHP / Laravel AI 配置

安装 sentry/sentry-laravel 和 laravel/ai 并启用追踪后，Laravel AI 插桩会自动启用。

composer require sentry/sentry-laravel "^4.27.0"
composer require laravel/ai
php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"
php artisan migrate

在 .env 中启用追踪：

SENTRY_TRACES_SAMPLE_RATE=1.0

如需在用户明确确认后纳入大模型提示词、工具参数和响应，请启用 PII 捕获：

SENTRY_SEND_DEFAULT_PII=true

Sentry 将大模型和工具的输入/输出视为 PII，默认不予捕获。未确认上文的数据捕获警告前，请勿启用 SENTRY_SEND_DEFAULT_PII=true。

Laravel 集成会自动捕获以下 span 类型：

Span op	Purpose
gen_ai.invoke_agent	Agent 提示词生命周期
gen_ai.chat	AI 提供商聊天请求
gen_ai.execute_tool	Laravel AI 工具执行
gen_ai.embeddings	嵌入生成

有关 Laravel 的详细设置、验证、对话行为和功能标志，请参阅 ${SKILL_ROOT}/../../references/sdks/php/ai-monitoring.md。

手动插桩

未检测到受支持的 SDK 时使用。请遵循规范的 Sentry gen_ai.* 属性约定——JS 文档可能尚未更新；请勿设置约定中标记为已弃用的属性。

Span 类型

op	Span name pattern	Purpose
gen_ai.{operation}（例如 gen_ai.chat、gen_ai.request）	{operation} {model}（例如 chat gpt-4o）	单次大模型调用
gen_ai.invoke_agent	invoke_agent {agent_name}	Agent 执行生命周期
gen_ai.execute_tool	execute_tool {tool_name}	工具/函数调用
gen_ai.handoff	handoff from {source} to {target}	Agent 间交接

对于大模型调用 span，op 遵循 gen_ai.{gen_ai.operation.name} 模式——已知操作类型时，请使用 gen_ai.chat、gen_ai.embeddings、gen_ai.generate_content 或 gen_ai.text_completion。Span 属性仅接受基本类型；数组/对象必须转换为 JSON 字符串。

示例（JavaScript）

const inputMessages = [
  { role: "user", parts: [{ type: "text", content: "Tell me a joke" }] },
];

await Sentry.startSpan({
  op: "gen_ai.chat",
  name: "chat gpt-4o",
  attributes: {
    "gen_ai.request.model": "gpt-4o",
    "gen_ai.operation.name": "chat",
    "gen_ai.input.messages": JSON.stringify(inputMessages),
  },
}, async (span) => {
  const result = await llmClient.complete(inputMessages);

  const outputMessages = [
    {
      role: "assistant",
      parts: [
        // Thinking/reasoning content goes in a `reasoning` part, NOT a `text` part.
        // Sentry surfaces it separately and filters it out of the Conversations view.
        { type: "reasoning", content: result.reasoning },
        { type: "text", content: result.text },
      ],
      finish_reason: result.finishReason,
    },
  ];
  span.setAttribute("gen_ai.output.messages", JSON.stringify(outputMessages));
  span.setAttribute("gen_ai.usage.input_tokens", result.inputTokens);
  span.setAttribute("gen_ai.usage.output_tokens", result.outputTokens);
  return result;
});

关键属性

通用属性（适用于所有 AI span）：

属性	必填	描述
gen_ai.request.model	是	模型标识符（例如，gpt-4o、claude-sonnet-4-6）
gen_ai.operation.name	否	操作标签（chat、embeddings、invoke_agent、execute_tool、handoff 等）
gen_ai.agent.name	否	Agent 名称（设置在 Agent 和工具 span 上）

模型配置（LLM 调用 span）：

属性	描述
gen_ai.request.reasoning_effort	推理模型的推理力度级别（例如，low、medium、high）。支持的值因提供商而异。

请求 / 响应内容（PII — 仅在确认后启用；请参阅上文的数据采集警告）：

属性	描述
gen_ai.input.messages	输入消息的 JSON 字符串化数组。每项使用 {role, parts}，其中 parts 为 [{type, content}]；role 为 "user"、"assistant"、"tool" 或 "system"。常见的 parts 类型包括："text"、"reasoning"、"tool_call"、"tool_call_response"
gen_ai.output.messages	响应消息（文本 + 工具调用）的 JSON 字符串化数组，结构与输入相同

思考 / 推理消息：启用扩展思考的模型（Anthropic 的 thinking 块、Gemini 的 thought、DeepSeek 的 reasoning_content）会生成不属于用户可见回复的内部推理内容。将其表示为助手消息中的 reasoning 部分——{"type": "reasoning", "content": "..."}——并与面向用户的 text 部分并列。Sentry 会单独显示推理部分，并在面向用户的 Conversations 视图中将其过滤，因此不要将思考内容并入 text 部分。当先前的思考内容被反馈到多轮请求中时，请在 gen_ai.input.messages 的助手消息中包含相同的 reasoning 部分。通过 gen_ai.usage.output_tokens.reasoning 记录推理令牌数（它是 gen_ai.usage.output_tokens 的子集）。 | gen_ai.system_instructions | 传递给模型的系统提示词 | | gen_ai.tool.definitions | 模型可用工具列表的 JSON 字符串化形式 |

令牌用量：

属性	描述
gen_ai.usage.input_tokens	输入令牌总数——包括缓存令牌
gen_ai.usage.input_tokens.cached	从缓存提供的输入令牌子集
gen_ai.usage.input_tokens.cache_write	处理输入时写入缓存的令牌数
gen_ai.usage.output_tokens	输出令牌总数——包括推理令牌
gen_ai.usage.output_tokens.reasoning	用于推理的输出令牌子集
gen_ai.usage.total_tokens	输入令牌数 + 输出令牌数

工具 span（gen_ai.execute_tool）：

属性	描述
gen_ai.tool.name	工具标识符
gen_ai.tool.description	供人阅读的工具描述
gen_ai.tool.call.arguments	工具参数的 JSON 字符串化形式
gen_ai.tool.call.result	工具结果的 JSON 字符串化形式

令牌用量与成本计算

Sentry 使用令牌属性来计算模型成本。缓存令牌和推理令牌是子集，而非单独计数——gen_ai.usage.input_tokens 已包含 gen_ai.usage.input_tokens.cached，而 gen_ai.usage.output_tokens 已包含 gen_ai.usage.output_tokens.reasoning。

Sentry 会从总数中减去缓存令牌数 / 推理令牌数，以计算未缓存 / 非推理部分。报告的缓存令牌数或推理令牌数若大于其总数，会导致仪表板中的成本为负数。

示例——输入令牌总数为 100，其中 90 个由缓存提供：

• 正确：input_tokens = 100，input_tokens.cached = 90
• 错误：input_tokens = 10，input_tokens.cached = 90（缓存令牌数大于总数 → 成本为负数）

gen_ai.usage.output_tokens 与 gen_ai.usage.output_tokens.reasoning 也遵循同样的规则。

验证

完成配置后，发起一次 LLM 调用并检查 Sentry Traces 仪表板。AI span 会显示 gen_ai.* 操作，其中包含模型、Token 数量和延迟信息。

对话

对话功能以易读的聊天式视图展示与 AI Agent 的过往会话。它会根据 gen_ai.conversation.id 对 span 进行分组——无论用户是在多个 trace 中交谈，还是在一个 trace 中进行了多次对话，你都可以查看每条消息、工具调用和回复的时间线。

当用户询问 AI 监控设置时，如果应用支持多轮聊天，请主动说明此要求。如果没有对话 ID，Agent 监控 span 仍然可以正常工作，但“对话”视图无法正确分组会话。

在 Sentry 中前往 Explore > Conversations 查看。

对话功能的前提条件

• 已启用追踪，且 tracesSampleRate > 0
• Gen AI span 流式传输默认开启——自 JS SDK 10.61.0 起，streamGenAiSpans 默认为 true；自 Python SDK 2.64.0 起，stream_gen_ai_spans 默认为 True。此设置会将 AI span 作为独立条目发送，因此输入或输出较大的 span 不会触及事务载荷大小限制并被丢弃。（如果需要在较旧的 SDK 中显式设置这些选项，可使用 JS 10.53.0 / Python 2.60.0 起的版本。）
• 已启用输入和输出采集——对话功能通过 gen_ai.input.messages 和 gen_ai.output.messages 属性还原聊天记录。在 JS 中，默认启用此功能（通过 dataCollection）；在 Python 中，设置 send_default_pii=True；在 Laravel 中，设置 SENTRY_SEND_DEFAULT_PII=true。如果未启用，对话内容将为空。

设置对话 ID

某些集成（适用于 Python 的 OpenAI Agents SDK、适用于 Node 的 OpenAI SDK，以及使用 Conversational + RemembersConversations 的 Laravel AI Agent）会自动推断对话 ID。其他情况则需要手动设置。

请使用简短、不透明的标识符——仅包含字母数字字符、连字符或下划线。切勿将 URL、电子邮件地址或其他自由格式文本用作对话 ID：Sentry 会将其用作 URL 路径段，包含斜杠的值会导致该会话的“对话”功能无法正常工作。

示例：

• UUID：48e35936-82ab-4f1a-beaf-b2fa4273ac5e
• 带前缀的 ID：conv_5j66UpCpwteGg4YSxUnt7lPYU、asst_abc12345、sess_987654

JavaScript

import * as Sentry from "@sentry/node"; // or @sentry/nextjs, @sentry/nestjs, etc.

// Set at the start of a conversation
Sentry.setConversationId("conv_abc123");

// All subsequent AI calls carry gen_ai.conversation.id: "conv_abc123"
await openai.chat.completions.create({
  model: "gpt-5.5",
  messages: [{ role: "user", content: "Hello" }],
});

Python

import sentry_sdk.ai

# Set at the start of a conversation
sentry_sdk.ai.set_conversation_id("conv_abc123")

# All subsequent AI calls carry gen_ai.conversation.id = "conv_abc123"

某些集成会自动推断对话 ID。例如，使用 conversation 参数时，Python OpenAI 集成会自动获取该 ID：

import openai
import sentry_sdk

sentry_sdk.init(...)

conversation = openai.conversations.create()
response = openai.responses.create(
    model="gpt-5.4",
    input=[{"role": "user", "content": "What are the 5 Ds of dodgeball?"}],
    conversation=conversation.id  # automatically sets gen_ai.conversation.id
)

用户归属信息

“对话”视图会显示 User 列。若要填充此列，请在进行任何 AI 调用之前，每个请求或会话调用一次 setUser / set_user：

JavaScript

import * as Sentry from "@sentry/node"; // or @sentry/nextjs, @sentry/nestjs, etc.

Sentry.setUser({ id: "user_123", email: "[email protected]", username: "jane" });

Python

import sentry_sdk

sentry_sdk.set_user({"id": "user_123", "email": "[email protected]", "username": "jane"})

只需提供 id、email 或 username 中的任意一项即可——“对话”视图会显示已提供的字段。

对话与 Trace

这是两个相互独立的概念：

• 单个对话可以跨越多个 trace（例如，用户在对话中途刷新页面——产生新的 trace，但对话 ID 相同）
• 单个 trace 可以包含来自不同对话的 span（例如，用户未刷新页面就开始了新聊天）

故障排查

问题	解决方案
未显示 AI span	确认 tracesSampleRate > 0，并检查 SDK 版本
缺少 Token 数量	某些提供商不会为流式传输返回 Token 数量
控制面板中的费用为负数或不正确	缓存 Token／推理 Token 是总量的子集——请参阅 Token 使用量和费用计算
未捕获提示词	在 JS 中，genAI 捕获默认开启——请确认未设置 dataCollection: { genAI: { inputs: false } }，或显式传入 recordInputs: true。在 Python 中，设置 send_default_pii=True；在 Laravel 中，设置 SENTRY_SEND_DEFAULT_PII=true。仅在需要显式覆盖 Python 配置时使用 include_prompts
Vercel AI 无法正常工作	为每次调用添加 experimental_telemetry
未显示 Laravel AI span	确认 sentry/sentry-laravel >=4.27.0，已安装 laravel/ai，且 SENTRY_TRACES_SAMPLE_RATE > 0
对话视图为空	确认已启用 Gen AI span 流式传输（自 JS SDK 10.61.0／Python SDK 2.64.0 起默认启用）、已启用 genAI 输入／输出捕获（JS 中默认通过 dataCollection 启用；Python 中设置 send_default_pii=True；Laravel 中设置 SENTRY_SEND_DEFAULT_PII=true），并已设置对话 ID
用户列显示“Unknown”	每次请求或会话调用一次 Sentry.setUser()（JS）或 sentry_sdk.set_user()（Python）