sentry-setup-ai-monitoring

设置 Sentry AI Agent 监控

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

在以下情况下调用此 Skill

• 用户要求"监控 AI/LLM 调用"或"跟踪 OpenAI/Anthropic 使用情况"
• 用户想要"AI 可观测性"或"Agent 监控"
• 用户询问 token 使用量、模型延迟或 AI 成本

重要： 下面的 SDK 版本、API 名称和代码示例仅供参考。实施前请务必对照 docs.sentry.io 核实，因为 API 和最低版本可能已经变更。

前提条件

AI 监控需要启用 tracing（tracesSampleRate > 0）。

数据采集警告

提示词和输出记录会采集可能属于 PII 的用户内容。 在启用 recordInputs/recordOutputs（JS）或 include_prompts/send_default_pii（Python）之前，请确认：

• 应用程序的隐私政策允许采集用户提示词和模型响应
• 采集的数据符合适用法规（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

支持的 SDK

JavaScript

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

*Vercel AI：10.6.0+ 适用于 Node.js、Cloudflare Workers、Vercel Edge Functions、Bun。10.12.0+ 适用于 Deno。需要在每次调用时设置 experimental_telemetry。

Python

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

包	自动？	备注
openai	是	包括 OpenAI Agents SDK
anthropic	是
langchain / langgraph	是
huggingface_hub	是
google-genai	是
pydantic-ai	是
litellm	否	需要显式集成
mcp (Model Context Protocol)	是

JavaScript 配置

Node.js —— 自动启用的集成

只需确保 tracing 已启用。安装 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
});

要自定义（例如启用提示词采集——见数据采集警告）：

integrations: [
  Sentry.openAIIntegration({
    // recordInputs: true,  // Opt-in: captures prompt content (PII)
    // recordOutputs: true, // Opt-in: captures response content (PII)
  }),
],

浏览器 / 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（自动启用）

integrations: [
  Sentry.langChainIntegration({
    // recordInputs: true,  // Opt-in: captures prompt content (PII)
    // recordOutputs: true, // Opt-in: captures response content (PII)
  }),
  Sentry.langGraphIntegration({
    // recordInputs: true,
    // recordOutputs: true,
  }),
],

Vercel AI SDK

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

integrations: [Sentry.vercelAIIntegration()],

在每次调用时启用遥测：

await generateText({
  model: openai("gpt-4o"),
  prompt: "Hello",
  experimental_telemetry: {
    isEnabled: true,
    // recordInputs: true,  // Opt-in: captures prompt content (PII)
    // recordOutputs: true, // Opt-in: captures response content (PII)
  },
});

Python 配置

集成会自动启用——只需在启用 tracing 的情况下初始化。只有要自定义选项时才添加显式导入：

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,  # Opt-in: required for prompt capture (sends user PII)
    # Integrations auto-enable when the AI package is installed.
    # Only specify explicitly to customize (e.g., include_prompts):
    # integrations=[OpenAIIntegration(include_prompts=True)],
)

手动插桩

在未检测到受支持的 SDK 时使用。

Span 类型

op 值	用途
gen_ai.request	单次大模型调用
gen_ai.invoke_agent	Agent 执行生命周期
gen_ai.execute_tool	工具/函数调用
gen_ai.handoff	Agent 到 Agent 的切换

示例（JavaScript）

await Sentry.startSpan({
  op: "gen_ai.request",
  name: "LLM request gpt-4o",
  attributes: { "gen_ai.request.model": "gpt-4o" },
}, async (span) => {
  span.setAttribute("gen_ai.request.messages", JSON.stringify(messages));
  const result = await llmClient.complete(prompt);
  span.setAttribute("gen_ai.usage.input_tokens", result.inputTokens);
  span.setAttribute("gen_ai.usage.output_tokens", result.outputTokens);
  return result;
});

关键属性

属性	描述
gen_ai.request.model	模型标识符
gen_ai.request.messages	JSON 输入消息
gen_ai.usage.input_tokens	输入 token 数量
gen_ai.usage.output_tokens	输出 token 数量
gen_ai.agent.name	Agent 标识符
gen_ai.tool.name	工具标识符

仅在向用户确认后才启用提示词/输出捕获（参见上方的数据捕获警告）。

验证

配置完成后，发起一次大模型调用并检查 Sentry Traces 仪表盘。AI span 会出现，带有 gen_ai.* 操作，显示模型、token 数量和延迟。

故障排查

问题	解决方案
AI span 未出现	验证 tracesSampleRate > 0，检查 SDK 版本
缺少 token 数量	部分提供商不会为流式传输返回 token
提示词未被捕获	启用 recordInputs/include_prompts
Vercel AI 不工作	为每次调用添加 experimental_telemetry