Trazas
Lista trazas y lee una con todos sus spans, de la petición del navegador a las llamadas a la base de datos.
En esta página
Una traza es una petición y todo lo que causó. El SDK del navegador la empieza y envía el encabezado W3C traceparent; el SDK del servidor o tu exportador de OpenTelemetry agrega los spans del servidor bajo el mismo id de traza.
Las trazas se guardan el mismo tiempo que los eventos (mira retención).
El objeto traza
Campos
-
idstring opcionalEl id de traza W3C, 32 caracteres hexadecimales.
-
started_attimestamp opcional -
duration_msinteger opcionalDel inicio del primer span al fin del último.
-
namestring opcionalEl nombre del span raíz, normalmente
MÉTODO ruta. -
methodstring o null opcional -
routestring o null opcionalLa ruta de la API, con los ids reemplazados.
-
status_codeinteger o null opcionalEl estado HTTP que respondió la raíz.
0cuando el navegador no recibió respuesta. -
failedboolean opcional -
partialboolean opcionaltruecuando la petición nunca terminó. -
serviceslista de string opcionalLos servicios que corrieron spans, y los que ellos llamaron (
peer.service). El navegador esbrowser. -
span_countinteger opcional -
dropped_spansinteger opcionalSpans por encima de los 500 que se guardan por traza.
-
session_idstring o null opcional -
problem_idstring o null opcionalEl problema del que esta traza es una ocurrencia.
-
environmentstring opcional -
releasestring o null opcional
El objeto span
Un paso de una traza. La misma forma sin importar quién lo envió, un SDK de Sypnia o un exportador de OpenTelemetry.
Campos
-
idstring opcional16 caracteres hexadecimales.
-
parent_idstring o null opcionalEl span que causó este.
nullen la raíz. -
namestring opcionalQué es el paso:
POST /api/checkout,SELECT carts,createPayment. -
kindstring opcionalbrowser: una petición tal como la vio el navegador.server: una petición atendida por un servicio.db: una llamada a una base de datos.http: una llamada HTTP saliente.internal: cualquier otra cosa. -
servicestring opcionalQué servicio lo corrió (
service.name). -
start_offset_msinteger opcionalInicio, en milisegundos desde el inicio de la traza.
-
duration_msinteger opcional -
statusstring opcionalrunningsolo en una traza parcial. Uno de:ok,error,running. -
attributesobject opcionalDetalles, con los nombres de OpenTelemetry:
http.response.status_code,db.system.name,error.type. Hasta 64, con valores de hasta 256 caracteres.
Listar trazas
/v1/traces MotorNube Las trazas que empezaron en el rango de tiempo, sin sus spans. Una traza está failed cuando alguno de sus spans tiene estado error, es decir, una llamada que no recibió respuesta, respondió 400, respondió 500 o más, o lanzó una excepción.
Parámetros de consulta
-
projectstring opcionalEl id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es
403. -
environmentstring opcionalEl entorno que se lee. Cualquier nombre que el proyecto haya enviado, o
all.Por defecto:
production -
sincestring opcionalSolo trazas que empezaron después de este momento.
Por defecto:
24h -
untilstring opcionalFin del rango de tiempo. Una fecha ISO 8601 o un valor relativo. Por defecto, ahora.
-
routestring, hasta 500 caracteres opcionalSolo trazas cuya raíz es esta ruta de la API (
/api/checkout,/api/orders/:id). -
methodstring opcionalSolo trazas cuya raíz tiene este método HTTP. Uno de:
GET,POST,PUT,PATCH,DELETE,HEAD,OPTIONS. -
failedboolean opcionaltruedevuelve solo las trazas fallidas,falsesolo las exitosas. -
min_duration_msinteger, mínimo 0 opcionalSolo trazas de al menos esta duración.
-
sessionstring opcionalSolo trazas de esta sesión.
-
servicestring, hasta 80 caracteres opcionalSolo trazas con un span de este servicio (
service.name). -
releasestring opcionalSolo trazas en esta versión.
-
sortstring opcionalrecent(las más recientes) oslowest(las más lentas).Por defecto:
recent -
limitinteger, 1 a 200 opcionalMáximo de elementos que se devuelven.
Por defecto:
50 -
cursorstring opcionalEl
next_cursorde la página anterior. Deja iguales todos los demás parámetros.
Petición
curl "https://api.sypnia.com/v1/traces?route=/api/checkout&failed=true" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Respuesta200
{
"data": [
{
"id": "7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c",
"started_at": "2026-03-12T10:31:43Z",
"duration_ms": 3870,
"name": "POST /api/checkout",
"method": "POST",
"route": "/api/checkout",
"status_code": 400,
"failed": true,
"partial": false,
"services": [
"browser",
"shop-api",
"payments"
],
"span_count": 4,
"dropped_spans": 0,
"session_id": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
"problem_id": "prb_8f3k2m9x4q7w",
"environment": "production",
"release": "4f2a91c"
}
],
"next_cursor": null
}Traer una traza
/v1/traces/{trace_id} MotorNube La traza con todos sus spans, ordenados por inicio. Los spans forman un árbol por medio de parent_id; la raíz tiene null. partial es true cuando la petición nunca terminó (la mató un tiempo de espera): los spans son los que se alcanzaron a reportar, y los que seguían corriendo tienen status: running.
Parámetros de ruta
-
trace_idstring obligatorioEl id de la traza, 32 caracteres hexadecimales.
Parámetros de consulta
-
projectstring opcionalEl id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es
403.
Petición
curl "https://api.sypnia.com/v1/traces/7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Respuesta200
{
"id": "7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c",
"started_at": "2026-03-12T10:31:43Z",
"duration_ms": 3870,
"name": "POST /api/checkout",
"method": "POST",
"route": "/api/checkout",
"status_code": 400,
"failed": true,
"partial": false,
"services": [
"browser",
"shop-api",
"payments"
],
"span_count": 4,
"dropped_spans": 0,
"session_id": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
"problem_id": "prb_8f3k2m9x4q7w",
"environment": "production",
"release": "4f2a91c",
"spans": [
{
"id": "0f1e2d3c4b5a6978",
"parent_id": null,
"name": "POST /api/checkout",
"kind": "browser",
"service": "browser",
"start_offset_ms": 0,
"duration_ms": 3870,
"status": "error",
"attributes": {
"http.request.method": "POST",
"http.response.status_code": 400,
"error.type": "amount_required"
}
},
{
"id": "a1b2c3d4e5f60718",
"parent_id": "0f1e2d3c4b5a6978",
"name": "POST /api/checkout",
"kind": "server",
"service": "shop-api",
"start_offset_ms": 14,
"duration_ms": 3842,
"status": "error",
"attributes": {
"http.route": "/api/checkout",
"http.response.status_code": 400
}
},
{
"id": "b2c3d4e5f6071829",
"parent_id": "a1b2c3d4e5f60718",
"name": "SELECT carts",
"kind": "db",
"service": "shop-api",
"start_offset_ms": 21,
"duration_ms": 12,
"status": "ok",
"attributes": {
"db.system.name": "postgresql",
"db.operation.name": "SELECT",
"db.collection.name": "carts"
}
},
{
"id": "c3d4e5f60718293a",
"parent_id": "a1b2c3d4e5f60718",
"name": "createPayment",
"kind": "http",
"service": "shop-api",
"start_offset_ms": 46,
"duration_ms": 3790,
"status": "error",
"attributes": {
"peer.service": "payments",
"server.address": "api.payments.example",
"http.request.method": "POST",
"http.response.status_code": 400,
"error.type": "amount_required"
}
}
]
}Errores
- 404
not_foundNinguna traza del proyecto tiene este id.
- 410
expiredLa traza es más vieja que la retención del proyecto.
Los errores que cualquier endpoint puede responder (401, 403, 429, 500, 503) están en Errores, límites, paginación.