Saltar al contenido principal

Trazas

Una traza es el registro de extremo a extremo de un turno de agente. Comienza cuando un mensaje del usuario llega al Runtime, cubre cada generación de LLM, llamada a herramienta, consulta a fuente de datos e invocación de subagente, y termina cuando se devuelve la respuesta final del asistente. Cada paso anidado es un span; los spans forman el árbol padre-hijo que se visualiza en el visor de trazas.

Lista de Trazas​

La página de Trazas muestra todas las trazas ingestadas con su estado y métricas.

Los filtros se encuentran en la parte superior de la página:

  • Agent ID — Filtro de texto libre por identificador de agente.
  • Model — Filtro de texto libre por modelo (p. ej. gpt-4o, claude-3.5-sonnet).
  • Status — All · OK · ERROR.
  • From / To — Rango de fecha y hora absoluto. Déjelo en blanco para usar la ventana implícita.

Cada fila muestra:

  • Time — Marca de tiempo de inicio de la traza en hora local.
  • Trace ID — UUID truncado. Haga clic en la fila para abrir el visor.
  • Agent — Nombre del agente.
  • Model — Modelo principal utilizado por la traza (el modelo de la última generación cuando hay varios).
  • Status — Chip OK (naranja) o chip ERROR (rojo).
  • Duration — Latencia de reloj de pared desde el primer hasta el último span.
  • Tokens — Recuento total de tokens en todas las generaciones de la traza.
  • Cost — Costo total en USD calculado a partir de las tarifas por modelo del Gateway.

Export en la parte superior derecha descarga el conjunto de trazas filtrado en formato JSON para análisis sin conexión.

Visor de Trazas​

Al hacer clic en una traza se abre el visor. El encabezado resume la ejecución completa; el panel izquierdo es el árbol de spans; el panel derecho muestra el detalle del span seleccionado actualmente.

Encabezado de Traza​

  • Nombre del agente — Con un chip ERROR cuando algún span falló.
  • Trace ID — UUID completo.
  • Model / Duration / Tokens / Cost / Start / End — Valores agregados sobre la traza completa.

Agent Analytics en la parte superior derecha abre la vista consolidada del agente en la página de Agentes.

Árbol de Spans​

Cada nodo del árbol muestra:

  • Nombre del span — La etiqueta de operación (p. ej. lint_check, code_review_parse, repo_search, llm_suggestion_gen).
  • Agent — El atributo de agente bajo el que se registró el span.
  • Tokens y costo — Contribución por span.
  • Duration — Representada tanto como número y como barra de Gantt alineada con la línea de tiempo de la traza.
  • Punto de estado — Verde para spans OK, rojo para spans ERROR.

La barra de Gantt hace visible la ruta crítica de un vistazo: el span con la barra más ancha en la línea de tiempo más ajustada es el que determinó la latencia total.

Pestañas de Detalle del Span​

Haga clic en cualquier span para poblar el panel derecho con su detalle. El encabezado del panel muestra el chip de tipo del span (Tool, Generation, Retrieval, etc.), el estado, el modelo, la latencia, los tokens y el costo. A continuación se encuentran cuatro pestañas.

Entrada / Salida​

La pestaña predeterminada. Para spans de herramienta, Arguments / Response renderizan la llamada estructurada. Para spans de generación, Input muestra el prompt (o el arreglo de mensajes) y Output muestra la respuesta del asistente, incluido el texto de error exacto cuando el span falló.

Herramientas​

Para un span de generación, la pestaña Herramientas lista todas las herramientas que fueron presentadas al modelo en esa llamada, cada una con su nombre y descripción. Es la forma más rápida de confirmar qué capacidades tenía disponibles el agente al producir una respuesta y de detectar una herramienta faltante o inesperada.

Metadatos​

La pestaña Metadatos expone los campos subyacentes de OpenTelemetry:

  • Identificadores — Span ID, Trace ID, Parent Span.
  • Información del Span — Name, Service, Kind (internal, client, server), Operation (chat, tool, etc.), Model.
  • Atributos — Todos los atributos personalizados establecidos por la instrumentación (p. ej. agent-id, user-id, nombre de plantilla de prompt).

Línea de Tiempo​

La pestaña Línea de Tiempo ubica el span en la línea de tiempo de reloj de pared de la traza:

  • Posición del Span en la Traza — Barra horizontal que muestra dónde se sitúa el span a lo largo de la duración total.
  • Start Time / End Time — Marcas de tiempo absolutas.
  • Duration — Tiempo de reloj de pared del span.
  • Offset from Trace Start — Qué tan avanzado en la traza comenzó el span.
  • % of Total Trace — Proporción de la duración total de la traza que consumió este span.

El desplazamiento y el porcentaje son los campos que identifican la ruta crítica: el span con la mayor duración que comenzó más tarde generalmente merece la primera ronda de optimización.

Lectura de una Traza con Error​

Cuando una traza está marcada como ERROR, el árbol de spans muestra un punto rojo en cada span que falló. El error se propaga hacia arriba: en la captura de pantalla anterior, llm_suggestion_gen falló con Context length exceeded y propagó el error a su span padre lint_check. La pestaña Entrada/Salida del span fallido muestra el texto de error exacto que devolvió el LLM, que es la forma más rápida de identificar si la causa es el tamaño del prompt, un argumento incorrecto o una respuesta de herramienta demasiado larga para caber en el contexto.

Buenas Prácticas​

  • Filtre la lista de Trazas por Status = ERROR primero al realizar triaje. Cada traza con error es una señal directa.
  • Use las barras de Gantt para encontrar la ruta crítica antes de examinar spans individuales. Los agentes suelen tener un span cuello de botella por turno.
  • El campo Attributes de Metadatos es el lugar para agregar claves de correlación personalizadas (id de inquilino, id de sesión, id de solicitud). Agréguelas una vez en la instrumentación y estarán disponibles como filtro en toda la flota.

Páginas Relacionadas​