本文へ移動
Telemetry
構造化イベント SQL レシピ

ネストされた AI ツール呼び出しイベントのクエリ

元のイベント ペイロードを平坦化することなく、点線でネストされたフィールドをフィルターし、失敗したツールをランク付けします。

中級者agent_eventsレビュー済み 2026-07-27テスト済み アパッチ DataFusion 45.2.0

レビュー者 Telemetry 製品チーム . SQL の互換性、イベント コントラクト、合成出力、および操作上の注意事項. 基準と所有権を確認する

質問に回答しました

最も失敗した呼び出しに関連する AI ツールと引数はどれですか?

構造化されたエージェント イベントは、多くの場合、入れ子になったツール コンテキストを運びます。 Telemetry は、ネストされた値を安定した点線の列として公開します。これにより、取り込み時の自然なイベントの形状を維持しながら、SQL の読み取り可能性が維持されます。

イベント契約

クエリが期待するフィールド

フィールド種類なぜ存在するのか
timestamp_utcTimestampツールの呼び出しが完了したとき。
event_nameUtf8これらのイベントの場合は agent_tool_called。
data.tool_nameUtf8点線の列として公開されるネストされたツール識別子。
data.statusUtf8ネストされた成功または失敗のステータス。
data.args.operationUtf8生の引数ではなく、安全で分類された操作。
data.latency_msFloat64ネストされたツール呼び出しのレイテンシー。
DataFusion SQL

クエリをコピーする

sql
SELECT
  "data.tool_name" AS tool_name,
  "data.args.operation" AS operation,
  COUNT(*) AS calls,
  SUM(CASE
    WHEN "data.status" = 'failed' THEN 1 ELSE 0
  END) AS failures,
  100.0 * SUM(CASE
    WHEN "data.status" = 'failed' THEN 1 ELSE 0
  END) / NULLIF(COUNT(*), 0) AS failure_rate_pct,
  approx_percentile_cont("data.latency_ms", 0.95) AS p95_latency_ms
FROM agent_events
WHERE event_name = 'agent_tool_called'
  AND timestamp_utc >= now() - INTERVAL '7 days'
GROUP BY "data.tool_name", "data.args.operation"
HAVING COUNT(*) >= 20
ORDER BY failure_rate_pct DESC, calls DESC;

この読み取り専用クエリは、空の型付きテーブルに対して計画され、実行されます。 アパッチ DataFusion 45.2.0。決定論的なサンプル出力は合成され、個別にレビューされます。フィールド タイプ、しきい値、ビジネス定義を独自のデータと照合して検証します。 テスト方法を読んでください。

クエリ結果

ツール呼び出しの失敗率

CRM ルックアップはツール操作の中で最も信頼性が低く、p95 と最も遅くなります。

tool_nameoperationcallsfailuresfailure_rate_pctp95_latency_ms
crm_lookupsearch_contact842617.242,180
order_apifetch_order2,210441.99940
knowledge_searchsemantic_search4,510190.42720

合成出力例。運用上の決定に使用する前に、独自のイベント スキーマとしきい値に対してクエリを実行します。

Tool-call failure rate: Query Nested AI Tool-Call Events 結果例からの合成 failure_rate_pct 値の静的チャート
決定論的な出力例のインデックス可能な SVG。記事、ランブック、または出典を明示した設計レビューのためにダウンロードしてください。

例を再現する

パブリックフィクスチャをダウンロードする

JSON バンドルには、型付きイベント コントラクトが含まれています。 illustrative 入力行、正確な SQL、予想される出力、レビューメモ、およびエンジンのバージョン。 CSV には、表示された結果が含まれます。

SQL の仕組み

  1. 1ドットは推定された列名の一部であるため、ドット付きフィールド名は二重引用符で囲まれています。
  2. 2クエリはツールと分類された操作の両方によってグループ化され、1 つのツールのさまざまな動作を区別するのに十分なコンテキストを保持します。
  3. 3デフォルトでは、生のツール引数はログに記録されません。代わりに、安全なカテゴリ、識別子、および結果フィールドを保存します。

決定すべきエッジケース

  • スキーマが進化しても、ネストされたフィールド タイプを安定した状態に保ちます。
  • ツールが異なれば、成功のセマンティクスも異なる場合があります。インストルメンテーション時にステータス値を正規化します。
  • カーディナリティの高い生の引数は、プライバシー、コスト、および使いやすさの問題を引き起こす可能性があります。

推奨されるダッシュボード

  • 棒グラフ: failure_rate_pct by tool_name
  • 折れ線グラフ: ツールごとに分割された p95_latency_ms の経時変化
  • 表: error_type とエージェントのワークフローに関する最近の障害

アラートガイダンス

実稼働ツールの障害率が有意な量でしきい値を超えたときにアラートを生成し、そのアラートを所有する統合にルーティングします。

アラート設定を読む

レシピを活用する

関連する機器とガイド

ソースデータを定義する

この分析のイベント スキーマ

分析を続ける

実際のイベントで実行する

テーブルを作成し、フィールドを調整して、結果を保存します

無料で始めて、構造化されたイベントを送信し、クエリ結果をグラフ、共有ダッシュボード ウィジェット、またはアラート入力として使用します。

API キーを取得する