OTLP
Send traces from any backend that speaks OpenTelemetry, with the standard OTLP/HTTP exporter.
Sypnia accepts traces in the OpenTelemetry protocol over HTTP (OTLP/HTTP). Use it for any backend that has no Sypnia SDK. Traces only: OTLP logs and metrics are not accepted (logs and custom metrics are planned).
Configure an exporter
Set the standard OpenTelemetry variables. The exporter adds /v1/traces to the endpoint by itself.
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=4f2a91cSelf-hosted: use <your base URL>/v1/otlp as the endpoint.
How spans become Sypnia data
| OpenTelemetry | Sypnia |
|---|---|
| Trace id | The trace id. A browser request that carried the SDK’s traceparent header joins the same trace |
Resource service.name | The span’s service |
Resource deployment.environment.name (or the older deployment.environment) | The environment. Default production |
Resource service.version | The release |
A server span (SPAN_KIND_SERVER) with http.route | One API call in Performance and the root of the trace |
A client span with db.system.name | A database call (kind: db) |
A client span with http.request.method | An outgoing HTTP call (kind: http) |
Span status ERROR, or an exception span event | A failure. An exception with a stack becomes a server-side problem |
Span attribute session.id (32 hex), or the x-sypnia-session request header read by your instrumentation | Links the trace to a session |
Span attributes are stored up to 64 per span, 256 characters per value. The engine drops attributes whose key
contains authorization, cookie, password, secret or token.
Export traces
/v1/otlp/v1/traces EngineCloud The OTLP/HTTP trace endpoint, as the OpenTelemetry specification defines it. The body is an
ExportTraceServiceRequest, in protobuf (application/x-protobuf) or JSON (application/json), optionally
with Content-Encoding: gzip. The answer is an ExportTraceServiceResponse in the same encoding.
When some spans are refused, the answer is still 200 and partialSuccess says how many and why, as the
protocol requires. An exporter must not retry a partial success.
Limits
- Body: 4,000,000 bytes after decompression.
- Spans per request: 2,000. Spans per trace that are kept: 500 (the rest are counted in the trace’s
dropped_spans).
Request
curl -X POST "https://ingest.sypnia.com/v1/otlp/v1/traces" \
-H "Authorization: Bearer spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e" \
-H "Content-Type: application/json" \
--data @spans.jsonRequest body
{
"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
}
}
]
}
]
}
]
}Response: Every span stored200
{}Response: Some spans refused200
{
"partialSuccess": {
"rejectedSpans": 2,
"errorMessage": "2 spans dropped: trace id is not 16 bytes"
}
}Errors
- 400
invalid_bodyThe body is not a valid
ExportTraceServiceRequest. - 401
unauthorizedThe ingest key is missing, unknown or revoked.
- 413
payload_too_largeThe body is larger than 4,000,000 bytes after decompression.
- 415
unsupported_media_typeThe content type is neither
application/x-protobufnorapplication/json. - 429
rate_limitedToo many requests. OTLP exporters honour
Retry-Afterby themselves. - 503
unavailableStorage is not reachable. OTLP exporters retry
503by themselves.
The errors every endpoint can answer (401, 403, 429, 500, 503) are on Errors, limits, pagination.