> ## 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.

# Quickstart: first traces in Atlas

> Send OpenTelemetry spans from a Python agent to Kubit Atlas with kubit-otel and see them in about 10 minutes.

This quickstart sends spans from a Python app to Kubit Atlas. At the end you'll have a test span in your workspace and your agent's LLM calls traced. It takes about 10 minutes.

For Node, Langfuse or Braintrust, use [Set up with your coding agent](https://learn.kubit.ai/coding-agent-setup.md) instead. It detects your setup and picks the right path.

## Before you start

* [ ] Python 3.9 or later 
* [ ] A Kubit workspace and its ingestion API key (see below)
* [ ] An agent that calls an LLM, or any Python script to test with

## Prompt for your coding agent

Paste this into Claude Code, Cursor or Codex in your repo:

```text theme={null}
Add Kubit tracing to this Python repo. Follow https://learn.kubit.ai/quickstart.md exactly.
Read KUBIT_API_KEY from .env. Show me the diff before writing any file.
```

## Steps

**1. Get an API key**

Kubit authenticates spans with an ingestion API key, read from the `KUBIT_API_KEY` environment variable. Each key belongs to one workspace.

| Way to get a key | How |
| - | - |
| **Coding agent** | Run `/kubit-integrate` in Claude Code. It creates or selects a workspace, mints a key and writes `KUBIT_API_KEY` to `.env.local` or `.env`. See [Set up with your coding agent](https://learn.kubit.ai/coding-agent-setup.md). |
| **Kubit app** | |

> [!WARNING]
>
> Keep the key out of source control. Put it in `.env` or your secrets manager, and check that `.env` is in `.gitignore`.

Then set it in your shell for the next steps:

```bash theme={null}
export KUBIT_API_KEY=<your-key>
```

**2. Install the SDK**

```bash theme={null}
pip install kubit-otel
```

If your app reads `.env` with `python-dotenv`, keep using it. Kubit reads `KUBIT_API_KEY` from the environment either way.

**3. Add the bootstrap file**

Create `kubit_instrumentation.py` next to your entrypoint:

```python kubit_instrumentation.py theme={null}
import os
from kubit_otel import configure

configure(
    api_key=os.environ["KUBIT_API_KEY"],
    service_name="support-agent",
    service_version="1.0.0",
    resource_attributes={"deployment.environment": "dev"},
)
```

Change `service_name`, `service_version` and `deployment.environment` to match your app. Atlas uses them to tell agents and releases apart.

> [!WARNING]
>
> If your app already creates an OpenTelemetry `TracerProvider`, don't call `configure()`. Call `attach()` after the provider is set instead. See [Send traces from Python](https://learn.kubit.ai/send-traces/python.md#you-already-have-a-tracerprovider).

**4. Import it first in your entrypoint**

Make it the first import in `main.py`, `app.py` or whichever file starts your app, so the provider exists before any LLM client is created:

```python main.py theme={null}
import kubit_instrumentation  # must be the first import

# your existing imports and code follow
```

**5. Send a test span**

From the folder that holds `kubit_instrumentation.py`, run:

```bash 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)
"
```

The two-second sleep gives the exporter time to send the span before the process exits.

**6. Trace your LLM calls**

The test span proves the connection. To trace real agent work, add an OpenTelemetry GenAI instrumentor for your LLM client. For the OpenAI Python SDK:

```bash theme={null}
pip install opentelemetry-instrumentation-openai-v2
```

```python kubit_instrumentation.py theme={null}
import os
from kubit_otel import configure
from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

configure(
    api_key=os.environ["KUBIT_API_KEY"],
    service_name="support-agent",
    service_version="1.0.0",
    resource_attributes={"deployment.environment": "dev"},
)
OpenAIInstrumentor().instrument()
```

Then set this env var so spans carry the prompt and response text that Polaris labels:

```bash theme={null}
export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
```

## Verify

Check that the `hello-kubit` span arrived. With the Kubit MCP server connected in Claude Code or Cursor, ask:

> "Show me traces from the last 15 minutes"

The result lists a trace whose root span is named `hello-kubit`, from service `support-agent`.

In the Kubit app:&#x20;

## If it fails

| Symptom | Cause | Fix |
| - | - | - |
| `KeyError: 'KUBIT_API_KEY'` | The env var isn't set in the shell that runs Python | `export KUBIT_API_KEY=<your-key>`, or load `.env` before the import |
| `ModuleNotFoundError: No module named 'kubit_otel'` | The SDK went into a different virtualenv | Activate the app's virtualenv and run `pip install kubit-otel` again |
| Test span runs with no error but never shows up | The process exited before the exporter flushed | Keep the `time.sleep(2)`, or call `trace.get_tracer_provider().force_flush()` before exit |
| Test span shows up but LLM calls don't | `kubit_instrumentation` is imported after the LLM client is created | Move `import kubit_instrumentation` to the first line of the entrypoint |

More checks are in [Is my data flowing?](https://learn.kubit.ai/data-flowing-checklist.md).

## Next steps

* [Send traces from Python](https://learn.kubit.ai/send-traces/python.md): existing providers, frameworks and production settings.
* [Span attributes](https://learn.kubit.ai/send-traces/span-attributes.md): add user and session IDs so Atlas can group traces.
* [Concepts](https://learn.kubit.ai/concepts.md): what Polaris does with the spans you just sent.


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