sentry-setup-ai-monitoring

Sentry AI エージェントのモニタリングを設定する

Sentry を設定して、LLM の呼び出し、エージェントの実行、ツールの使用状況、トークンの消費量を追跡します。

このスキルを使用するタイミング

• ユーザーが「AI／LLM の呼び出しを監視」または「OpenAI／Anthropic の使用状況を追跡」したい場合
• ユーザーが「AI オブザーバビリティ」または「エージェントのモニタリング」を求めている場合
• ユーザーがトークンの使用状況、モデルのレイテンシー、AI のコストについて尋ねた場合

重要： 以下の SDK バージョン、API 名、コードサンプルは例です。API や最小バージョンが変更されている可能性があるため、実装前に必ず docs.sentry.io で確認してください。

前提条件

AI モニタリングにはトレーシングの有効化（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：Node.js、Cloudflare Workers、Vercel Edge Functions、Bun では 10.6.0 以降。Deno では 10.12.0 以降。呼び出しごとに 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 — 自動的に有効になるインテグレーション

トレーシングが有効になっていることを確認するだけです。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 の設定

インテグレーションは自動的に有効になります。トレーシングを有効にして初期化するだけです。オプションをカスタマイズする場合にのみ、明示的なインポートを追加してください。

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 が検出されない場合に使用します。

スパンの種類

op の値	用途
gen_ai.request	個々の LLM 呼び出し
gen_ai.invoke_agent	エージェントの実行ライフサイクル
gen_ai.execute_tool	ツール／関数の呼び出し
gen_ai.handoff	エージェント間の引き継ぎ

例（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	入力トークン数
gen_ai.usage.output_tokens	出力トークン数
gen_ai.agent.name	エージェント識別子
gen_ai.tool.name	ツール識別子

プロンプト／出力のキャプチャを有効にするのは、ユーザーに確認してからにしてください（上記のデータキャプチャに関する警告を参照）。

検証

設定後、LLM を呼び出し、Sentry のトレースダッシュボードを確認します。モデル、トークン数、レイテンシを示す gen_ai.* 操作の AI スパンが表示されます。

トラブルシューティング

問題	解決策
AI スパンが表示されない	tracesSampleRate > 0 であることを確認し、SDK のバージョンを確認します
トークン数が表示されない	ストリーミングではトークンを返さないプロバイダーもあります
プロンプトがキャプチャされない	recordInputs/include_prompts を有効にします
Vercel AI が機能しない	各呼び出しに experimental_telemetry を追加します