Send backend traces to BTX
Export traces from your existing OpenTelemetry setup.
Connect your backend
BTX accepts traces from your existing OpenTelemetry (OTel) setup. Add an export destination and keep your instrumentation, sampling, and other exporters.
Choose a setup path:
| Your backend | Export to BTX |
|---|---|
| Node.js | Install the published @btx-second-context/otel package. |
| Python | Use the official OTel HTTP exporter. |
| Other languages or a Collector | Use the OTLP connection settings. No BTX package is required. |
The BTX Node.js package handles export: batching, authentication, bounded delivery, and diagnostics. It does not create traces or instrument your application. If you have no instrumentation yet, start with the OpenTelemetry language guides.
Create an API key
In the BTX desktop app, select your project and open Settings > Project > API keys. Create a key and store it in your backend's secret manager as BTX_API_KEY. This is a server credential; keep it out of browser and mobile apps.
Your API key determines the project that receives the traces. Span attributes cannot change that project.
Keep your existing pipeline
Register BTX alongside your other processors on the provider your instrumentation already uses. Each processor sends its own copy to its destination. BTX preserves trace IDs, span IDs, and parent relationships, so an existing trace with multiple child spans keeps the same structure.
With Langfuse, keep its processor registered and add BTX once. Do not create a second global provider or redirect shared OTEL_EXPORTER_OTLP_* settings used by another exporter. An isolated Langfuse provider must also receive the BTX processor if you want its spans in BTX.
Filtering and masking are destination-specific. A policy configured in Langfuse does not automatically apply to BTX. Removing a parent span can leave its children without a visible parent; filtering does not reparent them.
Connection reference
| Setting | Value |
|---|---|
| Endpoint | https://btx.so/api/otel/v1/traces |
| Method | POST |
| Authorization | Authorization: Bearer YOUR_BTX_API_KEY |
| Protocol | OTLP over HTTP, Protobuf or JSON |
| Compression | None or gzip |
Use the full traces endpoint when configuring an exporter. A gRPC exporter cannot send directly to this HTTP endpoint.
You can also export from other languages or an OpenTelemetry Collector using this connection information.
Find your first trace
Run an existing instrumented request or job, let its spans finish, and flush your provider. In BTX, open your project's Telemetry > Traces and select the trace. Check the root name, child spans, timing, and status.
BTX preserves the received trace and span IDs. Add a trace ID to a feedback report when you need to reference a specific execution; exporting a trace does not automatically identify a customer.
Delivery and data
Exporters buffer work in memory. Flush before a short-lived runtime pauses, and shut down the provider when your application exits. A process crash or a full queue can lose spans. Host sampling determines which spans reach the exporter.
BTX stores accepted span metadata, attributes, events, links, and resource information. Review what your instrumentation captures before enabling export. Exclude credentials, customer text, and request bodies that you do not intend to store.
The receiver accepts up to 4 MiB per HTTP request, 16 MiB after decompression, and 4,096 spans per request. A stored span must fit the 128 KiB projected JSON limit. Oversized or invalid spans can be rejected while the rest of the batch is accepted. Accepted content is not silently truncated.
Troubleshooting
| Result | What to check |
|---|---|
401 | The project API key is missing, invalid, or revoked. |
413 | Reduce the export batch size or captured content. |
415 | Use OTLP HTTP Protobuf or JSON, with no compression or gzip. |
429 | Reduce export frequency and let the exporter honor Retry-After within its retry deadline. |
503 | A temporary service failure occurred. Exporter retries remain bounded by its timeout. |
| Partial success | Some spans were rejected. Inspect exporter diagnostics; do not replay the whole batch. Accepted spans have already been stored. |
| No trace | Check that BTX uses the instrumented provider, sampling includes the request, spans have ended, and export diagnostics show no failure. Flush before the runtime pauses. |
| Missing parent or child | Check each destination's filters and whether the spans use the same provider and propagated context. |