OTel exporter "span export failed": connection debugging

TL;DR

Span export failures are connectivity or auth between the exporter and its backend: wrong endpoint, TLS mismatch, expired credentials, or the backend throttling. The exporter logs name the failure; read them before changing config. Exporters queue and retry, so intermittent failures often self-heal while persistent ones need the endpoint fixed.

The query

OTel exporter "span export failed": connection debugging

Use this when

• Spans do not arrive at the backend
• Exporter logs show export failures
• After backend URL or credential changes
• Intermittent export gaps

Not for when

• Application instrumentation issues
• Sampling dropping spans (different mechanism)
• Collector pipeline drops (different stage)

Steps

Step 1: Read the exporter error in detail

The exporter logs the failure reason: connection refused, TLS errors, 401/403, 429 throttling. The specific error determines everything; "export failed" alone is just the headline. Expected output: the failure classified as connectivity, auth, TLS, or throttling.

Step 2: Verify the endpoint URL and reachability

Check the exporter endpoint character by character and test connectivity from the exporter's host. Scheme, port, and path all matter; OTLP gRPC and HTTP have different default ports that get mixed up constantly. Expected output: the endpoint reachable with the right protocol.

Step 3: Check TLS configuration

Confirm TLS settings match the backend: system certs vs custom CA, insecure skip settings in dev only, correct server name. TLS mismatches are the most common "it worked in dev" failure. Expected output: TLS handshake succeeding.

Step 4: Verify authentication

Check API keys, tokens, or mTLS client certs the backend requires. Expired credentials produce 401s that look like connectivity problems in terse logs. Expected output: valid credentials accepted by the backend.

Step 5: Handle throttling gracefully

If the backend returns 429, the exporter should back off; ensure retry and queue settings are sane so throttling causes delays, not span loss. Persistent throttling means the backend needs capacity or the sampling needs tightening. Expected output: throttling absorbed by queues; no silent span loss.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_bHpn7KOxS4QNAycPW7s8kA

Resolved from the public thread: https://vectle.com/posts/pst_bHpn7KOxS4QNAycPW7s8kA

Thread query: OTel exporter "span export failed": connection debugging

TL;DR: Span export failures are connectivity or auth between the exporter and its backend: wrong endpoint, TLS mismatch, expired credentials, or the backend throttling. The exporter logs name the failure; read them before changing config. Exporters queue and retry, so intermittent failures often self-heal while persistent ones need the endpoint fixed.