sentry-setup-ai-monitoring

用途

本技能用于在任意项目中配置 Sentry AI Agent Monitoring，以便追踪和监控 AI 相关行为。调用场景包括：用户要求“监控 AI/LLM 调用”或“追踪 OpenAI/Anthropic 使用量”；用户需要“AI 可观测性”或“智能体监控”；用户询问 token 用量、模型延迟或 AI 成本。

主要能力

可配置 Sentry 以追踪 LLM 调用、智能体执行、工具使用情况以及 token 消耗，并提供自动集成与手动埋点两种方式。

支持以下 Span 类型：gen_ai.request（单次 LLM 调用）、gen_ai.invoke_agent（智能体执行生命周期）、gen_ai.execute_tool（工具/函数调用）、gen_ai.handoff（智能体间切换）。

关键属性包括：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（智能体标识）、gen_ai.tool.name（工具标识）。

前提条件

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

Package	Integration	Min Sentry SDK	Auto?
openai	openAIIntegration()	10.28.0	Yes
@anthropic-ai/sdk	anthropicAIIntegration()	10.28.0	Yes
ai (Vercel)	vercelAIIntegration()	10.6.0	Yes*
@langchain/*	langChainIntegration()	10.28.0	Yes
@langchain/langgraph	langGraphIntegration()	10.28.0	Yes
@google/genai	googleGenAIIntegration()	10.28.0	Yes

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

Python

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

Package	Auto?	Notes
openai	Yes	包含 OpenAI Agents SDK
anthropic	Yes
langchain / langgraph	Yes
huggingface_hub	Yes
google-genai	Yes
pydantic-ai	Yes
litellm	No	需要显式集成
mcp (Model Context Protocol)	Yes

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()],

每次调用启用 telemetry：

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 时使用。

示例（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;
});

仅在与用户确认后再启用提示词/输出捕获（见上文数据捕获警告）。

验证

配置完成后，发起一次 LLM 调用并检查 Sentry Traces 仪表盘。AI spans 会以 gen_ai.* 操作出现，显示模型、token 计数与延迟。

故障排查

问题	解决方案
AI spans 未出现	验证 tracesSampleRate > 0，检查 SDK 版本
token 计数缺失	某些提供商在流式传输时不返回 token
提示词未捕获	启用 recordInputs/include_prompts
Vercel AI 不工作	为每次调用添加 experimental_telemetry

重要提示

上述 SDK 版本、API 名称与代码示例均为示例。实施前务必对照 docs.sentry.io 核实，因为 API 与最低版本可能已变更。