sentry-setup-ai-monitoring

すべてのスキル > 機能のセットアップ > AI モニタリング

Sentry AI エージェントモニタリングをセットアップする

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

このスキルを使用する場面

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

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

前提条件

AI モニタリングにはトレーシングの有効化（tracesSampleRate > 0）が必要です。

アプリに複数ターンのチャットがある場合は、チャットセッションを識別できる箇所で、デフォルトの会話 ID を設定してください。Sentry は gen_ai.conversation.id を使用して、関連する AI スパンを会話単位にグループ化します。一部のインテグレーションでは自動的に推測されますが、多くの構成では明示的な設定が必要です。

データキャプチャに関する警告

プロンプトと出力の記録では、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} です。エージェントの実行はスパンツリー全体としてサンプリングされるため、ルートスパンが破棄されると、すべての子 gen_ai スパンも失われます。AI を完全に可視化するには、gen_ai 関連のトランザクションを 100% の割合でサンプリングする必要があります。他のトラフィックは現在のレートでサンプリングしながら、AI トレースを 100% 保持する tracesSampler を設定しますか？」

ユーザーが承諾した場合は、${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 (Model Context Protocol)	はい

PHP / Laravel

パッケージ	インテグレーション	Sentry SDK の最小バージョン	自動？
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 スタイルの自動計装は適用されません。Workers AI（env.AI）は withSentry（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

ユーザーの明示的な確認後に LLM のプロンプト、ツール引数、レスポンスを含めるには、PII キャプチャを有効にします。

SENTRY_SEND_DEFAULT_PII=true

Sentry は LLM とツールの入出力を PII として扱い、デフォルトではキャプチャしません。上記の「データキャプチャに関する警告」を確認せずに SENTRY_SEND_DEFAULT_PII=true を有効にしないでください。

Laravel インテグレーションは、以下のスパンタイプを自動的にキャプチャします。

スパン op	目的
gen_ai.invoke_agent	エージェントのプロンプトのライフサイクル
gen_ai.chat	AI プロバイダーへのチャットリクエスト
gen_ai.execute_tool	Laravel AI のツール実行
gen_ai.embeddings	埋め込みの生成

Laravel の詳細なセットアップ、検証、Conversations の動作、機能フラグについては、${SKILL_ROOT}/../../references/sdks/php/ai-monitoring.md をお読みください。

手動計装

サポートされている SDK が検出されない場合に使用します。正規の Sentry の gen_ai.* 属性規約に従ってください。JS ドキュメントの内容が古い場合があります。規約で非推奨とされている属性は設定しないでください。

スパンタイプ

op	スパンの name パターン	目的
gen_ai.{operation}（例：gen_ai.chat、gen_ai.request）	{operation} {model}（例：chat gpt-4o）	個々の LLM 呼び出し
gen_ai.invoke_agent	invoke_agent {agent_name}	エージェント実行のライフサイクル
gen_ai.execute_tool	execute_tool {tool_name}	ツール／関数の呼び出し
gen_ai.handoff	handoff from {source} to {target}	エージェント間の移行

LLM 呼び出しのスパンでは、op は gen_ai.{gen_ai.operation.name} のパターンに従います。操作が分かっている場合は、gen_ai.chat、gen_ai.embeddings、gen_ai.generate_content、または gen_ai.text_completion を使用してください。スパン属性で受け入れられるのはプリミティブのみです。配列／オブジェクトは 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 スパン）：

属性	必須	説明
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	いいえ	エージェント名（エージェントとツールのスパンに設定）

モデル設定（LLM 呼び出しスパン）：

属性	説明
gen_ai.request.reasoning_effort	推論モデルの推論強度（例：low、medium、high）。サポートされる値はプロバイダーによって異なります。

リクエスト／レスポンスの内容（PII — 有効にするのは確認後のみ。上記のデータ収集に関する警告を参照）：

属性	説明
gen_ai.input.messages	入力メッセージの JSON 文字列化配列。各項目は {role, parts} を使用し、parts は [{type, content}] です。role は "user"、"assistant"、"tool"、または "system" です。一般的な type は "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	入力トークンと出力トークンの合計

ツールスパン（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 のスパンは、モデル、トークン数、レイテンシーを示す gen_ai.* オペレーションとともに表示されます。

会話

Conversations では、AI エージェントとの過去のセッションを、読みやすいチャット形式で確認できます。gen_ai.conversation.id に基づいてスパンがグループ化されるため、ユーザーが複数のトレースにまたがって会話した場合も、1 つのトレース内で複数の会話が行われた場合も、すべてのメッセージ、ツール呼び出し、応答のタイムラインを確認できます。

AI モニタリングの設定をユーザーから尋ねられたとき、アプリに複数ターンのチャットがある場合は、この要件を先回りして伝えてください。会話 ID がなくてもエージェントのモニタリングスパンは機能しますが、Conversations ビューではセッションを正しくグループ化できません。

Sentry の Explore > Conversations から確認できます。

Conversations の前提条件

• トレーシングが有効で、tracesSampleRate > 0 であること
• Gen AI スパンのストリーミングはデフォルトで有効です。JS SDK 10.61.0 以降では streamGenAiSpans のデフォルトが true、Python SDK 2.64.0 以降では stream_gen_ai_spans のデフォルトが True です。これにより AI スパンが独立したアイテムとして送信されるため、入力や出力が大きいスパンがトランザクションのペイロードサイズ制限に達して破棄されることを防げます。（これらのオプションは JS 10.53.0／Python 2.60.0 以降で利用可能です。古い SDK で明示的に設定する必要がある場合に使用してください。）
• 入力と出力のキャプチャが有効であること — Conversations は gen_ai.input.messages と gen_ai.output.messages 属性からチャットを再構築します。JS ではデフォルトで有効です（dataCollection 経由）。Python では send_default_pii=True を設定し、Laravel では SENTRY_SEND_DEFAULT_PII=true を設定してください。これが有効でない場合、会話は空で表示されます。

会話 ID の設定

一部のインテグレーション（OpenAI Agents SDK for Python、OpenAI SDK for Node、Conversational + RemembersConversations を使用する Laravel AI エージェント）では、会話 ID が自動的に推定されます。それ以外の場合は、手動で設定してください。

短く、不透明な識別子を使用してください。使用できるのは、英数字とハイフンまたはアンダースコアのみです。会話 ID に URL、メールアドレス、その他の自由形式のテキストを使用しないでください。Sentry はこれを URL のパスセグメントとして使用するため、スラッシュを含む値を指定すると、そのセッションの Conversations が機能しなくなります。

良い例：

• 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 が自動的に推定されます。たとえば、Python OpenAI インテグレーションでは、conversation パラメーターを使用すると会話 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
)

ユーザーの関連付け

Conversations ビューには User 列が表示されます。この列に値を設定するには、AI の呼び出しを行う前に、リクエストまたはセッションごとに 1 回 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 のいずれかがあれば十分です。Conversations には、存在するフィールドが表示されます。

Conversations と Traces の違い

これらは独立した概念です。

• 1 つの会話が複数のトレースにまたがる場合があります（例：会話の途中でユーザーがページを更新すると、新しいトレースが作成されますが、会話 ID は同じです）
• 1 つのトレースに異なる会話のスパンが含まれる場合があります（例：ユーザーがページを更新せずに新しいチャットを開始する場合）

トラブルシューティング

問題	解決方法
AI スパンが表示されない	tracesSampleRate > 0 を確認し、SDK のバージョンを確認してください
トークン数が表示されない	ストリーミング時にトークンを返さないプロバイダーもあります
ダッシュボードでコストがマイナス、または誤って表示される	キャッシュトークンや推論トークンは合計値に含まれる内数です。「トークン使用量とコストの計算」を参照してください
プロンプトが記録されない	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 のスパンが表示されない	sentry/sentry-laravel >=4.27.0、laravel/ai がインストールされていること、および SENTRY_TRACES_SAMPLE_RATE > 0 を確認してください
会話ビューが空	Gen AI スパンのストリーミングが有効になっていること（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 が設定されていることを確認してください
ユーザー列に「不明」と表示される	リクエストまたはセッションごとに一度、Sentry.setUser()（JS）または sentry_sdk.set_user()（Python）を呼び出してください