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

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

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

External metrics do **not** appear in the conversation transcript or on the Events page. They're measurements *about* a conversation, not things that happened *in* it.

## Re-scoring and the latest value

Reporting the same metric for a session again supersedes the previous value — the newest report wins. 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, the validation rules, and how to attach a metric to a session out-of-band.

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.** 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.
- [Sessions](/docs/platform/sessions.md) — where you filter by them.
- [Custom events](/docs/instrument/custom-events.md) — for things that *happened*, rather than things you measured.