Troubleshooting

Most problems come down to a handful of settings, listed in order below.

Nothing shows up

1. Is the protocol HTTP? Our ingest doesn't accept gRPC, and Python defaults to gRPC:

OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

2. Is the endpoint the base? The SDK adds /v1/traces, /v1/metrics and /v1/logs to OTEL_EXPORTER_OTLP_ENDPOINT itself:

# Right
OTEL_EXPORTER_OTLP_ENDPOINT=https://ws.latency.app/v1/ingest

# Wrong
OTEL_EXPORTER_OTLP_ENDPOINT=https://ws.latency.app
OTEL_EXPORTER_OTLP_ENDPOINT=https://ws.latency.app/v1/ingest/v1/traces

The per-signal variables, like OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, are used exactly as written, so they need the full path: https://ws.latency.app/v1/ingest/v1/traces.

3. Is the header encoded? The space after Bearer is written %20:

OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer%20lit_XXXXXXXXXXX

4. Did the app see the variables? Settings in a .env file are often read after OpenTelemetry starts. Set them in the real environment, or see the language page for loading them first.

5. Is the missing data a metric? Metrics are exported every 60 seconds by default. Wait a minute, or set OTEL_METRIC_EXPORT_INTERVAL=10000.

Error responses

Turn on the SDK's debug logging (below) to see the response, then match it here:

Response	Cause	Fix
400 stream_type_mismatch	A key from an Events Stream	Use a key from an OpenTelemetry Stream
401	Key is wrong, disabled or revoked, or its Stream is deleted	Check the key in Manage Streams
413	Batch over 4 MB	Lower the batch size, like OTEL_BSP_MAX_EXPORT_BATCH_SIZE=256 for traces
404, or gRPC errors like UNIMPLEMENTED	Sent over gRPC	Set OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
415	Unsupported content type or compression	Use http/protobuf or http/json, uncompressed or with gzip, deflate, br or zstd
403 plan_required	The account's plan doesn't include telemetry	Upgrade the plan
403 ingest_blocked	We blocked the key or Stream; the body says why	Contact feedback@latency.app
429 rate_limited	Over a rate limit; X-Latency-Limit names it	Nothing for a burst. If the limit persists, batch more or raise the key's limit
429 quota_exceeded	The account is at 110% of its monthly events	Upgrade, or wait for next month
429 or 503, other	Busy or briefly unavailable	Nothing: SDKs retry on their own

Data arrives but some is missing

Open the Stream's Overview (select the Stream in Manage Streams). Ingest Health lists anything that was rejected, dropped or throttled in the last 7 days, with the reason and an example. The limits page explains each reason.

Service shows as unknown_service

Set a name:

OTEL_SERVICE_NAME=checkout-api

The last few seconds of data go missing

SDKs send in batches, so data from just before the process exits can be lost. Shut the SDK down on exit so the final batch goes out. The zero-code agents for Node.js and Python, and Deno's built-in support, handle this on a normal shutdown.

For serverless functions, flush before each invocation returns (for example forceFlush() on the tracer and meter providers), because the process may be frozen between invocations.

Turn on debug logging

Language	Setting
Node.js	OTEL_LOG_LEVEL=debug
Deno	OTEL_EXPORTER_OTLP_PROTOCOL=console prints everything instead of sending it
Go	otel.SetErrorHandler(...) with a custom logger
Everything else	See the SDK's docs, or send to a local Collector with the debug exporter

Still stuck?

Try the same key with curl. If this returns 200, the key and network are fine and the problem is in the SDK's configuration:

curl -i https://ws.latency.app/v1/ingest/v1/traces \
  -H "Authorization: Bearer lit_XXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"resourceSpans": []}'