Trazas
Cómo sigue Sypnia una petición desde un clic en el navegador hasta tu API y las llamadas a la base de datos que hay detrás, y qué guarda una traza.
Esta página es para quien quiere ver dónde gastó su tiempo una petición o dónde falló. Las trazas son parte del motor de código abierto y funcionan igual en Sypnia Cloud.
Una traza es el camino de una petición por tu app: del navegador a tu API y a las llamadas a la base de datos y a los servicios que hay detrás, con lo que tardó cada paso y si falló.
Spans
Una traza está hecha de spans. Un span es un paso. Todos los spans tienen la misma forma, venga de donde venga:
| Campo | Significado |
|---|---|
| Nombre | Qué es el paso: POST /api/checkout, SELECT carts. |
| Tipo | Qué clase de paso es: una petición como la vio el navegador, una petición que atendió un servicio, una llamada a la base de datos, una llamada a otro servicio o un paso interno. |
| Servicio | Qué parte de tu app lo corrió, por ejemplo shop-api. El navegador es browser. |
| Inicio y duración | Cuándo empezó y cuánto tardó. |
| Estado | Si salió bien o falló. En una traza parcial, un paso también puede seguir corriendo. |
| Atributos | Un conjunto limitado de detalles, como la ruta o el código de estado: hasta 64 por span, con valores de hasta 256 caracteres. |
| Padre | El span que lo causó. Es lo que le da a la traza su forma de árbol. |
Las llamadas a la base de datos son spans como cualquier otro. La forma es compatible con OpenTelemetry, así que los spans de un SDK de Sypnia y los de un exportador de OpenTelemetry quedan en la misma traza.
Cómo se une una traza
- El SDK del navegador la empieza. Cuando la página llama a tu API, el SDK crea un id de traza y lo envía con la petición en el encabezado estándar
traceparentdel W3C. También envía el id de la sesión, así la traza entra a la sesión. - Tu servidor la continúa. Los SDK de Node y de Next.js leen el encabezado y trazan cada petición que llega, de forma automática. No tienes que poner ninguna llamada a mano. Registran la petición y las llamadas a la base de datos y a otros servicios que hace.
- Cualquier otro backend entra por OpenTelemetry. Un exportador de trazas OTLP/HTTP que respete
traceparentagrega sus spans a la misma traza. Mira OpenTelemetry.
Una petición que no empieza en un navegador, como un webhook o una tarea programada, es una traza propia, que empieza el servidor.
Una traza une partes de un solo proyecto. Envía tu frontend y tu backend al mismo proyecto.
Cuándo falló un span
Una llamada falló cuando no recibe respuesta, responde 400, o responde 500 o más. Una petición que recibió tu servidor falló cuando responde 500 o más, o lanza un error. Los spans que llegan por OpenTelemetry fallaron cuando su estado es ERROR o traen una excepción.
Otras respuestas, como 401, 404 o 409, son respuestas, no fallas.
Un span fallido es una falla en el sentido de Problemas: el span fallido más profundo de una traza decide a qué problema pertenece la traza.
Peticiones que nunca terminan
Una petición que sigue corriendo a los 20 segundos se reporta en ese momento como una traza parcial: los spans que terminaron, y las llamadas que seguían en curso con el tiempo que llevaban corriendo (SDK de Node y de Next.js).
- Si la petición termina después, su traza completa reemplaza a la parcial.
- Si nunca termina, porque la plataforma la mató, la traza parcial es todo lo que hay. Cuenta como una falla del servidor y abre un problema con un título como «Timeout: POST /api/checkout did not finish». Las llamadas que estaban en curso te dicen qué estaba esperando.
Qué guarda una traza, y qué no
Sypnia guarda lo necesario para ver la forma y los tiempos de una petición:
- el nombre, el tipo, los tiempos y el estado de cada span,
- el método, la ruta y el código de estado de las peticiones,
- el destino de una llamada: el nombre de una tabla, el host y la ruta de un servicio,
- un conjunto limitado de atributos por span.
Una petición que atendió tu servidor conserva hasta 200 de las llamadas que hizo, y una traza conserva hasta 500 spans. Más allá de eso los spans se cuentan y no se guardan.
No guarda los cuerpos de las peticiones ni de las respuestas, ni cookies, ni encabezados. Los atributos cuyo nombre contiene authorization, cookie, password, secret o token se descartan en la ingesta. Los límites exactos están en la referencia de la API.
Cómo se cuentan y cuánto se guardan
- En Sypnia Cloud, una traza cuenta como un evento, tenga los spans que tenga. La petición del navegador y los spans del servidor bajo el mismo id de traza son una sola traza.
- Las trazas se guardan el mismo tiempo que los eventos. Mira Ubicación y retención de los datos.
- Las duraciones de todas las peticiones alimentan los números de la API en Rendimiento, abra alguien la traza o no.
Ejemplo: el pago fallido
La traza de un clic en Pagar, como la muestra Sypnia:
click «Pay $64.00» browser
└─ POST /api/checkout 412 ms 400 shop-api
├─ SELECT carts 18 ms ok database
├─ SELECT cart_items 22 ms ok database
└─ POST /v1/payments 340 ms 400 payment service <- fallóParticiparon tres servicios: el navegador, la API de la tienda y el servicio de pagos. Las dos llamadas a la base de datos funcionaron. La llamada al servicio de pagos respondió 400, y es el span fallido más profundo, así que esta traza pertenece al problema sobre la llamada de pago. Después la API le respondió 400 a la página, que no mostró nada, y el cliente volvió a hacer clic.
La traza dice dónde se rompió. El problema dice por qué: la petición al servicio de pagos no llevaba monto, porque el checkout lee cart.total y la versión desplegada ayer le cambió el nombre a cart.totalCents.
Referencia
Los campos de una traza y de un span están en la referencia de la API. Lo que cada SDK traza de forma automática está en Node y Next.js.