← Decisions operate mode →

Decisions

ADR-011: One question per dashboard

Dashboards grow. A dashboard that started as "is this service healthy?" acquires a panel for the one time someone debugged a memory leak, then a panel for the weekly review meeting, then three panels for a migration,…

#011

ADR-011: One question per dashboard

Status: Accepted Date: 2026-04-21

Context

Dashboards grow. A dashboard that started as "is this service healthy?" acquires a panel for the one time someone debugged a memory leak, then a panel for the weekly review meeting, then three panels for a migration, then panels the author forgot to delete after the migration shipped. Nobody deletes panels; every panel was useful once. Six months later the dashboard has forty panels and answers no single question clearly.

The failure mode is not "the dashboard is wrong". The failure mode is "at 3am an engineer scans the dashboard for twenty seconds, doesn't see the single signal they need, and goes to Explore instead". The dashboard has quietly stopped paying for its pixels.

We need a discipline rule that stops the drift. A rule that is easy to cite in a PR review ("what question does this panel help answer?") is more durable than a rule that requires judgement on panel count alone (see ADR-012 for the count cap — this ADR is about purpose).

Decision

Every dashboard answers exactly one question. The question is stated in the dashboard's description field, in plain English, as a question. Every panel on the dashboard contributes to that question.

Concrete examples of the questions our Tier-0 set answers:

  • service-overview: "Is my service healthy right now?"
  • service-errors: "What failed, and for whom?"
  • service-resources: "Is the container healthy?"
  • service-canary-compare: "Is the canary regressing compared to stable?"
  • service-deploy-health: "Did this deploy break anything?"

Tier-1 platform dashboards follow the same rule: platform-incident answers "what is on fire right now?", not "what might be interesting to look at".

A panel that doesn't contribute to the dashboard's question is moved to a different dashboard (or deleted). "It would be nice to see X while I'm here" is the sentence that creates forty-panel dashboards; it is the sentence this ADR refuses.

Consequences

  • PR review has a single citable criterion. A reviewer asks "what question does this dashboard's description claim to answer? does this panel help answer it?" That is a conversation, not an opinion battle.
  • New dashboards are cheap. The pressure to stuff a new panel into an existing dashboard goes away when creating a new dashboard is the accepted path. The scaffold CLI makes new Tier-0 dashboards trivial to add.
  • Per-service dashboard count grows. Five Tier-0 dashboards per service, each answering one question, beats one "service everything" dashboard that answers several questions poorly. Grafana's folder UI handles the count fine.
  • Some investigations span dashboards. A real incident moves from service-overview (symptom) to service-errors (what failed) to service-deploy-health (did deploy break it). We accept this workflow: each dashboard answers its own question well, and the footer links chain them. Compare to a single mega-dashboard where the investigator scrolls past unrelated panels at every step.
  • Dashboard descriptions become load-bearing. The description field is not decoration; it is the contract the dashboard signs. Empty or vague descriptions ("Service dashboard") are PR blockers.
  • Deleting panels is a review action, not a sensitivity. A reviewer can propose "this panel doesn't help answer the question — delete?" without it being a personal call. The ADR is the third party in the conversation.
  • The rule has exceptions in one direction only. A dashboard may answer sub-questions of the one question (the error drill-down splits "what failed?" into category mix, recent lines, top messages — all facets of the same thing). It does not get to answer two unrelated questions.

Alternatives considered

  • Panel-count cap only. Rejected as insufficient: a 12-panel dashboard can still answer three unrelated questions badly. The cap is necessary but not sufficient; this ADR covers purpose, ADR-012 covers count.
  • Freeform, review-by-taste. Relies on every reviewer having the same taste. Rejected: taste drifts, and "the previous reviewer let a similar panel through" becomes the slippery default.
  • Auto-generated dashboards only, no humans. Code generates everything, nobody hand-edits. Rejected: incidents reveal questions the generator didn't anticipate; the on-call engineer needs to be able to build a dashboard in the UI and commit it. The generator handles the Tier-0 default set; humans handle the specific.
  • One dashboard per service, panels grouped in rows. Looks tidy. Rejected: rows don't solve the problem — the question of "which row do I look at right now?" is the same problem the ADR is solving, just inside a larger container.

Supersedes: none Superseded by: