Troubleshooting

No data shows up

• Check the project's Send data page: the key's Last used updates when it's accepted.
• Look at the ingest request in your browser's network tab or your exporter's logs. A 401 means a wrong or revoked key; a 403 means the request came from a domain or IP the key doesn't allow (the response names what it saw, so you can add it on the Send data page); a 415 means the exporter isn't sending JSON.
• Browser spans are sent about 2 seconds after they happen, and when the tab is hidden. Wait a moment, then refresh.
• The dashboard defaults to the last hour. Test spans with old timestamps fall outside it.
• A Worker needs the nodejs_compat flag, and its handler must be the one wrapped by instrument() and exported as default.

History stays empty

Recent ranges work but 7d and 30d show nothing, or the row count in Verify stays at 0.

• A new pipeline takes a few minutes to write its first file. Wait five minutes before digging.
• bunx wrangler pipelines get knotel_spans_pipeline should say running and list the stream the Worker is bound to. Compare its id with SPANS_STREAM in your deploy target, and check the last deploy was made with KNOTEL_TARGET set.
• The stream rejects records that don't match its schema. If pipelines/spans.schema.json changed since the stream was created, the stream is stale: see Changing the span schema. The Worker logs span stream send failed when this happens (bunx wrangler tail knotel --search "stream").
• The sink's catalog token expired or was deleted. Recreate the sink with a new token (step 3 of the schema change, then the pipeline).

Long ranges fail with an error

• Unauthenticated. from R2 SQL: the R2_SQL_TOKEN secret is wrong or expired. Create a new token and replace the secret with bunx wrangler secrets-store secret update STORE_ID --secret-id … --remote.
• No field named … or a schema error: the Worker is newer than the table. Follow Changing the span schema.
• More than one account available from wrangler: set CLOUDFLARE_ACCOUNT_ID.

Long ranges take seconds

Ranges beyond the hot window are answered by R2 SQL, which takes 1 to 5 seconds per query. Results are cached in KV for a few minutes, so the second viewer doesn't wait. Increase HOT_WINDOW_DAYS to keep more ranges instant.

Browser and backend traces aren't linked

• The backend's host must be your page's origin or be listed in data-propagate.
• Cross-origin APIs must allow the traceparent header in CORS. If they don't, the browser blocks the request itself, so check the console.
• The backend must read traceparent. The Worker SDK and OpenTelemetry SDKs do.

A Python service traces nothing

Look for 415 in the service's own log. The Python SDK ships only a protobuf exporter and ingest accepts protobuf, so a 415 means the instance predates that support and needs redeploying. A rejected batch is dropped and the service carries on, which is why tracing can look healthy while nothing is stored. See OpenTelemetry.

Worker spans show 0 ms

Workers only advance the clock during I/O, so CPU-only work has no measurable duration. Spans around fetches, database calls and other I/O are accurate.

Numbers lag behind

Ranges of 6 hours and longer are cached for up to a minute (6h, 24h) or 5 minutes (7d, 30d). Switch to 1 hour for live numbers. Spans reach the long-term store about a minute after they arrive, but the hot cache answers recent ranges immediately, so you rarely see that delay.

A revoked key still works

Worker instances that recently saw it can accept it for up to a minute after revoking.

Limits

FAQ

Does it do logs or metrics? Traces only, for now. Many questions metrics answer (request rates, error rates, percentiles) come from traces.

Does it sample? No. Every span sent is stored. Sample in your SDK or Collector if you need to.

Can several environments share an instance? Yes. Use a project per environment, or one project with a deployment.environment.name resource attribute to filter on.