Telemetry
Structured events SQL recipe

Query Nested AI Tool-Call Events

Filter dotted nested fields and rank failing tools without flattening the original event payload.

Intermediateagent_eventsReviewed 2026-07-27Tested with Apache DataFusion 45.2.0

Reviewed by the Telemetry product team on . SQL compatibility, event contract, synthetic output, and operational caveats. Review standards and ownership

Question answered

Which AI tools and arguments are associated with the most failed calls?

Structured agent events often carry nested tool context. Telemetry exposes nested values as stable dotted columns, which keeps the SQL readable while preserving a natural event shape at ingestion.

Event contract

Fields the query expects

FieldTypeWhy it exists
timestamp_utcTimestampWhen the tool call completed.
event_nameUtf8agent_tool_called for these events.
data.tool_nameUtf8Nested tool identifier exposed as a dotted column.
data.statusUtf8Nested success or failed status.
data.args.operationUtf8Safe, categorized operation rather than raw arguments.
data.latency_msFloat64Nested tool-call latency.
DataFusion SQL

Copy the query

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;

This read-only query is planned and executed against an empty typed table with Apache DataFusion 45.2.0. The deterministic sample output is synthetic and reviewed separately; validate field types, thresholds, and business definitions against your own data. Read the testing methodology.

Query result

Tool-call failure rate

CRM lookup is both the least reliable tool operation and the slowest at p95.

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

Synthetic example output. Run the query against your own event schema and thresholds before using it for operational decisions.

Tool-call failure rate: static chart of synthetic failure_rate_pct values from the Query Nested AI Tool-Call Events example result
Indexable SVG of the deterministic example output. Download it for an article, runbook, or design review with attribution.

Reproduce the example

Download the public fixture

The JSON bundle includes the typed event contract, illustrative input rows, exact SQL, expected output, review notes, and engine version. The CSV contains the displayed result.

How the SQL works

  1. 1Dotted field names are double-quoted because the dots are part of the inferred column name.
  2. 2The query groups by both tool and categorized operation, preserving enough context to distinguish different behaviors of one tool.
  3. 3Raw tool arguments should not be logged by default. Store safe categories, identifiers, and outcome fields instead.

Edge cases to decide

  • Keep nested field types stable as schemas evolve.
  • Different tools may have different success semantics; normalize status values at instrumentation time.
  • High-cardinality raw arguments can create privacy, cost, and usability problems.

Recommended dashboard

  • Bar chart: failure_rate_pct by tool_name
  • Line chart: p95_latency_ms over time split by tool
  • Table: recent failures with error_type and agent workflow

Alert guidance

Alert when a production tool's failure rate crosses its threshold at meaningful volume, and route the alert to the owning integration.

Read alert setup

Put the recipe to work

Related instrumentation and guides

Define the source data

Event schemas for this analysis

Continue the analysis

Run it on real events

Create a table, adapt the fields, and save the result

Start free, send structured events, and use the query result as a chart, shared dashboard widget, or alert input.

Get an API key