Saltar al contenido
Telemetry
Eventos estructurados receta SQL

Consultar eventos de llamadas de herramientas de IA anidadas

Filtre campos anidados con puntos y clasifique las herramientas que fallan sin aplanar la carga útil del evento original.

Intermedioagent_eventsRevisado 2026-07-27Probado con Apache DataFusion 45.2.0

Revisado por el equipo de producto Telemetry en . Compatibilidad con SQL, contrato de eventos, resultados sintéticos y advertencias operativas. Revisar los estándares y la propiedad

Pregunta respondida

¿Qué herramientas y argumentos de IA están asociados con la mayor cantidad de llamadas fallidas?

Los eventos de agentes estructurados a menudo llevan un contexto de herramienta anidado. Telemetry expone los valores anidados como columnas de puntos estables, lo que mantiene el SQL legible y al mismo tiempo conserva una forma de evento natural en la ingesta.

Contrato de evento

Campos que espera la consulta

CampoTipoPor que existe
timestamp_utcTimestampCuando se completó la llamada a la herramienta.
event_nameUtf8agent_tool_called para estos eventos.
data.tool_nameUtf8Identificador de herramienta anidado expuesto como una columna de puntos.
data.statusUtf8Estado anidado de éxito o error.
data.args.operationUtf8Operación segura y categorizada en lugar de argumentos crudos.
data.latency_msFloat64Latencia de llamada de herramienta anidada.
DataFusionSQL

Copiar la consulta

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;

Esta consulta de solo lectura se planifica y ejecuta en una tabla escrita vacía con Apache DataFusion 45.2.0. El resultado de la muestra determinista es sintético y se revisa por separado; valide tipos de campos, umbrales y definiciones comerciales con sus propios datos. Lea la metodología de prueba.

Resultado de la consulta

Tasa de fallas de llamadas de herramientas

La búsqueda de CRM es la operación de herramienta menos confiable y la más lenta en p95.

tool_nameoperationcallsfailuresfailure_rate_pctp95_latency_ms
crm_lookupsearch_contact842617,242180
order_apifetch_order2210441,99940
knowledge_searchsemantic_search4510190,42720

Salida de ejemplo sintético. Ejecute la consulta con su propio esquema de eventos y umbrales antes de utilizarla para decisiones operativas.

Tool-call failure rate: gráfico estático de valores sintéticos de failure_rate_pct del resultado del ejemplo Query Nested AI Tool-Call Events
SVG indexable de la salida del ejemplo determinista. Descárguelo para ver un artículo, un runbook o una revisión de diseño con atribución.

Reproducir el ejemplo

Descargar el accesorio público

El paquete JSON incluye el contrato de evento escrito, illustrative filas de entrada, SQL exacto, resultado esperado, notas de revisión y versión del motor. El CSV contiene el resultado mostrado.

Cómo funciona el SQL

  1. 1Los nombres de los campos con puntos están entre comillas dobles porque los puntos son parte del nombre de la columna inferida.
  2. 2La consulta agrupa tanto por herramienta como por operación categorizada, preservando suficiente contexto para distinguir diferentes comportamientos de una herramienta.
  3. 3Los argumentos sin procesar de la herramienta no deben registrarse de forma predeterminada. En su lugar, almacene categorías, identificadores y campos de resultados seguros.

Casos extremos para decidir

  • Mantenga estables los tipos de campos anidados a medida que evolucionan los esquemas.
  • Diferentes herramientas pueden tener diferentes semánticas de éxito; normalizar los valores de estado en el momento de la instrumentación.
  • Los argumentos en bruto de alta cardinalidad pueden crear problemas de privacidad, costos y usabilidad.

Panel recomendado

  • Gráfico de barras: failure_rate_pct por tool_name
  • Gráfico de líneas: p95_latency_ms a lo largo del tiempo dividido por herramienta
  • Tabla: fallas recientes con error_type y el flujo de trabajo del agente

Guía de alerta

Alerte cuando la tasa de falla de una herramienta de producción cruce su umbral en un volumen significativo y enrute la alerta a la integración propietaria.

Leer configuración de alerta

Pon la receta a trabajar

Instrumentación y guías relacionadas.

Definir los datos de origen

Esquemas de eventos para este análisis.

Continuar el análisis

Ejecútelo en eventos reales.

Crea una tabla, adapta los campos y guarda el resultado.

Comience gratis, envíe eventos estructurados y utilice el resultado de la consulta como un gráfico, un widget de panel compartido o una entrada de alerta.

Obtén una clave API