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

# Concepts

> Definitions of users, sessions, traces, spans, execution paths and Polaris annotations (Action, Exception, Misstep, Warning) in Kubit Atlas.

Kubit Atlas organizes agent data into four fixed subjects: User, Session, Trace and Span. Polaris adds annotations to every span, and Flows groups traces by execution path. This page defines each term as Atlas uses it.

## Subjects

Atlas has exactly four subjects. They're the same in every workspace and don't depend on your schema.

| Subject | What it is | Identified by |
| - | - | - |
| **User** | The end user who started the trace | User ID |
| **Session** | A group of related traces, such as one conversation | Session ID |
| **Trace** | One end-to-end agent run or request | Trace ID |
| **Span** | One operation inside a trace: an LLM call, a tool call, a retrieval | Span ID |

The hierarchy is User → Session → Trace → Span. A user has sessions, a session has traces and a trace has spans. You can start at any level and drill down.

[Span attributes](https://learn.kubit.ai/send-traces/span-attributes.md) lists the attribute keys Atlas reads to fill in User ID and Session ID.

## Trace and span

A trace is one run of your agent, from the incoming request to the final response. A span is one timed operation inside that trace, with a start time, an end time, a parent and a set of attributes.

Atlas uses standard OpenTelemetry traces and spans. A span your existing OpenTelemetry setup produces is a span in Atlas, with no conversion.

**Availability:** Atlas time is span start time unless a page says otherwise.

## Execution path

An execution path is the ordered sequence of steps in one trace: which tools and model calls ran, in what order. Two traces that called `search_orders`, then `get_refund_policy`, then the LLM, share one execution path, even if their inputs differ.

Flows draws every execution path in one Sankey. Each path shows how many traces took it, so a failure that repeats a thousand times shows up as one path with a count of 1,000.

When two runs call the same tools with different arguments, Polaris labels or custom eval scores split them into separate paths.

## Polaris annotations

Polaris annotations are the labels and scores Polaris adds to every span. Polaris is Kubit's in-house small language model. It labels each span in under a second, on every span, with no sampling.

Polaris has three parts.

| Part | What it produces |
| - | - |
| **Classifier** | Labels on every span: annotation type, plus intent, sentiment, failure and hallucination |
| **Fine-tuning** | A classifier retrained on the label corrections your team makes in the workspace |
| **Evals** | Scores from your own eval prompts. A score can be a number, a true/false or a value from a list you define. |

"Label" always means classifier output. Eval output is a "score". Evals run on Polaris and are included in Atlas at no extra cost.

### Annotation types

Every span gets one of four annotation types.

| Type | Meaning | Example |
| - | - | - |
| **Action** | The span did its job: an LLM call, a retrieval or a tool call | `get_order_status` returned the order |
| **Exception** | The call failed: an exception, a 4xx or 5xx response, a timeout or no network | `charge_card` returned HTTP 502 |
| **Misstep** | The call ran, often with an OK status, but did the wrong thing | `issue_refund` ran with the shipping fee as the refund amount |
| **Warning** | The span is a risk even if it worked: a loop, high cost, high latency, high frequency, detected PII or a spike | The agent called `search_docs` 14 times in one trace |

Exception and Misstep are different. An Exception shows in your error logs. A Misstep usually doesn't, because the call returned OK.

## Workspace

A workspace holds one set of traces, its API keys, its Polaris labels and its reports. An organization can have several workspaces, for example one per environment or per agent.

## MCP prompt examples

> "Show me the sessions for user 8812 in the last 7 days"

> "Which execution paths for the support agent had a Misstep on a tool call yesterday?"

> "Compare the Exception rate by model version for traces in the last 30 days"

## Related

* [What is Kubit Atlas](https://learn.kubit.ai/index.md): the features built on these concepts.
* [Span attributes](https://learn.kubit.ai/send-traces/span-attributes.md): how your spans map to users and sessions.
* [Quickstart](https://learn.kubit.ai/quickstart.md): send your first traces.


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