Troubleshooting

Most problems come down to one of a handful of settings. Work down this page.

Nothing shows up

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

OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

2. Are the endpoints exact? Per-signal endpoints are used as written, so include the signal at the end and nothing after it:

# Right
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://ws.latency.app/v1/telemetry/traces

# Wrong
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://ws.latency.app
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://ws.latency.app/v1/telemetry/traces/v1/traces

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

OTEL_EXPORTER_OTLP_TRACES_HEADERS=authorization=Bearer%20lit_your_traces_key

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 your language's page for how to load them first.

5. Is it 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:

Response	Cause	Fix
400 stream_type_mismatch	A key from the wrong kind of stream, like a traces key on the metrics endpoint	Use each signal's own key
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	Latency 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 if it's a burst. If it 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 (the Details button in Explore). Its 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 one.

My service is called 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 it sends the final batch. The zero-code agents for Node.js and Python, and Deno's built-in support, do this for you 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 your own logger
Everything else	See your 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/telemetry/traces \
  -H "Authorization: Bearer lit_your_traces_key" \
  -H "Content-Type: application/json" \
  -d '{"resourceSpans": []}'