OTLP
Envía trazas desde cualquier backend que hable OpenTelemetry, con el exportador estándar de OTLP/HTTP.
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.
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=4f2a91cEn alojamiento propio, usa <tu URL base>/v1/otlp como endpoint.
Cómo se convierten los spans en datos de Sypnia
| OpenTelemetry | Sypnia |
|---|---|
| El id de traza | El id de la traza. Una petición del navegador que llevaba el encabezado traceparent del SDK entra en la misma traza |
service.name del recurso | El service del span |
deployment.environment.name del recurso (o el anterior deployment.environment) | El entorno. Por defecto production |
service.version del recurso | La versión (release) |
Un span de servidor (SPAN_KIND_SERVER) con http.route | Una llamada a la API en Rendimiento y la raíz de la traza |
Un span de cliente con db.system.name | Una llamada a la base de datos (kind: db) |
Un span de cliente con http.request.method | Una llamada HTTP saliente (kind: http) |
Estado ERROR del span, o un evento de span exception | Una 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ón | Une 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
/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.
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_spansde la traza).
Petición
curl -X POST "https://ingest.sypnia.com/v1/otlp/v1/traces" \
-H "Authorization: Bearer spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e" \
-H "Content-Type: application/json" \
--data @spans.jsonCuerpo de la petición
{
"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
{}Respuesta: Algunos spans rechazados200
{
"partialSuccess": {
"rejectedSpans": 2,
"errorMessage": "2 spans dropped: trace id is not 16 bytes"
}
}Errores
- 400
invalid_bodyEl cuerpo no es un
ExportTraceServiceRequestválido. - 401
unauthorizedFalta la llave de ingesta, es desconocida o está revocada.
- 413
payload_too_largeEl cuerpo pesa más de 4.000.000 de bytes después de descomprimirlo.
- 415
unsupported_media_typeEl tipo de contenido no es
application/x-protobufniapplication/json. - 429
rate_limitedDemasiadas peticiones. Los exportadores de OTLP respetan
Retry-Afterpor su cuenta. - 503
unavailableNo se puede llegar al almacenamiento. Los exportadores de OTLP reintentan un
503por su cuenta.
Los errores que cualquier endpoint puede responder (401, 403, 429, 500, 503) están en Errores, límites, paginación.