# 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.

Aplica a: el motor de Sypnia (código abierto, en tu propia infraestructura) y Sypnia Cloud (servicio pago). Estado: al lanzar.  
Fuente: https://docs.sypnia.com/es/concepts/traces/

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

1. **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 `traceparent` del W3C. También envía el id de la sesión, así la traza entra a la sesión.
2. **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.
3. **Cualquier otro backend entra por OpenTelemetry.** Un exportador de trazas OTLP/HTTP que respete `traceparent` agrega sus spans a la misma traza. Mira [OpenTelemetry](https://docs.sypnia.com/es/sdks/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](https://docs.sypnia.com/es/concepts/problems): 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](https://docs.sypnia.com/es/api/otlp).

## 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](https://docs.sypnia.com/es/cloud/data-location-and-retention).
- Las duraciones de todas las peticiones alimentan los números de la API en [Rendimiento](https://docs.sypnia.com/es/concepts/performance), abra alguien la traza o no.

## Ejemplo: el pago fallido

La traza de un clic en **Pagar**, como la muestra Sypnia:

```text
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](https://docs.sypnia.com/es/api/traces). Lo que cada SDK traza de forma automática está en [Node](https://docs.sypnia.com/es/sdks/node) y [Next.js](https://docs.sypnia.com/es/sdks/nextjs).
