# Trazas

> Lista trazas y lee una con todos sus spans, de la petición del navegador a las llamadas a la base de datos.

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/api/traces/

Para agentes: Referencia de los endpoints de trazas de la API de Sypnia: listar trazas con filtros y traer una con todos sus spans (browser, server, db, http, internal).

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](https://docs.sypnia.com/es/api/errors-limits-pagination#retention)).

## El objeto traza

**Campos:**

- `id` (string, opcional): El id de traza W3C, 32 caracteres hexadecimales.
- `started_at` (timestamp, opcional)
- `duration_ms` (integer, opcional): Del inicio del primer span al fin del último.
- `name` (string, opcional): El nombre del span raíz, normalmente `MÉTODO ruta`.
- `method` (string o null, opcional)
- `route` (string o null, opcional): La ruta de la API, con los ids reemplazados.
- `status_code` (integer o null, opcional): El estado HTTP que respondió la raíz. `0` cuando el navegador no recibió respuesta.
- `failed` (boolean, opcional)
- `partial` (boolean, opcional): `true` cuando la petición nunca terminó.
- `services` (lista de string, opcional): Los servicios que corrieron spans, y los que ellos llamaron (`peer.service`). El navegador es `browser`.
- `span_count` (integer, opcional)
- `dropped_spans` (integer, opcional): Spans por encima de los 500 que se guardan por traza.
- `session_id` (string o null, opcional)
- `problem_id` (string o null, opcional): El problema del que esta traza es una ocurrencia.
- `environment` (string, opcional)
- `release` (string 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:**

- `id` (string, opcional): 16 caracteres hexadecimales.
- `parent_id` (string o null, opcional): El span que causó este. `null` en la raíz.
- `name` (string, opcional): Qué es el paso: `POST /api/checkout`, `SELECT carts`, `createPayment`.
- `kind` (string, opcional): `browser`: 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.
- `service` (string, opcional): Qué servicio lo corrió (`service.name`).
- `start_offset_ms` (integer, opcional): Inicio, en milisegundos desde el inicio de la traza.
- `duration_ms` (integer, opcional)
- `status` (string, opcional): `running` solo en una traza parcial. Uno de: `ok`, `error`, `running`.
- `attributes` (object, opcional): Detalles, con los nombres de OpenTelemetry: `http.response.status_code`, `db.system.name`, `error.type`. Hasta 64, con valores de hasta 256 caracteres.

## Listar trazas

`GET /v1/traces` \[Motor, Nube]

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.

**Autenticación:** Token de API (`read`)

**Parámetros de consulta:**

- `project` (string, opcional): El 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`.
- `environment` (string, opcional, por defecto `production`): El entorno que se lee. Cualquier nombre que el proyecto haya enviado, o `all`.
- `since` (string, opcional, por defecto `24h`): Solo trazas que empezaron después de este momento.
- `until` (string, opcional): Fin del rango de tiempo. Una fecha ISO 8601 o un valor relativo. Por defecto, ahora.
- `route` (string, hasta 500 caracteres, opcional): Solo trazas cuya raíz es esta ruta de la API (`/api/checkout`, `/api/orders/:id`).
- `method` (string, opcional): Solo trazas cuya raíz tiene este método HTTP. Uno de: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`.
- `failed` (boolean, opcional): `true` devuelve solo las trazas fallidas, `false` solo las exitosas.
- `min_duration_ms` (integer, mínimo 0, opcional): Solo trazas de al menos esta duración.
- `session` (string, opcional): Solo trazas de esta sesión.
- `service` (string, hasta 80 caracteres, opcional): Solo trazas con un span de este servicio (`service.name`).
- `release` (string, opcional): Solo trazas en esta versión.
- `sort` (string, opcional, por defecto `recent`): `recent` (las más recientes) o `slowest` (las más lentas).
- `limit` (integer, 1 a 200, opcional, por defecto `50`): Máximo de elementos que se devuelven.
- `cursor` (string, opcional): El `next_cursor` de la página anterior. Deja iguales todos los demás parámetros.

**Petición:**

```bash
curl "https://api.sypnia.com/v1/traces?route=/api/checkout&failed=true" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Respuesta (200):**

```json
{
  "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

`GET /v1/traces/{trace_id}` \[Motor, Nube]

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

**Autenticación:** Token de API (`read`)

**Parámetros de ruta:**

- `trace_id` (string, obligatorio): El id de la traza, 32 caracteres hexadecimales.

**Parámetros de consulta:**

- `project` (string, opcional): El 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:**

```bash
curl "https://api.sypnia.com/v1/traces/7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Respuesta (200):**

```json
{
  "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_found`: Ninguna traza del proyecto tiene este id.
- `410` `expired`: La 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](https://docs.sypnia.com/es/api/errors-limits-pagination).
