Before you start
- A Kubit Agent workspace and its API key in
KUBIT_API_KEY - For Python: Python 3.9 or later
- For Node: Node.js 18 or later and OpenTelemetry JS SDK v2
KUBIT_API_KEY environment variable. Each key belongs to one workspace.
The app shows a new key only once:
This is the only time we'll show you this key. Copy it now. Copy it, or click Download for a .env file, then click I’ve Saved It. The downloaded file names the key KUBIT_OTEL_API_KEY, so rename it to KUBIT_API_KEY.
Availability: API Keys shows only to the Owner and Admin roles, and only in Agent and User workspaces.
Prompt for your coding agent
Steps for Python
Point the exporter at Kubit
Every exporter that sends to Kubit uses these settings:If your app already registers a TracerProvider, add a second Pass the endpoint and header in code, as above. The
Set
service.name, service.version and deployment.environment on the resource. Kubit maps service.version to Client: Version and deployment.environment to Client: Environment.Create kubit_tracing.py and import it first in your entrypoint, before any LLM client is created:kubit_tracing.py
main.py
BatchSpanProcessor with the Kubit exporter to it instead, after your app calls trace.set_tracer_provider(). Don’t create a second provider. OpenTelemetry keeps the first global provider and ignores the second.tracing.py
OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT and OTEL_EXPORTER_OTLP_HEADERS environment variables apply to every OpenTelemetry exporter in the process. If another backend shares the process, setting them for Kubit sends that backend’s spans to Kubit too.Trace LLM calls
Add the OpenTelemetry GenAI instrumentor for your LLM client, and turn on message content so Polaris has text to label:Add these lines at the end of
kubit_tracing.py, after trace.set_tracer_provider(provider):kubit_tracing.py
Add user and session IDs
Set
user.id and session.id on the root span of each request, so Kubit can group traces into sessions and join them to users:handler.py
Steps for Node
Install the SDK and exporter
Install the OpenTelemetry JS SDK v2 packages and the OTLP/HTTP protobuf exporter:
Point the exporter at Kubit
Use the settings in Point the exporter at Kubit. Create If your app already creates a tracer provider or
kubit-tracing.ts and import it first in your entrypoint, before any LLM client is created:kubit-tracing.ts
index.ts
NodeSDK, add the Kubit processor to its spanProcessors list instead. OpenTelemetry JS SDK v2 takes span processors only when the provider is created.instrumentation.ts
Verify
Open Agent > Activity in the Kubit app, set Time Range to Last 1 day and click Execute. Thechat.completion trace from your test span is in the list. Validate in Activity shows what to check in the trace.
Check the Connection with curl
If the test span doesn’t show, send one span as OTLP/JSON withcurl. It works from any machine, so it separates a key or network problem from a problem in your app:
HTTP 200 when Kubit accepted the span. Run it again with a different traceId to send a second test trace.
If it fails
More checks are in Is my data flowing?.
Next Steps
- Quickstart: check the extraction mapping and validate in Activity.
- Kubit SDK for Python: the same setup with span filtering and masking built in.
- Recipe: OTel traces in your own ClickHouse: send the same spans to your own Collector and ClickHouse instead, and read them in place.