# What is a metric?

A metric is one number with a definition: *open urgent tickets*, *server
errors*, *average response time*. It is the thing you track: build it once and
it can sit on any number of dashboards, goal lists and reports, with a target
to judge it by.

## What it represents

A metric is a **saved filter over a dataset**, plus a way to roll the matching
rows up into one value:

- **Which rows:** the filter. *Status code is 500 or more.*
- **How to roll them up:** count them, count distinct values, or take the sum,
  average, minimum or maximum of a number column.

It does not store the rows or the answer. It stores the question, as a small
piece of JSON text, and asks it again every time someone looks. That is why a
metric is always current, and why an agent can write one: a metric is text.

A dataset can have many metrics. Each is a different question about the same
data.

## How it's set up

**Goals → Metrics → New metric** opens the builder. From top to bottom:

1. **Name** it. A permanent **key** is made from the name; dashboards and
   agents refer to the metric by that key, so renaming is safe. A
   **description** says what it counts; it shows when someone hovers the
   metric's name in a list.
2. Pick the **dataset**.
3. Build the **filter**: conditions joined by ALL or ANY, with nested groups.
4. Choose the **aggregation**, and the measure column if it needs one.
5. Set the **period field**: the date column that a dashboard's or report's
   period narrows, and that a trend chart buckets by. Leave it blank for a
   number that doesn't depend on time, like *pending approvals*; such a metric
   can't be drawn over time.
6. Choose a **format** (number, compact, decimal, percent, currency, duration) and a
   **unit**.
7. Add **colour rules** if you want them: *10 or more is danger, 5 or more is
   warning*. The first rule that matches colours the number.

The preview shows the value and how many rows match as you go, and **See
them** opens those rows before you save.

You can also start on a dataset's page: filter its rows and choose **Make a
metric**. **Start from a metric** there loads one you have, to copy with
changes.

Two other kinds skip the filter. A metric **entered by hand** holds values
you type, for numbers that live in another tool. A **rate** is one metric
divided by another, such as errors ÷ requests.

## How to use it

- **On a dashboard:** add a card and pick the metric, or build a
  **component** from it first to control how it looks. A metric goes on the
  designs that show one number; a split or a chart filters a dataset of its
  own, and can start from the metric's filter.
- **In a goal list:** give it a target. **Add to goals** is on the metric's
  page and in the metrics list.
- **In a report:** add it as a row to compare it across periods.
- **On its own page:** see its value by period, the rows behind it, and every
  dashboard, report and goal list that uses it.
- **On any page of your project:** `{% metric_card "key" %}` in a template.

## Good to know

- **Editing a metric changes it everywhere.** The form lists where it's used
  before you save.
- **A card over a metric takes its format, unit and colour rules from it**,
  unless the card overrides them. A card that copied the metric's filter is on
  its own from then on: editing the metric doesn't reach it.
- **Deleting** shows what would break (cards, report rows, goals) and removes
  them in the same step unless you say otherwise.
- **Personal or shared.** A shared dashboard, report or goal list can only use
  shared metrics.
- A metric can be tagged, duplicated and archived. Archiving takes it out of
  lists and pickers but keeps it working wherever it's already used.