Docs

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 MotorNube Al lanzar

Ver como Markdown
En esta página
  1. Spans
  2. Cómo se une una traza
  3. Cuándo falló un span
  4. Peticiones que nunca terminan
  5. Qué guarda una traza, y qué no
  6. Cómo se cuentan y cuánto se guardan
  7. Ejemplo: el pago fallido
  8. Referencia

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:

CampoSignificado
NombreQué es el paso: POST /api/checkout, SELECT carts.
TipoQué 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.
ServicioQué parte de tu app lo corrió, por ejemplo shop-api. El navegador es browser.
Inicio y duraciónCuándo empezó y cuánto tardó.
EstadoSi salió bien o falló. En una traza parcial, un paso también puede seguir corriendo.
AtributosUn conjunto limitado de detalles, como la ruta o el código de estado: hasta 64 por span, con valores de hasta 256 caracteres.
PadreEl 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.

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:

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. Lo que cada SDK traza de forma automática está en Node y Next.js.

Secciones

Empieza aquíQué es Sypnia, cómo funciona, qué es código abierto y qué es la nube de pago, y las dos maneras de recibir tu primer problema en palabras claras.ConceptosLas diez ideas de las que está hecho Sypnia, cada una definida con precisión, desde un proyecto y sus llaves hasta los problemas, las trazas y las alertas.SDKCómo envía tu app los datos a Sypnia. Un SDK para el navegador, uno para Node, uno para Next.js, y la entrada de OpenTelemetry para cualquier otro backend.El agenteCómo analiza Sypnia un problema, qué escribe, qué le envía a un modelo y qué nunca hace.MCP y skillsConecta tu agente de código a Sypnia para que pregunte qué está fallando en producción, lea lo que necesita para arreglarlo y configure Sypnia por ti.Referencia de la APILa API HTTP de Sypnia: una sola API para el motor de código abierto y para Sypnia Cloud, con cada endpoint, parámetro, respuesta y error.Referencia de la CLIEl comando sypnia: cómo instalarlo, qué variables lee, qué significan sus códigos de salida y dónde está documentado cada comando.Alojamiento propioQué corres cuando alojas tú mismo el motor de Sypnia, qué necesitas, cuánto cuesta y qué no tienes frente a Sypnia Cloud.Cómo está construido el motorTodo el motor de Sypnia en una página, desde un clic en tu app hasta la frase que lee tu agente de código, con las reglas de diseño y el código que las sostiene.Sypnia CloudCómo funciona el servicio pago, desde las organizaciones y los roles hasta los planes, los límites, la facturación, dónde viven tus datos, la GitHub App y el soporte.Privacidad y seguridadQué recoge Sypnia de tu app y de sus usuarios, qué no recoge nunca, cómo funciona el enmascarado, cómo eliminar datos y cómo se protege el servicio.LicenciasQué licencia cubre cada parte de Sypnia, qué puedes hacer con ella, cómo se puede usar el nombre, y los términos de una contribución.GuíasRecetas paso a paso para las formas comunes de usar Sypnia, desde apps hechas con constructores de IA y Next.js en Vercel hasta Supabase, source maps en CI, correos de alerta desde tu propio motor, y venir desde Sentry.ReferenciaLas páginas donde se consulta, desde el esquema de eventos y el glosario hasta lo planeado, el registro de cambios y las preguntas frecuentes.
↑↓ para moverte↵ para abrirEsc para cerrar