Checklist: is my data flowing?

Use this checklist when spans don’t show up in Kubit Atlas, or show up without the detail you expect. Work through the checks in order. Each one rules out a cause before the next.

Check 1: the test span arrives

A test span takes your agent code out of the picture. From the folder that holds your Kubit bootstrap file, run:

Python

KUBIT_API_KEY=<your-key> python -c "
import kubit_instrumentation
from opentelemetry import trace
trace.get_tracer('kubit-sdk').start_span('hello-kubit').end()
import time; time.sleep(2)
"

Node

KUBIT_API_KEY=<your-key> node -r ts-node/register -e "
require('./kubit-instrumentation');
const { trace } = require('@opentelemetry/api');
trace.getTracer('kubit-sdk').startSpan('hello-kubit').end();
setTimeout(() => process.exit(0), 2000);
"

Then ask your assistant with the Kubit MCP server connected: “Show me traces from the last 15 minutes”.

Result	Next
`hello-kubit` is there	The key and network work. Go to Check 3.
Nothing	Go to Check 2.

Check 2: key and connection

Check	How	Fix
`KUBIT_API_KEY` is set in the process	`python -c "import os; print(bool(os.environ.get('KUBIT_API_KEY')))"` prints `True`	Export it, or load `.env` before the Kubit import
The key belongs to the workspace you’re looking at	Run `/kubit-connect` and compare the workspace name	Switch workspace, or mint a key in the right one
The SDK is installed in the running environment	`pip show kubit-otel` or `npm ls @kubit-ai/otel`	Install it in the app’s virtualenv or package
Outbound HTTPS is allowed		Allow the ingestion host in your egress rules

Check 3: your agent’s spans arrive

The test span arrived but your agent’s spans didn’t.

Cause	How to tell	Fix
Kubit is imported after the LLM client is created	The Kubit import isn’t the first line of the entrypoint	Move it to the first line
`configure()` replaced your provider, or `attach()` ran before it existed	Spans reach only one of your exporters	Use `attach()` after `trace.set_tracer_provider()`. See Send traces from Python.
No GenAI instrumentor	Only your own manual spans arrive	Add the instrumentor for your LLM client
Process exits before the batch flushes	Missing spans come from scripts, cron jobs or serverless functions	Call `force_flush()` on the tracer provider before exit
Next.js parents AI spans on an HTTP route span	Next.js app with the Vercel AI SDK	Wrap AI SDK calls in `context.with(ROOT_CONTEXT, () => …)`
OpenTelemetry JS SDK `^1.x`	`npm ls @opentelemetry/sdk-trace-base` shows `1.x`	Upgrade to `^2.0.0`

Check 4: spans arrive but detail is missing

Symptom	Cause	Fix
No sessions, or every trace is its own session	`session.id` not set	Set it on the root span. See Span attributes.
Traces don’t join to users	`user.id` not set, or set to a different ID than your product events	Use the same user ID in both
No Polaris labels on LLM spans	Message content not captured	`OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true`
Flows shows generic span names	Tool spans lack `gen_ai.tool.name`	Set it on every tool span
All agents look like one	Same `service.name` everywhere	Give each agent its own `service.name`

Still stuck

Send your workspace name, the output of Check 1 and the time you ran it to support.

Start here

Get started

Send traces

Bring your own warehouse

Checklist: is my data flowing?

Check 1: the test span arrives

Check 2: key and connection

Check 3: your agent’s spans arrive

Check 4: spans arrive but detail is missing

Still stuck

​Check 1: the test span arrives

​Check 2: key and connection

​Check 3: your agent’s spans arrive

​Check 4: spans arrive but detail is missing

​Still stuck

​Related

Check 1: the test span arrives

Check 2: key and connection

Check 3: your agent’s spans arrive

Check 4: spans arrive but detail is missing

Still stuck

Related