Skip to content
Overview

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 backendExport to BTX
Node.jsInstall the published @btx-second-context/otel package.
PythonUse the official OTel HTTP exporter.
Other languages or a CollectorUse 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

SettingValue
Endpointhttps://btx.so/api/otel/v1/traces
MethodPOST
AuthorizationAuthorization: Bearer YOUR_BTX_API_KEY
ProtocolOTLP over HTTP, Protobuf or JSON
CompressionNone 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

ResultWhat to check
401The project API key is missing, invalid, or revoked.
413Reduce the export batch size or captured content.
415Use OTLP HTTP Protobuf or JSON, with no compression or gzip.
429Reduce export frequency and let the exporter honor Retry-After within its retry deadline.
503A temporary service failure occurred. Exporter retries remain bounded by its timeout.
Partial successSome spans were rejected. Inspect exporter diagnostics; do not replay the whole batch. Accepted spans have already been stored.
No traceCheck 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 childCheck each destination's filters and whether the spans use the same provider and propagated context.