Quickstart: first traces in Atlas

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 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:

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

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.
Kubit app

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:

export KUBIT_API_KEY=<your-key>

Install the SDK

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.

Add the bootstrap file

Create kubit_instrumentation.py next to your entrypoint:

kubit_instrumentation.py

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.

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.

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:

main.py

import kubit_instrumentation  # must be the first import

# your existing imports and code follow

Send a test span

From the folder that holds kubit_instrumentation.py, run:

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.

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:

pip install opentelemetry-instrumentation-openai-v2

kubit_instrumentation.py

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:

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:

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

Next steps

Send traces from Python: existing providers, frameworks and production settings.
Span attributes: add user and session IDs so Atlas can group traces.
Concepts: what Polaris does with the spans you just sent.

Start here

Get started

Send traces

Bring your own warehouse

Quickstart: first traces in Atlas

Before you start

Prompt for your coding agent

Steps

Verify

If it fails

Next steps

​Before you start

​Prompt for your coding agent

​Steps

​Verify

​If it fails

​Next steps

Before you start

Prompt for your coding agent

Steps

Verify

If it fails

Next steps