MCP Server and Tool Telemetry: 境界から検証された行まで
制御されたアプリケーション境界で MCP Server and Tool Telemetry を使用し、イベント コントラクトを小さく保ち、集約ビューを構築する前に既知の結果を検証します。
- 1
結果を選択してください
MCP ツールの信頼性
- 2
契約を定義する
tool_call_id、run_id、server_name、tool_name、client_type、トランスポート、およびリリース
- 3
境界を計測する
登録されたツール ハンドラーを計測して、呼び出そうとするたびに、返された MCP エラーを含む 1 つの結果イベントが生成されるようにします。
- 4
証拠を検証する
Exercise a known fixture, then inspect mcp_tool_completed for one correctly typed terminal row.
始める前に
前提条件と境界
- @modelcontextprotocol/sdk、zod、および telemetry-sh が信頼できるサーバー プロセスで初期化される
- 限定されたツール分類とアプリケーション所有の呼び出しまたは実行識別子
- ツールの入力、出力、承認、クライアント ID、および副作用に関する認可とプライバシー ポリシー
配信設定
サーバー側のインストールと初期化
サーバー専用コードで telemetry-sh をインポートし、process.env.TELEMETRY_API_KEY で一度初期化します。 ブラウザ バンドル、クライアントに表示される環境変数、ソース管理、ログ、および例外メッセージに取り込み資格情報が含まれないようにします。
npmのインストール
npm install telemetry-sh- 1制限されたネットワーク動作を持つ再利用可能なサーバー側配信クライアントを 1 つ準備します。
- 2成功、失敗、再試行、またはタイムアウトの境界に結果イベントを追加します。
- 3アラートを有効にする前に、制御されたフィクスチャを送信し、保存されている行を検査します。
スニペット
1 つの構造化されたイベントから始める
ワークフローが完了、失敗、または再試行される場所にこの図形を追加します。次に、実際のフィールドからダッシュボードを構築します。
MCP Server and Tool Telemetryイベント
server.registerTool(
"lookup-account",
{
title: "Look up account",
description: "Return an approved account summary",
inputSchema: { accountId: z.string() },
},
async ({ accountId }) => {
const startedAt = performance.now();
const toolCallId = crypto.randomUUID();
let status = "success";
let errorType;
try {
const summary = await lookupApprovedAccountSummary(accountId);
return {
content: [{ type: "text", text: summary }],
};
} catch (error) {
status = "failed";
errorType = classifyToolError(error);
return {
content: [{ type: "text", text: "Account lookup failed" }],
isError: true,
};
} finally {
await telemetry.log("mcp_tool_completed", {
tool_call_id: toolCallId,
server_name: "account-tools",
tool_name: "lookup-account",
status,
error_type: errorType,
duration_ms: Math.round(performance.now() - startedAt),
release: process.env.APP_RELEASE,
}).catch(reportTelemetryDeliveryFailure);
}
},
);イベント契約
tool_call_id、run_id、server_name、tool_name、client_type、トランスポート、およびリリース
ステータス、duration_ms、retry_count、error_type、approval_required、および approval_result
side_effect_category および output_category は制限され承認された場合のみ
実装のチェックポイント
チェックポイント 1
登録されたツール ハンドラーを計測して、呼び出そうとするたびに、返された MCP エラーを含む 1 つの結果イベントが生成されるようにします。
チェックポイント 2
デフォルトでは、ツール入力、返されたコンテンツ、埋め込みリソース、ファイル パス、資格情報、トークン、および無制限のエラーを Telemetry から除外します。
チェックポイント 3
Telemetry 配信の失敗によって、成功したツールの結果が変更されないようにしてください。短いタイムアウト、ローカル エラー報告、および制限されたシャットダウン動作を使用します。
検証
イベントが到着したことを証明する
既知の成功例と失敗例を実行した後、これを実行します。最終的なイベント コントラクトがスニペットと異なる場合は、フォールバック テーブル名を置き換えます。
MCP Server and Tool Telemetry 検証クエリ
SELECT *
FROM mcp_tool_completed
ORDER BY timestamp_utc DESC
LIMIT 20;実装の参考資料
新しい運用パスを有効にする前に、イベント契約、データ安全性に関するガイダンス、上流の主要ドキュメントを確認してください。
生産境界
結果イベントを小さく、回復可能なものに保つ
このパターンが提供するのは、
- 上流のワークフローの横にある、制限付きの SQL 対応の結果。
- ダッシュボード、アラート、およびイベント間の相関関係の安定したフィールド。
- 成功、失敗、再試行、タイムアウトの動作を検証するためのフィクスチャ駆動のパス。
このパターンでは提供されません
- OTLP エクスポーター、自動収集パイプライン、または詳細なトレースと診断ログの代替。
- ペイロードにイベント ID が含まれているという理由だけで、1 回だけ配信されます。
- 生のプロバイダー ペイロード、ユーザー コンテンツ、資格情報、または規制されたデータを収集する許可。
イベントスキーマの開始点
このワークフローのイベント コントラクト
クエリまたはスニペットを運用環境に適用する前に、行粒度、出力境界、必要なタイプ、プライバシー クラス、サンプル ペイロード、および検証チェックリストを確認してください。
関連製品の機能
このワークフローを続行します AIエージェントの監視
レビュー可能な SQL を使用して、エージェントの実行、ツールの使用、モデルのコスト、品質、製品の結果を結び付けます。
関連する SQL レシピ
SQL で次の質問に答えてください
このワークフローの構造化フィールドに対してクエリを実行し、結果の例を検査して、有用な回答をダッシュボードまたはアラートに変換します。
AI エージェント ツールの承認決定を監査する
どのエージェント ツールが最も頻繁に拒否されたり、人間の承認に送られたりするのでしょうか?
レシピを開くネストされた AI ツール呼び出しイベントのクエリ
最も失敗した呼び出しに関連する AI ツールと引数はどれですか?
レシピを開く繰り返しを検出する AI エージェント ツール Loops
どのエージェントの実行が繰り返しのツール ループに陥っているように見えますか?
レシピを開く相関のあるワークフローのタイムラインを再構築する
最近失敗したワークフロー中に、順番に何が起こったのでしょうか?
レシピを開くSQL による特権アクションの監査
どの特権アクションが失敗するか、人間によるレビューが最も頻繁に必要になるのはどれですか?
レシピを開く実装ファミリーごとに参照する
関連する統合パターンを比較する
この統合と組み合わせるテンプレート
さらなる統合
OpenAI エージェント Telemetry
OpenAI エージェントの実行、ツール呼び出し、モデルの使用状況、レイテンシー、コスト、および構造化イベントによる最終結果をログに記録します。
オープンガイドAutoGen タスク フロー、状態、タイムアウトの監視
AutoGen タスクフローの状態、タイムアウト、チームとエージェントの結果、ツールのアクティビティ、ハンドオフ、遅延、障害、コスト、リリースをコンパクトな構造化イベントで追跡します。
オープンガイドCrewAI ワークフロー Telemetry
エージェントの会話を保持することなく、CrewAI のスタッフとフローの結果、タスク数、ハンドオフ、再試行、待ち時間、コスト、承認された結果を追跡します。
オープンガイド