用 Sentry 监控 LLM 调用与 AI Agent…

当需要为项目接入 Sentry 来追踪 LLM 调用、Agent 执行、工具使用和 token 消耗时，按此流程检测已装 AI SDK 并完成配置。

适用场景

解决思路

1. 先确认前置条件：AI 监控要求开启 tracing，即 tracesSampleRate > 0。
2. 在启用 prompt/输出捕获前先做数据合规确认：recordInputs/recordOutputs（JS）或 include_prompts/send_default_pii（Python）会捕获可能含 PII 的用户内容，需确认隐私政策允许、符合 GDPR/CCPA 等法规、Sentry 数据保留设置合适；必须询问用户是否要开启，默认不开启，仅在明确要求或确认后配置。tracesSampleRate: 1.0 仅用于开发环境，生产环境用更低值或 tracesSampler 函数。
3. 配置前先检测已安装的 AI SDK：JS 执行 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。
4. 对照支持的 SDK 与最低 Sentry SDK 版本：JS 中 openai→openAIIntegration()（10.28.0，自动）、@anthropic-ai/sdk→anthropicAIIntegration()（10.28.0，自动）、ai(Vercel)→vercelAIIntegration()（10.6.0，自动，Deno 需 10.12.0，且每次调用需 experimental_telemetry）、@langchain/*→langChainIntegration()（10.28.0，自动）、@langchain/langgraph→langGraphIntegration()（10.28.0，自动）、@google/genai→googleGenAIIntegration()（10.28.0，自动）。
5. Python 侧集成在安装对应 AI 包后自动启用，无需显式注册：openai（含 OpenAI Agents SDK）、anthropic、langchain/langgraph、huggingface_hub、google-genai、pydantic-ai、mcp 均自动；litellm 不自动，需显式集成。
6. Node.js 配置：只需确保开启 tracing，AI 包安装后集成自动启用，例如 Sentry.init({ dsn: "YOUR_DSN", tracesSampleRate: 1.0 })。如需自定义（如开启 prompt 捕获），在 integrations 中显式写 Sentry.openAIIntegration({ recordInputs: true, recordOutputs: true })。
7. 浏览器 / Next.js 的 OpenAI 需手动包装（无自动埋点）：import OpenAI from "openai"; import * as Sentry from "@sentry/nextjs"; const openai = Sentry.instrumentOpenAiClient(new OpenAI()); 之后正常使用该 client。
8. LangChain / LangGraph 配置：在 integrations 中加入 Sentry.langChainIntegration({ recordInputs: true, recordOutputs: true }) 和 Sentry.langGraphIntegration({ recordInputs: true, recordOutputs: true })。
9. Vercel AI SDK 配置：在 sentry.edge.config.ts 中加入 integrations: [Sentry.vercelAIIntegration()]；并在每次调用时开启 telemetry，例如 generateText({ model: openai("gpt-4o"), prompt: "Hello", experimental_telemetry: { isEnabled: true, recordInputs: true, recordOutputs: true } })。
10. Python 配置：集成自动启用，只需带 tracing 初始化，例如 sentry_sdk.init(dsn="YOUR_DSN", traces_sample_rate=1.0)；如需 prompt 捕获加 send_default_pii=True，或显式写 integrations=[OpenAIIntegration(include_prompts=True)]。
11. 当未检测到受支持的 SDK 时使用手动埋点，按 span 类型选择 op：gen_ai.request（单次 LLM 调用）、gen_ai.invoke_agent（Agent 执行生命周期）、gen_ai.execute_tool（工具/函数调用）、gen_ai.handoff（Agent 间切换）。
12. 手动埋点示例（JS）：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; });
13. 手动埋点关键属性：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（工具标识）；仅在向用户确认后再开启 prompt/输出捕获。
14. 配置完成后发起一次 LLM 调用，到 Sentry Traces 面板验证：AI span 会以 gen_ai.* 操作出现，展示模型、token 数和延迟。
15. 排障：AI span 不出现→确认 tracesSampleRate > 0 并检查 SDK 版本；token 数缺失→部分提供商流式响应不返回 token；prompt 未捕获→开启 recordInputs/include_prompts；Vercel AI 不生效→为每次调用加 experimental_telemetry。
16. 注意 SDK 版本、API 名称和代码示例仅为示例，实施前务必对照 docs.sentry.io 核实，因为 API 和最低版本可能已变化。

适用边界 · 注意事项

• 未使用 Sentry 或不愿接入 Sentry 的项目不适用。
• 未开启 tracing（tracesSampleRate 为 0）时无法生效。
• 涉及用户 prompt/响应捕获时，若隐私政策或法规不允许、或用户未确认，不应开启数据捕获。