# External metrics

Bring your own scores into Brizz — eval results, ratings, latencies — and filter and slice sessions by them.

**External metrics** are numbers *your* system produces about an interaction: an LLM judge's score, a customer's star rating, a latency budget, a cost. You report them with [`record_metric`](/docs/instrument/record-metric.md), and Brizz treats them as first-class metrics alongside the ones it computes itself.

## What it is

Most teams already grade their own agent. An eval harness scores every answer for quality and groundedness; a human reviewer rates a sample each morning; a nightly job re-grades yesterday's conversations with a stronger judge. Those numbers usually live somewhere else — a spreadsheet, a warehouse table, a dashboard nobody opens next to the conversation that produced them.

An external metric puts that number on the session. Once it's there you can ask the question that actually matters: *show me every conversation my judge scored below 0.6* — and then read those conversations.

## Where they show up

**Session Details → Metrics.** Every metric reported for a session is badged in the details panel, next to the ones Brizz computes. `Answer Quality 0.34`, `Hallucination Risk 0`.

**The metric drawer.** Click a badge to open it. You get a gauge showing where the value sits on its scale, the `comment` you attached (an evaluator's rationale, a reviewer's note), and the metric's attributes as chips — which judge produced it, which rubric version, which variant the user saw.

Because you tell Brizz the metric's scale (`min_value` / `max_value`) and its **polarity** — whether a rising value is good or bad — this gauge colours correctly without further instruction. A high `answer_quality` reads as healthy; a high `hallucination_risk` reads as a problem.

**Sessions → filters.** Each metric you've reported becomes a numeric filter on the Sessions page, offering `>`, `≥`, `<`, `≤`, `=`, `≠`, and `exists`. Brizz builds the filter list per service from the metrics it has actually seen, so a metric appears in the dropdown as soon as you start reporting it — there's nothing to configure.

**Issue details → Your metrics for this issue.** When the service has external metrics in the selected date range, Brizz lists them even if none of the issue's sessions reported a value. Reported values are averaged over the measured issue sessions and compared with the service average. The summary rows always show; **Distribution** appears when Brizz has distribution data with measured sessions for both the issue and the service. With one to four measured issue sessions, Brizz withholds the verdict and shows **too few to compare** in the summary and, when available, Distribution.

A session-level metric does **not** appear in the conversation transcript or on the Events page: it's a measurement *about* the conversation, not something that happened *in* it. A per-turn metric is badged on its turn — see below.

## Per-turn metrics

Some scores describe one turn, not the whole conversation — a frustration rate per user message, a groundedness score per answer. Report those with `scope="trace"` (`scope: 'trace'` in TypeScript), and each trace keeps its own value instead of the next turn's report replacing it.

- **In the conversation**, each turn's value is badged on that turn's reply.
- **At the session level** — the Metrics panel, the Sessions filter, charts, and the issue comparison — the session's value is the **average of its turns**. If the same metric was also reported for the session itself, that session value wins: it's your own verdict on the conversation.
- **The metric drawer** lists the value of every turn behind the average, with each turn's comment and its own "Was this assessment accurate?" thumbs. Discarding a turn's value takes it out of the average. The average itself has no thumbs: give feedback on the turn that's wrong.
- **A discarded session value stays in the drawer**, greyed out under **Session value**, while the session's value falls back to the average of its turns. To restore it, click that row's thumbs-down again: this removes your feedback, discard included.

## Re-scoring and the latest value

Reporting the same metric for a session again supersedes the previous value — the newest report wins. A per-turn metric works the same way per trace: re-scoring a turn replaces that turn's value and leaves the others alone. That's what makes offline evaluation work: a nightly job can re-grade a conversation with a better judge, and the session's score updates to reflect the correction rather than keeping the original.

Pass a `timestamp` when you re-score to record *when the thing you measured happened*, as opposed to when you got around to measuring it. Brizz still resolves "which value is current" by when the report arrived, so a backdated re-score correctly supersedes the original instead of being buried under it.

## Reporting them

See [Record metrics](/docs/instrument/record-metric.md) for the SDK reference — the fields and the validation rules. [Online evaluation](/docs/instrument/record-metric/online-evaluation.md) covers scoring inside the agent during the session; [Offline evaluation](/docs/instrument/record-metric/offline-evaluation.md) covers scoring later or from a separate process, across many services, by session id or trace id.

A few things worth knowing:

- **Values are numbers.** Categorical facts about the measurement go in `attributes` (which evaluator, which rubric), not in the value.
- **Names Brizz uses or has used are reserved.** `faithfulness`, `session_outcome`, and other Brizz-managed metric names can't be overwritten — pick your own name.
- **A metric needs a session, or a trace that resolves to one.** It's anchored to a conversation; without one there's nothing to attach it to.

## Related

- [Record metrics](/docs/instrument/record-metric.md) — the SDK API.
- [Offline evaluation](/docs/instrument/record-metric/offline-evaluation.md) — scoring from a batch job or a separate eval process.
- [Sessions](/docs/platform/observe/sessions.md) — where you inspect and filter by them.
- [Issues](/docs/platform/issues.md) — where you compare them for one issue against the service baseline.
- [Custom events](/docs/instrument/custom-events.md) — for things that *happened*, rather than things you measured.

---

[All Brizz documentation](https://docs.brizz.ai/llms.txt) · [Full documentation (single file)](https://docs.brizz.ai/llms-full.txt)
