Skip to main content
Las trazas muestran mediante OpenTelemetry lo que ocurrió dentro de una llamada. Cada llamada o sesión es una traza: un árbol de spans —una generación de LLM, un paso de texto a voz, otro de voz a texto, una llamada a una herramienta o tu propio código— junto con los registros que emiten esos pasos. Zelto guarda esta telemetría para mostrar, llamada por llamada, dónde se consumieron el tiempo y los tokens y qué falló. Así no necesitas una plataforma de trazas y otra de registros por separado. Abre Trazas en la barra lateral para ver una fila por traza, con el estado y la duración junto al nombre del span raíz. Los tokens y el costo están ocultos por defecto; actívalos en Columnas. Selecciona una fila para explorar el árbol o la cronología y consultar las entradas, salidas, atributos y registros de cada span en el panel lateral. En las vistas Árbol y Cascada de paneles estrechos, selecciona un span para abrir sus detalles y usa Volver a los spans para regresar al árbol. Las primeras 50 filas se cargan antes que el total. Puedes seguir navegando por las páginas mientras se calcula; los totales grandes muestran su magnitud, por ejemplo >1.000.000. Los controles de vista, columnas y densidad están junto a los filtros principales. Un selector en la parte superior alterna entre dos vistas. Trazas, la predeterminada, muestra una fila por llamada. Spans muestra una fila por span de todas las trazas: una lista plana que puedes filtrar por tipo, modelo, agente y periodo para comparar pasos individuales, por ejemplo todos los spans llm del último día. Ambas vistas comparten los mismos filtros, alcance y periodo. Sin filtro de fecha, la lista muestra las últimas 48 horas. El control de fechas ofrece rangos rápidos (últimas 48 horas, 7 días, 30 días) o un desde / hasta personalizado, de hasta 30 días a la vez: un rango más amplio se limita a 30 días y el chip lo indica. Las trazas más antiguas siguen ahí: elige un rango para llegar a ellas, hasta el periodo de retención de 90 días. Abrir una traza, o la pestaña Traza de una llamada, no tiene ningún límite de periodo. Si un rango es demasiado pesado para tu volumen, la página indica que las trazas no están disponibles temporalmente: vuelve a intentarlo o acota el rango.

​
Explorar una traza

En la página completa, usa el icono de copiar junto al ID de la traza en el encabezado para copiar el ID completo. Abrir conversación abre la llamada vinculada. Si dice Sin conversación vinculada, el icono de información abre la guía de conexión. El visor tiene dos paneles: navegación de spans a la izquierda y detalles a la derecha. Empieza en Línea de tiempo y recuerda la vista y el ancho elegidos. Arrastra el divisor, o enfócalo y usa las flechas, para cambiar el ancho. Las vistas, la búsqueda y el botón para contraer comparten la barra izquierda. Contrae la navegación para dar más espacio a los detalles; al expandirla se restauran la selección, el zoom y el ancho. El audio continúa reproduciéndose. La búsqueda funciona en las tres vistas; filtrar Pistas conserva el eje completo. El panel izquierdo ofrece tres vistas con una selección compartida:
  • Árbol muestra la jerarquía, los tipos de spans, la duración y los tokens.
  • Línea de tiempo agrega barras sobre un eje de tiempo compartido. Comparte la búsqueda y los controles para contraer la jerarquía con Árbol.
  • Pistas agrupa STT, LLM, herramientas, TTS y los demás tipos registrados. Los spans concurrentes ocupan filas separadas. Si el nombre no cabe en una barra, usa Árbol o selecciona la barra para consultar los detalles.
Usa + y − para cambiar el zoom en las vistas temporales y Ajustar para ver el rango completo. Cambiar de vista conserva el zoom y la selección. Selecciona un span para ver su fecha, duración, modelo, tokens y costo a la derecha. Vista previa contiene la entrada y la salida; Atributos, los metadatos y sus filtros; y Registros, los logs del span. Evento anterior y Evento siguiente recorren la llamada en orden temporal y conservan la pestaña de detalles seleccionada. En spans de LLM, el JSON con mensajes de chat se abre en la vista Formateado: cada mensaje muestra su rol (por ejemplo, sistema, usuario o asistente) sobre texto legible que se ajusta al ancho del panel. Admite listas de mensajes, mensajes individuales y objetos con una lista messages. Usa Sin formato para ver la entrada y la salida originales, o vuelve a Formateado. Las llamadas a herramientas y otros metadatos están en Campos adicionales. Los bloques de texto se muestran como texto; los demás bloques permanecen visibles como JSON. El texto simple y el JSON incompleto o no reconocido conservan su presentación original. Selecciona Resumen de la traza en el panel izquierdo para abrir las pestañas Resumen, Atributos y Registros. Resumen muestra las estadísticas y Duración por paso; en la página completa, también contiene Llamada, Transcripción y Monitores para una llamada vinculada. Atributos agrupa los valores registrados por span para conservar el contexto de las claves repetidas. Registros muestra todos los registros de la traza en orden temporal, incluidos los que no tienen un span correspondiente. Selecciona el nombre de un span debajo de un registro para inspeccionarlo. Selecciona Llamada, Transcripción o Monitores para cargar ese panel de la llamada vinculada; vuelve a seleccionarlo para cerrarlo. Si la traza está vinculada a una conversación con audio, el reproductor permanece debajo del panel izquierdo. Puedes reproducir, pausar, buscar un momento, cambiar la velocidad o descargar la grabación. Cambiar de span o de vista no interrumpe la reproducción. En pantallas estrechas, seleccionar un span o el resumen abre los detalles. Usa Volver a los spans o Escape para regresar. Los registros muestran milisegundos; pasa el cursor sobre la hora para ver la fecha y zona horaria.

​
Vincular trazas a conversaciones

Vincular una traza conecta sus tiempos, errores y uso de tokens con lo que ocurrió en la llamada. Puedes abrir la conversación desde el encabezado, consultar su transcripción y los resultados de monitores, y escuchar la grabación mientras inspeccionas los spans. El audio, las transcripciones y los resultados aparecen cuando están disponibles en la conversación; vincularla no genera datos que falten.
  1. Envía la conversación a la misma organización. Usa la integración de tu proveedor o la API de ingesta de llamadas. Para llamadas enviadas por API, establece call.externalId con el ID de llamada, sala o sesión del proveedor. Exportar solo trazas no crea una conversación.
  2. Envía ese mismo ID con la traza. Establece session.id en los spans o en el recurso OpenTelemetry con el mismo ID externo de la conversación. Por ejemplo, dentro de un span activo en Python:
    Zelto también reconoce call.id, gen_ai.conversation.id, conversation.id, zelto.reference_id, livekit.room, livekit.room_name, room.name y lk.room_name. Estos atributos son referencias externas de la llamada, no el ID de la traza. Con JSON nativo, usa el campo sessionRef del span. Para LiveKit, usa el mismo nombre de sala en call.externalId y en el atributo de sala o sesión de la traza.
  3. Vuelve a abrir la traza cuando ambos hayan llegado. El encabezado muestra Abrir conversación cuando Zelto encuentra una sola conversación coincidente. Puedes enviar la traza antes o después de la conversación.
Si sigue mostrando Sin conversación vinculada, comprueba que la conversación exista en la misma organización y que los IDs externos coincidan exactamente. Usa un ID único por llamada: Zelto no elige entre coincidencias duplicadas. Si un span ya tiene un agente asignado, debe coincidir con el agente de la conversación. Las trazas que abarcan varias conversaciones no muestran un enlace a una sola conversación.

​
Identifica agentes con tus propios IDs

Envía el ID estable del agente como zelto.agent_external_id en cada span o registro, o como atributo del recurso de OpenTelemetry si representa un solo agente:
Usa el mismo ID que agent.externalId en tus cargas de llamadas y consérvalo entre llamadas y versiones. session.id cambia en cada llamada y debe coincidir con su call.externalId. Zelto reutiliza el agente de tu organización o crea uno con el ID externo como nombre. La traza puede llegar antes que la llamada. Incluye zelto.agent_provider con el mismo proveedor que las llamadas (livekit en el ejemplo) para que ambos flujos creen el mismo agente. Si lo omites, se reutiliza una coincidencia única existente; los agentes nuevos usan zelto. Los IDs son cadenas sensibles a mayúsculas de hasta 255 caracteres; el proveedor admite hasta 50. Si el ID coincide con distintos agentes de varios proveedores, queda sin asignar hasta que especifiques el proveedor. Los IDs fusionados apuntan al agente que permanece. Si un exportador atiende a varios agentes, envía el ID en cada span o registro en vez de un recurso compartido. Sus atributos tienen prioridad sobre los del recurso. zelto.agent_id sigue siendo un UUID de Zelto y tiene prioridad: no pongas tu ID externo ahí, aunque también tenga formato UUID. En JSON nativo, usa las mismas claves dentro de attributes de cada span o registro. El campo agentId sigue significando un UUID de Zelto.

​
Qué contiene una traza

  • Spans, cada uno con un tipo normalizado: llm, tts, stt, vad, tool, code, telephony, livekit, session u other. Los spans de IA generativa exponen el modelo, los tokens y el costo para poder filtrarlos rápidamente.
  • Registros, asociados con un span o con la traza completa, con su nivel de gravedad y contenido.
  • Una referencia de sesión, como el identificador de sala, llamada o sesión, que enlaza la traza con su conversación cuando Zelto puede relacionarlas.
Las trazas se conservan durante 90 días.

​
Enviar telemetría

Empieza con Enviar trazas a Zelto: incluye una primera traza ejecutable, identidad del agente, vinculación de llamadas, registros y solución de problemas.
Si tus llamadas proceden de Vapi, Zelto crea las trazas automáticamente a partir de los registros de plataforma de cada llamada; no necesitas instalar un exportador. Consulta Vapi → Trazas.
Trazas recibe el estándar OTLP/HTTP, por lo que funciona con cualquier agente que tenga un exportador de OpenTelemetry. Esto incluye los agentes de LiveKit, cuyas sesiones ya instrumenta LiveKit. No necesitas escribir un cliente específico para Zelto, pero sí registrar un exportador OTLP que apunte a Zelto. Consulta LiveKit para ver el ejemplo completo. Crea una clave de ingestión de observabilidad de solo escritura para la organización. Se muestra una sola vez. Puedes crearla y copiar la configuración del exportador desde Configuración → Integraciones → Observabilidad o desde Trazas → Conectar agente; ambas opciones crean el mismo tipo de clave. Para crear o revocar claves necesitas el rol owner o admin. Configura el endpoint de ingestión de Zelto y autentica el exportador con la clave como token Bearer:
El exportador envía los spans a /v1/traces y los registros a /v1/logs; el SDK de OpenTelemetry añade estas rutas automáticamente. Zelto admite las dos codificaciones de OTLP/HTTP: protobuf, la predeterminada en la mayoría de los exportadores, y JSON. No admite gRPC en :4317; utiliza el endpoint HTTP. Las solicitudes de telemetría a /v1/traces, /v1/logs y /webhooks/otel admiten hasta 10 MB (10.000.000 bytes) por solicitud, medidos después de la descompresión. Las solicitudes más grandes reciben HTTP 413; reduce el tamaño del lote de exportación antes de volver a enviarlas.
El exportador HTTP de Python usado en estos ejemplos envía protobuf. Mantén OTEL_EXPORTER_OTLP_PROTOCOL como http/protobuf.
La tasa de ingestión se limita por organización. Si envías un volumen muy alto, algunas solicitudes pueden recibir 429 con una cabecera Retry-After. Respeta esa cabecera y reintenta con espera progresiva. Los reintentos y las colas de los exportadores tienen límites: vigila los errores y los lotes descartados. Si necesitas un volumen alto de forma habitual, pide a tu contacto de Zelto que amplíe el límite de la organización.
Si ninguna traza coincide con tus filtros, usa Borrar filtros o ajusta el periodo. Si tu organización aún no tiene trazas, comprueba que el exportador apunta al endpoint anterior y envía una clave válida en Authorization: Bearer.
Una respuesta HTTP 200 confirma la aceptación. Con ingestión en cola, los datos se consultan después del procesamiento asíncrono; el objetivo es 30 segundos con carga normal, no un máximo garantizado. La espera del exportador y las interrupciones pueden añadir demora. OTLP devuelve {} y JSON nativo devuelve {"received":true}.

​
JSON nativo

Si tu agente no admite OTLP, envía a /webhooks/otel un cuerpo JSON más sencillo con los spans y registros en el formato nativo de Zelto, utilizando la misma clave Bearer. Consulta el ejemplo completo. Usa OTLP si tu stack ya lo admite.

​
Importar invocaciones de herramientas anteriores

Si ya registras invocaciones de herramientas, pero todavía no exportas OpenTelemetry, Zelto puede proyectar ese historial como trazas para que la vista no quede vacía mientras configuras el exportador. Cada invocación de herramienta se convierte en un span tool y todas las invocaciones de una misma conversación comparten una traza. Solo se incluyen llamadas de los últimos 90 días, el periodo de conservación de las trazas. Pide a tu contacto de Zelto que ejecute esta importación para la organización.

​
Contenido relacionado

  • Invocaciones de herramientas — compara el uso, los resultados y la duración de las herramientas entre llamadas y agentes.
  • Conversaciones — la vista de transcripción y análisis; una traza enlaza con su conversación cuando coincide el identificador de sesión.
  • LiveKit — configura el exportador de OpenTelemetry de un agente de LiveKit para transmitir trazas a Zelto.