跳至主要內容
Telemetry
結構化事件 SQL查詢範例

查詢巢狀 AI 工具呼叫事件

過濾點巢狀欄位並對失敗的工具進行排名,而無需展平原始事件負載。

中級agent_events已審查 2026-07-27測試用 阿帕奇 DataFusion 45.2.0

審閱者 Telemetry產品團隊 . SQL 相容性、事件契約、合成輸出和操作注意事項. 審查標準和所有權

問題已回答

哪些人工智慧工具和參數與失敗次數最多的呼叫相關?

結構化代理事件通常帶有巢狀的工具上下文。 Telemetry 將巢狀值公開為穩定的點列,這使 SQL 保持可讀性,同時保留攝取時的自然事件形狀。

活動合約

查詢期望的欄位

欄位型別為什麼存在
timestamp_utcTimestamp當工具呼叫完成時。
event_nameUtf8agent_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查詢按工具和分類操作進行分組,保留足夠的上下文來區分一種工具的不同行為。
  3. 3預設情況下不應記錄原始工具參數。而是儲存安全類別、識別符號和結果欄位。

需要決定的邊緣情況

  • 隨著架構的發展,保持巢狀欄位型別穩定。
  • 不同的工具可能有不同的成功語義;在檢測時標準化狀態值。
  • 高基數原始參數可能會產生隱私、成本和可用性問題。

推薦儀表板

  • 條形圖:failure_rate_pct by tool_name
  • 折線圖:p95_latency_ms 隨著時間的推移按工具劃分
  • 資料表:error_type 和代理工作流程的最近故障

警示指導

當生產工具的故障率在有意義的數量上超過其閾值時發出警示,並將警示路由到所屬整合。

讀取警示設定

讓查詢範例發揮作用

相關埋點和指南

定義源資料

此分析的事件模式

繼續分析

在真實事件中執行它

建立資料表,調整欄位並儲存結果

免費開始,傳送結構化事件,並將查詢結果用作圖表、共享儀表板小工具或警示輸入。

獲取 API 金鑰