# Labels

Categorize sessions and other entities — manually, by rule, or with AI — then filter and group your analytics by them.

**Labels** are how you categorize your data in Brizz. Attach a label to a session (or another entity) and it becomes a dimension you can filter and group by everywhere else — a way to carry your own vocabulary into the analytics, not just the fields the SDK sent.

## What it is

A label marks an entity as belonging to some category you care about — a plan tier, a customer segment, a review status, a product area. Once applied, a label isn't just a tag on one record; it's a dimension you can slice the whole product by.

Labels come in two shapes: a **plain label** and a **label group**.

## Labels vs. label groups

- **Plain label** — a single category applied on its own. An entity either has it or doesn't.
- **Label group** — a label with a set of **allowed values**. A `plan` group might allow `free`, `pro`, and `enterprise`; a `review-status` group might allow `pending`, `approved`, and `rejected`. Each value can carry its own **color** and **description**, so the group reads clearly wherever it's shown.

Reach for a group when you want related categories managed together; reach for a plain label when it's a standalone flag. Groups can be mutually exclusive, but an [AI classification rule](#labeling-rules) can assign several values to the same session when it's configured to allow multiple values — the **Single value** checkbox in the labeling-rule editor, or **Single category per session** in the classification editor.

## How labels get applied

A label reaches an entity in one of three ways:

- **Manually** — someone applies the label directly to an entity.
- **By a labeling rule** — a saved rule applies the label automatically as data arrives.
- **By AI** — "auto-assign with AI" classifies entities and applies the label for you, so you don't have to write the matching logic by hand.

The three paths coexist. A label can be applied by hand to one session and by a rule or by AI across thousands of others.

## Labeling rules

Labeling **rules** are how you automate application instead of tagging entities one at a time. A rule targets a label and decides what gets it. Rules come in two kinds:

- **Manual matching** — a rule you define with explicit matching criteria.
- **AI classification** — a rule that hands classification to the AI, which decides which entities match and applies the label.

Rules are an admin capability — see [Availability](#availability). The rule editor is the in-product source of truth for what each rule kind can target and how it's configured.

## Using labels

Once a label exists and is applied, it becomes a dimension across the analytics:

- **Filter** by a label to narrow any view to the entities that carry it.
- **Group by** a label to break a metric out along your own categories — for example, group a [custom chart](/docs/platform/custom-charts.md) by a label to compare a metric across its values. For a multi-value classification, one session can count toward several values, so per-value counts can overlap.

### System labels

Brizz ships some **system labels** of its own. The clearest example is **`product-area`**, which organizes the Issues view — it drives the product-area treemap on the Issues Overview. System labels exist alongside your own, and you can filter and group by them just the same. The difference is ownership: system labels are **read-only** to your tenant. You use them; you don't edit them.

## Availability

**Viewing** labels is available to any member — the `/labels` page is read-only for members, so anyone can see which labels exist and how they're defined. **Managing** labels (creating and editing them) requires admin or higher. **AI auto-assign** additionally needs a plan that includes AI labels. **Managing labeling rules** requires admin or higher. If you can see labels but can't change them, your role is view-only for this area.

## See also

- [Labeler instances](/docs/admin/labeler-instances.md) — configure the automatic labelers that apply labels for you.
- [Notifications](/docs/platform/notifications.md) — a Label Digest delivers label trends on a schedule.
- [Custom charts](/docs/platform/custom-charts.md) — group any chart by a label.
- [Issues](/docs/platform/issues.md) — the product-area system label organizes the Issues view.