> ## Documentation Index
> Fetch the complete documentation index at: https://learn.kubit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Checklist: is my data flowing?

> Step-by-step checks when traces don't appear in Kubit Atlas: API key, SDK install, provider order, flushing, span filters and identity attributes.

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:

```bash Python theme={null}
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)
"
```

```bash Node theme={null}
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](https://learn.kubit.ai/send-traces/python.md#choose-configure-or-attach). |
| 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](https://learn.kubit.ai/send-traces/span-attributes.md#identity-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.&#x20;

## Related

* [Quickstart](https://learn.kubit.ai/quickstart.md)
* [Set up with your coding agent](https://learn.kubit.ai/coding-agent-setup.md)
* [Span attributes](https://learn.kubit.ai/send-traces/span-attributes.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.