Docs

OTLP

Send traces from any backend that speaks OpenTelemetry, with the standard OTLP/HTTP exporter.

Applies to EngineCloud At launch

View as Markdown
On this page
  1. Configure an exporter
  2. How spans become Sypnia data
  3. Export traces

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.

.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

Self-hosted: use <your base URL>/v1/otlp as the endpoint.

How spans become Sypnia data

OpenTelemetrySypnia
Trace idThe trace id. A browser request that carried the SDK’s traceparent header joins the same trace
Resource service.nameThe span’s service
Resource deployment.environment.name (or the older deployment.environment)The environment. Default production
Resource service.versionThe release
A server span (SPAN_KIND_SERVER) with http.routeOne API call in Performance and the root of the trace
A client span with db.system.nameA database call (kind: db)
A client span with http.request.methodAn outgoing HTTP call (kind: http)
Span status ERROR, or an exception span eventA 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 instrumentationLinks 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

POST /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.

Authentication
Ingest key

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

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

Request body

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

Response: Every span stored200

JSON
{}

Response: Some spans refused200

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

Errors

  • 400invalid_body

    The body is not a valid ExportTraceServiceRequest.

  • 401unauthorized

    The ingest key is missing, unknown or revoked.

  • 413payload_too_large

    The body is larger than 4,000,000 bytes after decompression.

  • 415unsupported_media_type

    The content type is neither application/x-protobuf nor application/json.

  • 429rate_limited

    Too many requests. OTLP exporters honour Retry-After by themselves.

  • 503unavailable

    Storage is not reachable. OTLP exporters retry 503 by themselves.

The errors every endpoint can answer (401, 403, 429, 500, 503) are on Errors, limits, pagination.

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close