# Core concepts

A short mental model for Brizz: trace, span, session, event, user, issue, intent, journey.

This page is the shared vocabulary every other doc links into. Read it once; come back when a term feels fuzzy.

## Trace

A **trace** is the record of a single end-to-end operation through your agent — for example, one user message and the chain of LLM calls, tool calls, and processing it triggered. Brizz reconstructs traces from OpenTelemetry data the SDK emits.

## Span

A **span** is one step inside a trace — an LLM call, a tool invocation, a function execution. Traces are trees of spans with start/end timestamps and attributes. Most automatic instrumentation produces spans without any code on your side.

## Session

A **session** groups multiple traces into a single user journey — typically one conversation thread. You provide the session ID; Brizz attaches every trace, event, and feedback signal that occurs inside it. Sessions are the primary lens for analysis in the dashboard.

→ Capture: [Sessions (instrumentation)](/docs/instrument/sessions.md)
→ Read: [Sessions (in the dashboard)](/docs/platform/sessions.md)

## Event

An **event** is a discrete signal you emit from your code — a business outcome, a milestone, a feedback action. Events are not LLM calls; they describe *what happened* (`order.placed`, `feedback.positive`) rather than *how* the model produced an answer.

→ [Custom events](/docs/instrument/custom-events.md)

## Metric

A **metric** is a number scored against a session — a quality rating, a latency, a cost. Where an event says *what happened*, a metric says *how well it went*. Brizz computes some itself; you can report your own (an eval score, a customer rating) as an **external metric**, and then filter and slice sessions by it.

→ Report: [Record metrics](/docs/instrument/record-metric.md)
→ Read: [External metrics](/docs/platform/external-metrics.md)

## User

A **user** is the person interacting with your agent. When you attach a `user_id` (and optionally `user_name`, `user_email`) to a session, Brizz unlocks user-level analytics: journeys, retention, segment-specific issues.

→ [Identify users](/docs/instrument/identify-users.md)

## Issue

An **issue** is a deduplicated problem detected across your traffic. When many occurrences describe the same underlying problem, Brizz groups them so you see *one row* with a frequency count, first/last seen, and affected users — not a flood of individual detections. Each issue carries an **issue type** (missing capability, technical failure, behavioral, and so on) and a **priority** — what to work on first, derived from how serious the problem is and how much of your traffic it affects.

→ [Issues](/docs/platform/issues.md)

## Intent

A **user intent** is a semantic cluster of similar prompts — "cancel my subscription," "stop auto-renew," and "turn off billing" collapse into one **Cancellation** intent. Brizz discovers intents automatically from your conversation data.

→ [User intents](/docs/platform/user-intents.md)

## Journey

A **user journey** is a common path users take through your agent — an aggregated flow built from many sessions. Journeys reveal where users drop off, what sequences lead to success, and how people actually use the product.

→ [User journeys](/docs/platform/user-journeys.md)

## See also

- [Glossary](/docs/help/glossary.md) — alphabetical, every term in one place.
- [Choose your SDK](/docs/sdks.md) — when you're ready to instrument.
- [Platform overview](/docs/platform.md) — what to look at in your first week.