Docs

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

Ver como Markdown
En esta página
  1. El objeto traza
  2. El objeto span
  3. Listar trazas
  4. Traer una traza

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

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

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

    El entorno que se lee. Cualquier nombre que el proyecto haya enviado, o all.

    Por defecto: production

  • since
    string opcional

    Solo trazas que empezaron después de este momento.

    Por defecto: 24h

  • 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

    recent (las más recientes) o slowest (las más lentas).

    Por defecto: recent

  • limit
    integer, 1 a 200 opcional

    Máximo de elementos que se devuelven.

    Por defecto: 50

  • cursor
    string opcional

    El next_cursor de la página anterior. Deja iguales todos los demás parámetros.

Petición

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

Respuesta200

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

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

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

Respuesta200

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

  • 404not_found

    Ninguna traza del proyecto tiene este id.

  • 410expired

    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.

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