Contexto: Un trace es una interacción completa entre la plataforma y un servicio externo: la solicitud enviada y la respuesta recibida. Es la unidad principal de análisis y donde se resuelve la mayoría de los diagnósticos.
Audiencia: funcionarios de soporte que necesitan determinar en qué punto falló un trámite concreto.
Cuándo aplicar: cuando ya sabes qué trámite o qué persona reportó el problema y necesitas la evidencia de qué ocurrió.
Traces
Cada vez que la plataforma llama a un servicio externo se generan dos registros: uno al enviar la solicitud y otro al recibir la respuesta. Ambos comparten un identificador de correlación, y ese par forma un trace.
Introducción
El identificador de correlación es un valor único por interacción. Es lo que permite reconstruir qué pasó en un caso puntual y, sobre todo, es la referencia que conviene citar en un reporte: con ese dato el proveedor del servicio externo abre exactamente la misma interacción, sin tener que reconstruirla.
Resultado de un trace
La herramienta clasifica automáticamente el resultado de cada trace a partir de sus eventos.
| Resultado | Qué significa | Cómo leerlo |
|---|---|---|
| “ok” | La interacción finalizó correctamente. No hay falla asociada. | Si el ciudadano reporta un problema y el trace es correcto, la falla no está en esa integración. Revisa el resto del flujo del trámite. |
| “error” | El servicio externo respondió con un error. | La falla está del lado del servicio consultado. El detalle indica el código y el mensaje devueltos. |
| “timeout” | El servicio no respondió dentro del tiempo de espera. | Indisponibilidad o lentitud del servicio externo. |
| “aborted” | La interacción se interrumpió antes de completarse. | Suele acompañar cortes de red o cancelaciones del lado de quien origina la llamada. |
Cómo buscar un trace
1. Abrir la vista de Traces
Entra a “Traces” desde el menú lateral. El listado muestra las interacciones más recientes de tu organización, de la más nueva a la más antigua.
2. Acotar la ventana de tiempo
Ajusta el periodo al momento en que ocurrió el reporte. Es el filtro que más reduce el ruido: sin él, el listado devuelve todo el tráfico reciente.
3. Buscar por el dato que tengas
La barra de búsqueda acepta varios tipos de dato:
| Dato | Cuándo usarlo |
|---|---|
| Identificador del trace | Cuando el reporte ya lo incluye. Es la vía más directa. |
| Correo electrónico | Para ubicar las interacciones asociadas a una persona usuaria. |
| Etiquetas | Para acotar por marcas de negocio adjuntas al evento. |
También puedes filtrar por servicio y por estado desde la barra superior, y combinar esos filtros con la búsqueda.
4. Abrir el trace
Selecciona un resultado del listado. Se despliega la línea temporal de la interacción con los eventos en orden cronológico.
Vista del detalle de un trace
Pantalla que aparece al seleccionar un trace del listado. Muestra:
- La línea temporal: los eventos en orden, desde la solicitud hasta la respuesta.
- La duración: cuánto tardó cada evento, en milisegundos. Un valor alto señala lentitud del servicio externo.
- Las etiquetas: las marcas de negocio asociadas al evento.
- El contenido del registro: el detalle completo de lo que se envió y lo que se recibió.
Con esa información se determina en qué punto de la cadena se produjo la falla y con qué mensaje respondió el servicio.
Tips y recomendaciones
Antes de buscar
Ten a mano el dato más específico que tengas del reporte: identificador del trace, correo de la persona usuaria, o la hora aproximada. Cuanto más específico, menos ruido.
Durante la búsqueda
Si la búsqueda no devuelve nada, amplía la ventana de tiempo antes de concluir que no hay registro. Un desfase de zona horaria o unos minutos de diferencia bastan para dejar fuera el caso.
Después de encontrarlo
Copia el identificador de correlación y regístralo en el ticket. Ese dato es lo que convierte un reporte en un caso trazable por ambas partes.
Errores comunes y cómo evitarlos
| Error | Causa | Solución |
|---|---|---|
| La búsqueda no devuelve resultados | La ventana de tiempo es demasiado estrecha, o el dato buscado no coincide. | Amplía el periodo y prueba con otro dato: si buscaste por correo, prueba por etiqueta o por servicio. |
| Se concluye que hubo falla sin abrir el trace | El listado muestra el resultado, pero no el motivo. | Abre el detalle. El código y el mensaje de respuesta son la evidencia; el resultado por sí solo no lo es. |
| Se reporta sin el identificador | El ticket queda sin referencia trazable. | Registra siempre el identificador de correlación en el ticket. |
Glosario técnico
- Trace: conjunto de eventos que comparten un identificador de correlación. Representa una interacción completa.
- Evento: registro individual de un momento de la interacción, la solicitud o la respuesta.
- Identificador de correlación: valor único que vincula los eventos de una misma interacción.
- Etiquetas: marcas de negocio adjuntas a cada evento, utilizables como filtro de búsqueda.
Ver también
Antes de buscar un trace:
- Servicios — descartar primero una afectación general.
Después de encontrar el trace:
- Incidentes — verificar si la falla ya está registrada como incidente.
Relacionados:
- Diagnosticar un reporte — el procedimiento completo, de reporte a evidencia.
- Sovra Log — conceptos y alcance de la herramienta.