All Skills > Feature Setup > AI Monitoring

Sentry AI Agent Monitoring のセットアップ

LLM呼び出し、エージェント実行、ツール使用、トークン消費を追跡するよう Sentry を構成します。

このスキルを呼び出すタイミング

• ユーザーが「AI/LLM呼び出しのモニタリング」または「OpenAI/Anthropic使用量の追跡」をリクエストする場合
• ユーザーが「AI可観測性」または「エージェント監視」を希望する場合
• ユーザーがトークン使用量、モデルレイテンシ、またはAIコストについて質問する場合

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

前提条件

AI モニタリングには、トレーシングが有効(tracesSampleRate > 0)である必要があります。

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

プロンプトおよび出力記録は、ユーザーコンテンツ（おそらく個人情報）をキャプチャします。 recordInputs/recordOutputs (JS) または include_prompts/send_default_pii (Python) を有効にする前に、以下を確認してください：

• アプリケーションのプライバシーポリシーがユーザープロンプトとモデル応答のキャプチャを許可している
• キャプチャされたデータが適用される規制（GDPR、CCPA など）に準拠している
• Sentry データ保持設定がデータの機密性に適切である

ユーザーに確認してください：プロンプト/出力キャプチャを有効にするかどうか。デフォルトで有効にしないでください。明示的にリクエストされた場合、または確認された場合のみ構成してください。開発環境では tracesSampleRate: 1.0 を使用し、本番環境では低い値または tracesSampler 関数を使用してください。

検出を最初に実施

AI SDKs を構成する前に、インストール済みのものを常に検出してください：

# 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

サンプリング確認

AI SDKs を検出した後、現在のサンプリング設定を確認します：

# 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

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)	はい

JavaScript 構成

Node.js — 自動有効化統合

トレーシングが有効であることを確認するだけです。AI パッケージがインストールされていると統合は自動で有効化されます：

Sentry.init({
  dsn: "YOUR_DSN",
  tracesSampleRate: 1.0, // 本番環境では低い値に (例：0.1)
  streamGenAiSpans: true, // SDK ≥10.53.0
  // OpenAI、Anthropic、Google GenAI、LangChain 統合は Node.js で自動有効化
});

カスタマイズする場合（例：プロンプトキャプチャを有効化 — データキャプチャに関する警告を参照）：

integrations: [
  Sentry.openAIIntegration({
    // recordInputs: true,  // オプトイン：プロンプトコンテンツをキャプチャ（個人情報）
    // recordOutputs: true, // オプトイン：レスポンスコンテンツをキャプチャ（個人情報）
  }),
],

ブラウザ / Next.js OpenAI（手動ラッピング必須）

ブラウザ側コードまたは Next.js メタフレームワークアプリでは、自動インストルメンテーションは利用できません。クライアントを手動でラップしてください：

import OpenAI from "openai";
import * as Sentry from "@sentry/nextjs"; // または @sentry/react、@sentry/browser

const openai = Sentry.instrumentOpenAiClient(new OpenAI());
// 通常通り 'openai' クライアントを使用

LangChain / LangGraph（自動有効化）

integrations: [
  Sentry.langChainIntegration({
    // recordInputs: true,  // オプトイン：プロンプトコンテンツをキャプチャ（個人情報）
    // recordOutputs: true, // オプトイン：レスポンスコンテンツをキャプチャ（個人情報）
  }),
  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,  // オプトイン：プロンプトコンテンツをキャプチャ（個人情報）
    // recordOutputs: true, // オプトイン：レスポンスコンテンツをキャプチャ（個人情報）
  },
});

Python 構成

統合は自動で有効化されます。トレーシング有効でイニシャライズするだけです。カスタマイズするオプションについてのみ明示的インポートを追加します：

import sentry_sdk

sentry_sdk.init(
    dsn="YOUR_DSN",
    traces_sample_rate=1.0,  # 本番環境では低い値に (例：0.1)
    stream_gen_ai_spans=True,  # SDK ≥2.60.0
    # send_default_pii=True,  # オプトイン：プロンプトキャプチャに必須（ユーザー個人情報を送信）
    # AI パッケージがインストールされていると統合は自動有効化されます。
    # オプションをカスタマイズする場合のみ明示的に指定します（例：include_prompts）：
    # integrations=[OpenAIIntegration(include_prompts=True)],
)

手動インストルメンテーション

サポート対象の SDK が検出されない場合に使用します。gen_ai.* 属性に関する Sentry 規約に従ってください。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: [{ 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	いいえ	エージェント名（エージェントとツールスパンで設定）

リクエスト/レスポンスコンテンツ（個人情報 — 確認後のみ有効化。上記のデータキャプチャに関する警告を参照）：

属性	説明
gen_ai.input.messages	入力メッセージの JSON 文字列化配列。各項目は {role, parts} を使用します。parts は [{type, content}]。role は "user"、"assistant"、"tool"、または "system"
gen_ai.output.messages	レスポンスメッセージの JSON 文字列化配列（テキスト＋ツール呼び出し）。入力と同じ形式
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 トレースダッシュボードで確認します。AI スパンはモデル、トークンカウント、レイテンシを示す gen_ai.* 操作で表示されます。

トラブルシューティング

問題	解決策
AI スパンが表示されない	tracesSampleRate > 0 を確認し、SDK バージョンを確認
トークンカウントが不足している	一部のプロバイダはストリーミングのトークンを返しません
ダッシュボードのコストが負または間違っている	キャッシュ/推論トークンは合計のサブセットです。トークン使用量とコスト計算を参照
プロンプトがキャプチャされない	recordInputs/include_prompts を有効化
Vercel AI が機能しない	各コールに experimental_telemetry を追加