Docs

OpenTelemetry

Point an existing OTLP/HTTP trace exporter at Sypnia, with examples for Python, Go, PHP, Rust, Java and the Collector, what each span becomes, and exactly what is ignored at launch.

Applies to EngineCloud At launch

View as Markdown
On this page
  1. The settings, for every language
  2. By language
  3. Check that it works
  4. Joining the browser’s trace and session
  5. What a span becomes
  6. What Sypnia does not use, at launch
  7. What you do not get this way
  8. Next

This page is for whoever runs a backend that is not Node: Python, Go, PHP, Rust, Java, or anything else with an OpenTelemetry SDK. Sypnia accepts traces in the OpenTelemetry protocol over HTTP (OTLP/HTTP), on the open-source engine and on Sypnia Cloud alike. Sypnia’s own SDKs for these languages are Planned; OpenTelemetry is today’s answer and stays supported after they exist.

At the end you will have: your backend’s requests in Sypnia’s traces and performance numbers, its exceptions as problems, and its spans joined to the browser’s trace when the request came from a page that runs the browser SDK.

The settings, for every language

You change no code that already works. Set the standard OpenTelemetry environment variables:

Sypnia Cloud

.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_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=none
OTEL_LOGS_EXPORTER=none
OTEL_SERVICE_NAME=shop-api
OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=production,service.version=4f2a91c
VariableWhat to putWhy
OTEL_EXPORTER_OTLP_ENDPOINTYour ingest address followed by /v1/otlp.The exporter adds /v1/traces by itself, so spans go to …/v1/otlp/v1/traces.
OTEL_EXPORTER_OTLP_HEADERSAuthorization=Bearer and your ingest key.The key says which project the spans belong to. It is public and can only send.
OTEL_EXPORTER_OTLP_PROTOCOLhttp/protobuf, or http/json.Sypnia does not accept gRPC.
OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTERnoneSypnia takes traces only. Without this, the exporter keeps trying to send metrics and logs and logs a 404 each time.
OTEL_SERVICE_NAMEA name for this service.It is the name you see on its spans.
OTEL_RESOURCE_ATTRIBUTESdeployment.environment.name and service.version.The environment (default production) and the release. Use the same values as your frontend.

Use the same project as your frontend: a trace connects parts of one project.

By language

Each example assumes the variables above are set. Package and command names are the OpenTelemetry project’s own; check its documentation for your version.

Python

Terminal
pip install opentelemetry-distro opentelemetry-exporter-otlp-proto-http
opentelemetry-bootstrap -a install
opentelemetry-instrument python app.py

Python reads the header variable strictly: write the space as %20.

.env
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e

Check that it works

  1. Start your service and call one of its routes.
  2. Within 10 minutes the route is listed in Performance with one request, and its trace is in Traces.

To test the address and the key without your app:

Terminal
curl -i -X POST "https://ingest.sypnia.com/v1/otlp/v1/traces" \
  -H "Authorization: Bearer spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e" \
  -H "Content-Type: application/json" \
  -d '{"resourceSpans":[]}'
You should see
HTTP/2 200 and the body {}. A 401 means the key is wrong; a 404 means the path is wrong.

Joining the browser’s trace and session

The trace joins by itself. The browser SDK sends the W3C traceparent header with each call to your API, and OpenTelemetry SDKs read it by default. Your server’s spans then carry the browser’s trace id. If the API is on another origin than the page, list it in the browser SDK’s traceTargets and allow the header in CORS: see Browser.

The session needs one attribute. The browser SDK also sends the session’s id in the header x-sypnia-session. Copy it to the span attribute session.id on the server span, and the request appears in that session’s timeline:

app.py
from flask import Flask, request
from opentelemetry import trace

app = Flask(__name__)

@app.before_request
def link_sypnia_session():
    session_id = request.headers.get("x-sypnia-session")
    if session_id:
        trace.get_current_span().set_attribute("session.id", session_id)

Without it the trace is still joined to the browser’s call, and through that call to the session; the attribute matters for requests whose browser event was lost.

What a span becomes

In OpenTelemetryIn Sypnia
Trace idThe trace’s id.
Resource service.nameThe span’s service.
Resource deployment.environment.name, or the older deployment.environmentThe environment. production when missing.
Resource service.versionThe release.
A span of kind SERVER with http.routeOne request in Performance, and the root of that service’s part of the trace.
A span of kind CLIENT with db.system.nameA database call.
A span of kind CLIENT with http.request.methodA call to another service.
Any other spanAn internal step, shown in the trace.
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 characters)Links the trace to a session.

What Sypnia does not use, at launch

Sent by OpenTelemetryWhat happens
Metrics and logs (/v1/metrics, /v1/logs)Not accepted: 404. Logs and custom metrics are Planned.
gRPC transportNot accepted. Use http/protobuf or http/json.
Span events other than exceptionDropped.
Span linksDropped.
tracestate and baggageNot read and not stored.
Attributes whose name contains authorization, cookie, password, secret or tokenDropped at ingest.
More than 64 attributes on a span, or a value longer than 256 charactersThe extra attributes are dropped; long values are cut.
More than 500 spans in one traceThe first 500 are kept; the rest are counted.
The sampling decision in traceparentNot used: Sypnia stores what you send. Sample in your SDK or Collector if you send too much.
The names and e-mails of peopleOpenTelemetry carries none that Sypnia reads. A trace gets its person from its session. See Identifying people.

Limits of one request are in the API reference: a body of 4,000,000 bytes after decompression and 2,000 spans. The standard batch exporters stay well under both.

What you do not get this way

OpenTelemetry sends traces. Sessions, replays, clicks and page performance come from the browser SDK, which works with any backend. On Sypnia Cloud, a trace counts as one event, however many spans it has.

Next

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