本文へ移動
Telemetry
統合ガイド

MCP サーバーおよびツール Telemetry

引数や返されたコンテンツを保存せずに、モデル コンテキスト プロトコル ツールの結果、遅延、エラー、承認、再試行、クライアント、リリースを追跡します。

レビュー者 Telemetry 製品チーム . インストルメンテーション契約、プライバシー境界、および実装ガイダンス. 基準と所有権を確認する

役に立つ
  • MCP ツールの信頼性
  • エージェントのツールループ分析
  • 特権アクションの監査
実装の証拠

MCP Server and Tool Telemetry: 境界から検証された行まで

制御されたアプリケーション境界で MCP Server and Tool Telemetry を使用し、イベント コントラクトを小さく保ち、集約ビューを構築する前に既知の結果を検証します。

  1. 1

    結果を選択してください

    MCP ツールの信頼性

  2. 2

    契約を定義する

    tool_call_id、run_id、server_name、tool_name、client_type、トランスポート、およびリリース

  3. 3

    境界を計測する

    登録されたツール ハンドラーを計測して、呼び出そうとするたびに、返された MCP エラーを含む 1 つの結果イベントが生成されるようにします。

  4. 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 で一度初期化します。 ブラウザ バンドル、クライアントに表示される環境変数、ソース管理、ログ、および例外メッセージに取り込み資格情報が含まれないようにします。

model-context-protocol-インストール

npmのインストール

bash
npm install telemetry-sh
  1. 1制限されたネットワーク動作を持つ再利用可能なサーバー側配信クライアントを 1 つ準備します。
  2. 2成功、失敗、再試行、またはタイムアウトの境界に結果イベントを追加します。
  3. 3アラートを有効にする前に、制御されたフィクスチャを送信し、保存されている行を検査します。

スニペット

1 つの構造化されたイベントから始める

ワークフローが完了、失敗、または再試行される場所にこの図形を追加します。次に、実際のフィールドからダッシュボードを構築します。

model-context-protocol

MCP Server and Tool Telemetryイベント

javascript
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 配信の失敗によって、成功したツールの結果が変更されないようにしてください。短いタイムアウト、ローカル エラー報告、および制限されたシャットダウン動作を使用します。

検証

イベントが到着したことを証明する

既知の成功例と失敗例を実行した後、これを実行します。最終的なイベント コントラクトがスニペットと異なる場合は、フォールバック テーブル名を置き換えます。

model-context-protocol-検証

MCP Server and Tool Telemetry 検証クエリ

sql
SELECT *
FROM mcp_tool_completed
ORDER BY timestamp_utc DESC
LIMIT 20;
論理結果ごとに 1 つのターミナル行を、予想されるステータス、識別子、単位、および UTC 時刻とともに確認します。
推論されたスキーマを検査し、再試行によってフィールド タイプが変更されたり、新しい論理イベント ID が生成されたりしないことを確認します。
保存されたフィールドで認証情報、生のペイロード、プロンプト、プライベート コンテンツ、および無制限のエラー メッセージを検索します。
ダッシュボードを完了として扱う前に、プロバイダーのタイムアウト、取り込みの拒否、およびプロセスのシャットダウンを実行します。

実装の参考資料

新しい運用パスを有効にする前に、イベント契約、データ安全性に関するガイダンス、上流の主要ドキュメントを確認してください。

生産境界

結果イベントを小さく、回復可能なものに保つ

このパターンが提供するのは、

  • 上流のワークフローの横にある、制限付きの SQL 対応の結果。
  • ダッシュボード、アラート、およびイベント間の相関関係の安定したフィールド。
  • 成功、失敗、再試行、タイムアウトの動作を検証するためのフィクスチャ駆動のパス。

このパターンでは提供されません

  • OTLP エクスポーター、自動収集パイプライン、または詳細なトレースと診断ログの代替。
  • ペイロードにイベント ID が含まれているという理由だけで、1 回だけ配信されます。
  • 生のプロバイダー ペイロード、ユーザー コンテンツ、資格情報、または規制されたデータを収集する許可。

イベントスキーマの開始点

クエリまたはスニペットを運用環境に適用する前に、行粒度、出力境界、必要なタイプ、プライバシー クラス、サンプル ペイロード、および検証チェックリストを確認してください。

関連製品の機能

このワークフローを続行します AIエージェントの監視

レビュー可能な SQL を使用して、エージェントの実行、ツールの使用、モデルのコスト、品質、製品の結果を結び付けます。

関連する SQL レシピ

SQL で次の質問に答えてください

このワークフローの構造化フィールドに対してクエリを実行し、結果の例を検査して、有用な回答をダッシュボードまたはアラートに変換します。

すべてのレシピを参照する

実装ファミリーごとに参照する

関連する統合パターンを比較する

この統合と組み合わせるテンプレート

さらなる統合