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

# Span attributes reference

> The OpenTelemetry span and resource attributes Kubit Atlas reads to identify users, sessions, models, tools and execution paths.

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:

```python handler.py theme={null}
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:

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

## Related

* [Concepts](https://learn.kubit.ai/concepts.md#subjects): the User, Session, Trace and Span subjects.
* [Send traces from Python](https://learn.kubit.ai/send-traces/python.md): where to set these attributes in code.


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