# Explain this metric > Two people read the same tile and mean different things by it. - Canonical: https://patterns.konigi.com/dashboards/explain-this-metric - Group: Meta information - Level: implementation - Status: published - Updated: September 10, 2026 - Also called: definition tooltip, metric glossary --- ## Problem The tile says "Active users: 41,208". Marketing means anyone who opened the app this month. Engineering means anyone who made an authenticated request in the last 24 hours. Finance means anyone with a paid seat. All three read the same tile and leave the meeting agreeing on a number none of them share. ## Solution Put the definition next to the number. An info affordance on the panel opening a short, plain-language statement of what is counted, over what window, with what exclusions, and who owns it. The content is the hard part, and it is four things rather than one. **What is counted.** In the viewer's words, not the column name. "Anyone who made at least one authenticated request" beats `count(distinct user_id)`. **Over what window.** Almost every disagreement about a metric turns out to be a disagreement about the window. **What is excluded.** Internal traffic, bots, test accounts, refunds, cancelled orders. Exclusions are where two honest implementations diverge and neither party knows it. **Who owns it.** A name. A definition with no owner is a definition nobody can correct, and it will be wrong within a year. The failure mode this pattern addresses is specific and expensive: not that the number is wrong, but that it is right under a definition the reader doesn't hold. That failure produces confident, articulate disagreement, and it survives any amount of chart polish. The structural version of the answer is a modelling or semantic layer, where a metric is defined once and every surface reads that definition. That is better than tooltips and much harder to retrofit. The tooltip is what you can do this quarter; the model is what stops the problem recurring. ## Use when The audience is mixed, the metric name is ambiguous, or the number gets quoted outside the room it was shown in. Any tile that ends up in a board deck. ## Don't use when The metric is genuinely self-evident to everyone who sees it—a CPU percentage on an engineering dashboard needs no gloss, and adding one dilutes the affordance where it matters. ## Trade-offs Definitions rot faster than charts, because the query changes and the tooltip doesn't, and a stale definition is worse than none: it is authoritative and wrong. Writing them well is slow, and writing them badly produces the sentence "Active users is the number of active users". Tooltips also hide the definition behind an interaction most viewers never perform, so the people most likely to misread the number are the least likely to check. And a definition that admits a metric's messiness can undermine confidence in a number that was, in fact, fine. ## Checklist - Does the definition say what is counted in the reader's language? - Does it state the window? - Does it list exclusions—internal traffic, bots, test accounts, refunds? - Does it name an owner? - Is the definition stored with the metric, or retyped per dashboard? - When the query changes, what makes the definition change? - Is the affordance visible enough that someone who doesn't know they're confused might click it? - Is the same metric defined identically everywhere it appears? - Does the definition distinguish this metric from the similarly-named one next to it? - Could this be a modelling-layer definition rather than a tooltip? ## Compare **Looker** answers this structurally with LookML: metrics are defined in a modelled layer and every chart inherits that definition, so the tooltip is generated rather than written and cannot drift from the query. **Grafana** has no notion of a metric definition at all—panels carry a description field, and whether it holds a real definition or nothing is a matter of author discipline. **Honeycomb** sidesteps some of it by keeping raw events: the derivation is visible in the query rather than hidden behind a metric name someone chose months ago. **Sentry** has an advantage most products lack, in that its core objects are concrete enough to need little definition; an error either happened or it didn't, and the ambiguity lives in grouping rules rather than in counting. ## Related Data source badge answers where the number came from, which is the other half of the same trust question. Ratio and rate is the pattern where a hidden denominator does the most damage. Metric targets is where a definition becomes load-bearing, because a target on an ambiguous metric is an argument waiting to happen. KPI tile is the container that most needs this and most often lacks it. Hover detail is the interaction, and the entry that warns against making a tooltip carry a paragraph. ## Examples ### Netdata Per-second charts, hundreds per node, with a per-chart anomaly ribbon instead of a band on the series. **Anomalies / Anomaly advisor** — captured September 11, 2026, Netdata Agent, Anomaly advisor (public registry node, signed out). operational, medium density, dark theme, desktop-web. Netdata answers the anomaly problem without drawing a band at all, and the difference is worth recording. Rather than shading an expected range around each series, it scores every metric continuously and plots the result as its own series: the percentage of dimensions currently anomalous, and beneath it the count. Both sit near zero for most of the window and spike to about 0.04% at five separate moments. The trade is clear once you see it. A band tells you whether this metric is behaving, on the same axes as the metric, and needs one per chart. A rate tells you whether anything at all is behaving, in one chart, and cannot tell you which thing without a second step—which is what the panel at the bottom is for, and why it currently reads "You haven't highlighted any timeframe yet." The finding requires a brush selection before it will name a single metric. Hotspots in this capture: - [Anomaly band](https://patterns.konigi.com/dashboards/anomaly-band) — Not a band. An anomaly rate as its own series, so one chart covers every metric instead of one band per chart. - [Explain this metric](https://patterns.konigi.com/dashboards/explain-this-metric) *(this pattern)* — Every section carries a sentence saying what it counts, directly under its heading rather than behind an icon. - [Cross-filter](https://patterns.konigi.com/dashboards/cross-filter) — Highlight a timeframe and the page names which metrics drove it. The selection is the query. - [Empty state](https://patterns.konigi.com/dashboards/empty-state) — "You haven't highlighted any timeframe yet"—the reason for the blank, and the action that fills it. - [Share and embed](https://patterns.konigi.com/dashboards/share-and-embed) — Generate report, top right. Whether the highlighted window travels with it is the question the button raises. ### Grafana (Grafana Labs) The reference implementation for panel grids, template variables, and stat panels; most other tools are defined by how they differ from it. **Examples / Dashboard Variables** — captured September 10, 2026, Grafana Play (signed out; no version string exposed). analytical, medium density, dark theme, desktop-web. Six selectors across the top and the page is unusually honest about what they cost. The middle panel says there is a hidden variable called bestfood, currently set to pizza, which has no control anywhere on screen—state affecting the page that a viewer cannot see or change. The overview panel says that setting Instance and then changing the Prometheus source will clear your selection, because the two variables are chained and the second one invalidates the first. Both of those are correct behaviour and both are the reason parameterised pages get distrusted. What the top row gets right is the display: Instance and CPU Usage Type show their selected values as chips with an × rather than as a count, so what is filtering the page is legible without opening anything. Hotspots in this capture: - [Template variable](https://patterns.konigi.com/dashboards/template-variable) — Six selectors bound to every panel's query, with the chosen values carried in the URL. - [Filter bar](https://patterns.konigi.com/dashboards/filter-bar) — Values as removable chips rather than a dropdown saying Instance (3). - [Explain this metric](https://patterns.konigi.com/dashboards/explain-this-metric) *(this pattern)* — Names a hidden variable set to pizza. Prose is doing the work a control should. - [Categorical series palette](https://patterns.konigi.com/dashboards/categorical-series-palette) — Twelve-plus hostnames differing only in the middle digits, with twelve-plus colours to match. - [Data table](https://patterns.konigi.com/dashboards/data-table) — Four columns visible, the fourth cut mid-word, with no horizontal scroll offered. ## Related patterns - [Data source badge](https://patterns.konigi.com/dashboards/data-source-badge) — The viewer needs to know where a panel's data comes from and whether that source is healthy. - [Ratio and rate](https://patterns.konigi.com/dashboards/ratio-and-rate) — A raw count misleads; the viewer needs it normalized by a denominator they understand. - [Metric targets](https://patterns.konigi.com/dashboards/metric-targets) — The viewer wants the dashboard to know what 'good' is. - [KPI tile](https://patterns.konigi.com/dashboards/kpi-tile) — A person needs to know the current value of one number, and whether it's fine, before they look at anything else. - [Hover detail](https://patterns.konigi.com/dashboards/hover-detail) — The chart shows shape; the viewer needs the exact value at one moment without leaving it. ## Sources - [Nielsen Norman Group, Visibility of System Status](https://www.nngroup.com/articles/visibility-system-status/) - [Grafana, Data sources](https://grafana.com/docs/grafana/latest/datasources/) - [Bach et al., Dashboard Design Patterns](https://dashboarddesignpatterns.github.io/patterns.html) --- Screenshots on patterns.konigi.com are reproduced for commentary and criticism. Product names and marks belong to their owners.