> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zelto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Trazas

> Almacena y explora las trazas y los registros de OpenTelemetry de tus agentes de voz: una traza por llamada y un árbol de spans.

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](#vincular-trazas-a-conversaciones).

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](/es/docs/integrations/livekit).
   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:

   ```python theme={null}
   span.set_attribute("session.id", external_call_id)
   ```

   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:

```json theme={null}
{
  "zelto.agent_external_id": "collections-agent",
  "zelto.agent_provider": "livekit",
  "session.id": "unique-call-or-room-id"
}
```

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](/es/docs/conversations) cuando Zelto
  puede relacionarlas.

Las trazas se conservan durante 90 días.

## Enviar telemetría

Empieza con [Enviar trazas a Zelto](/es/docs/guides/send-traces): incluye una
primera traza ejecutable, identidad del agente, vinculación de llamadas,
registros y solución de problemas.

<Note>
  Si tus llamadas proceden de [Vapi](/es/docs/integrations/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](/es/docs/integrations/vapi#trazas-sin-instrumentalizar-nada).
</Note>

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](/es/docs/integrations/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](/es/docs/integrations/livekit#transmitir-trazas-opentelemetry) 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](/es/docs/settings#miembros-e-invitaciones)
`owner` o `admin`.

Configura el endpoint de ingestión de Zelto y autentica el exportador con la clave
como token Bearer:

```bash theme={null}
OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.zelto.ai"
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20<your-ingest-key>"
OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
```

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.

<Note>
  El exportador HTTP de **Python** usado en estos ejemplos envía protobuf.
  Mantén `OTEL_EXPORTER_OTLP_PROTOCOL` como `http/protobuf`.
</Note>

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.

<Note>
  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`.
</Note>

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](/es/docs/guides/send-traces#json-nativo-sin-sdk-de-opentelemetry).
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](/es/docs/tool-calls) — compara el uso, los resultados y la duración de las herramientas entre llamadas y agentes.
* [Conversaciones](/es/docs/conversations) — la vista de transcripción y análisis; una traza enlaza con su conversación cuando coincide el identificador de sesión.
* [LiveKit](/es/docs/integrations/livekit) — configura el exportador de OpenTelemetry de un agente de LiveKit para transmitir trazas a Zelto.