Span attributes reference

Kubit Atlas reads standard OpenTelemetry attributes from your spans. This page lists which keys Atlas uses, what each one drives in the product and which ones you need to set yourself. It covers resource attributes, identity attributes, GenAI attributes and custom attributes.

When to use

Use case	Example
Group traces into conversations	Set `session.id` so every turn of one support chat lands in one session
Join agent runs to your users	Set `user.id` to the same ID your product events use
Compare releases	Set `service.version` so Triggers can compare Misstep rates before and after a deploy
Name the steps in an execution path	Set `gen_ai.tool.name` on tool spans so Flows shows `search_orders`, not a generic span name

Resource attributes

Resource attributes describe the service that produced the spans. Set them once, in configure() or on your TracerProvider.

Attribute	Required?	Used for
service.name	Yes	Telling agents apart. One value per agent or service.
service.version	Optional	Comparing releases in Triggers and Flows
deployment.environment	Optional	Keeping dev, staging and production apart

Identity attributes

Identity attributes connect a trace to the User and Session subjects. Atlas reads them from the root span of each trace.

Attribute	Required?	Used for
user.id	TBD	The User subject. Use the same ID your product analytics events use, so agent runs join to user behavior.
session.id	TBD	The Session subject. One value per conversation or multi-turn task.
gen_ai.conversation.id	TBD

Set both on the root span when the request starts:

handler.py

from opentelemetry import trace

tracer = trace.get_tracer("support-agent")

def handle_message(user_id: str, conversation_id: str, text: str) -> str:
    with tracer.start_as_current_span("invoke_agent support-agent") as span:
        span.set_attribute("user.id", user_id)
        span.set_attribute("session.id", conversation_id)
        return run_agent(text)  # your existing agent code

Constraint: Traces without user.id can’t be joined to users. Traces without session.id each count as their own session.

GenAI attributes

Atlas follows the OpenTelemetry GenAI semantic conventions. Instrumentors such as opentelemetry-instrumentation-openai-v2 set most of these for you.

Attribute	Set on	Used for
gen_ai.operation.name	Every GenAI span	Span kind: `chat`, `execute_tool`, `invoke_agent`, `embeddings`
gen_ai.request.model	LLM spans	Model comparisons in Triggers
gen_ai.response.model	LLM spans	The model that actually answered
gen_ai.provider.name	LLM spans	Provider, such as `openai` or `anthropic`. Older instrumentors set `gen_ai.system`.
gen_ai.usage.input_tokens	LLM spans	Token counts and cost
gen_ai.usage.output_tokens	LLM spans	Token counts and cost
gen_ai.tool.name	Tool spans	The step name in the execution path
gen_ai.tool.call.id	Tool spans	Linking a tool call to the LLM turn that requested it
gen_ai.agent.name	Agent spans	Telling agents apart inside one service

Message content

Polaris labels spans from their prompt, response and tool input and output. Instrumentors only record message content when this env var is set:

export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true

Constraint: Without message content, Polaris has no text to label.

Custom attributes

Any other attribute on a span is kept and can be used as a filter or Group By in Atlas, for example search.result_count or customer.plan.

Constraint	Value
Max attributes per span	TBD
Max attribute value length	TBD
Spans dropped by the default filter	HTTP route spans with no GenAI descendants

MCP prompt examples

“Show me the sessions for user 8812 in the last 7 days”

“Compare the Misstep rate on search_orders between service.version 1.4.0 and 1.5.0”

“Which traces in production yesterday had more than 5 tool calls, grouped by gen_ai.request.model?”

Concepts: the User, Session, Trace and Span subjects.
Send traces from Python: where to set these attributes in code.

Start here

Get started

Send traces

Bring your own warehouse

Span attributes reference

When to use

Resource attributes

Identity attributes

GenAI attributes

Message content

Custom attributes

MCP prompt examples

​When to use

​Resource attributes

​Identity attributes

​GenAI attributes

​Message content

​Custom attributes

​MCP prompt examples

​Related

When to use

Resource attributes

Identity attributes

GenAI attributes

Message content

Custom attributes

MCP prompt examples

Related