Docs

OTLP

Envía trazas desde cualquier backend que hable OpenTelemetry, con el exportador estándar de OTLP/HTTP.

Aplica a MotorNube Al lanzar

Ver como Markdown
En esta página
  1. Configura un exportador
  2. Cómo se convierten los spans en datos de Sypnia
  3. Exportar trazas

Sypnia acepta trazas en el protocolo de OpenTelemetry por HTTP (OTLP/HTTP). Úsalo para cualquier backend que no tenga SDK de Sypnia. Solo trazas: los registros y las métricas de OTLP no se aceptan (los registros y las métricas propias están planeados).

Configura un exportador

Define las variables estándar de OpenTelemetry. El exportador le agrega /v1/traces al endpoint por su cuenta.

.env
OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.sypnia.com/v1/otlp
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_SERVICE_NAME=shop-api
OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=production,service.version=4f2a91c

En alojamiento propio, usa <tu URL base>/v1/otlp como endpoint.

Cómo se convierten los spans en datos de Sypnia

OpenTelemetrySypnia
El id de trazaEl id de la traza. Una petición del navegador que llevaba el encabezado traceparent del SDK entra en la misma traza
service.name del recursoEl service del span
deployment.environment.name del recurso (o el anterior deployment.environment)El entorno. Por defecto production
service.version del recursoLa versión (release)
Un span de servidor (SPAN_KIND_SERVER) con http.routeUna llamada a la API en Rendimiento y la raíz de la traza
Un span de cliente con db.system.nameUna llamada a la base de datos (kind: db)
Un span de cliente con http.request.methodUna llamada HTTP saliente (kind: http)
Estado ERROR del span, o un evento de span exceptionUna falla. Una excepción con pila se convierte en un problema del servidor
El atributo session.id del span (32 hex), o el encabezado x-sypnia-session de la petición leído por tu instrumentaciónUne la traza a una sesión

De cada span se guardan hasta 64 atributos, con valores de hasta 256 caracteres. El motor descarta los atributos cuya clave contiene authorization, cookie, password, secret o token.

Exportar trazas

POST /v1/otlp/v1/traces MotorNube

El endpoint de trazas de OTLP/HTTP, tal como lo define la especificación de OpenTelemetry. El cuerpo es un ExportTraceServiceRequest, en protobuf (application/x-protobuf) o en JSON (application/json), con Content-Encoding: gzip si quieres. La respuesta es un ExportTraceServiceResponse en la misma codificación.

Cuando se rechazan algunos spans, la respuesta igual es 200 y partialSuccess dice cuántos y por qué, como exige el protocolo. Un exportador no debe reintentar un éxito parcial.

Autenticación
Llave de ingesta

Límites

  • Cuerpo: 4.000.000 de bytes después de descomprimirlo.
  • Spans por petición: 2.000. Spans por traza que se guardan: 500 (el resto se cuenta en dropped_spans de la traza).

Petición

Terminal
curl -X POST "https://ingest.sypnia.com/v1/otlp/v1/traces" \
  -H "Authorization: Bearer spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e" \
  -H "Content-Type: application/json" \
  --data @spans.json

Cuerpo de la petición

JSON
{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [
          {
            "key": "service.name",
            "value": {
              "stringValue": "shop-api"
            }
          },
          {
            "key": "service.version",
            "value": {
              "stringValue": "4f2a91c"
            }
          },
          {
            "key": "deployment.environment.name",
            "value": {
              "stringValue": "production"
            }
          }
        ]
      },
      "scopeSpans": [
        {
          "spans": [
            {
              "traceId": "7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c",
              "spanId": "a1b2c3d4e5f60718",
              "parentSpanId": "0f1e2d3c4b5a6978",
              "name": "POST /api/checkout",
              "kind": 2,
              "startTimeUnixNano": "1773311503130000000",
              "endTimeUnixNano": "1773311506972000000",
              "attributes": [
                {
                  "key": "http.request.method",
                  "value": {
                    "stringValue": "POST"
                  }
                },
                {
                  "key": "http.route",
                  "value": {
                    "stringValue": "/api/checkout"
                  }
                },
                {
                  "key": "http.response.status_code",
                  "value": {
                    "intValue": "400"
                  }
                }
              ],
              "status": {
                "code": 2
              }
            }
          ]
        }
      ]
    }
  ]
}

Respuesta: Todos los spans guardados200

JSON
{}

Respuesta: Algunos spans rechazados200

JSON
{
  "partialSuccess": {
    "rejectedSpans": 2,
    "errorMessage": "2 spans dropped: trace id is not 16 bytes"
  }
}

Errores

  • 400invalid_body

    El cuerpo no es un ExportTraceServiceRequest válido.

  • 401unauthorized

    Falta la llave de ingesta, es desconocida o está revocada.

  • 413payload_too_large

    El cuerpo pesa más de 4.000.000 de bytes después de descomprimirlo.

  • 415unsupported_media_type

    El tipo de contenido no es application/x-protobuf ni application/json.

  • 429rate_limited

    Demasiadas peticiones. Los exportadores de OTLP respetan Retry-After por su cuenta.

  • 503unavailable

    No se puede llegar al almacenamiento. Los exportadores de OTLP reintentan un 503 por su cuenta.

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