dashboards

What this skill does

# Grafana Dashboards

Dashboards are JSON: panels on a 24-column grid, fed by data-source queries, shaped by client-side transformations,
styled by standard options and overrides, parameterized by template variables, connected through annotations and links.
Data shape drives the visualization; variables make dashboards reusable; links carry context across navigation.

## Scope

- **In scope:** dashboard JSON (Classic and V2 schemas), panel selection and configuration, standard options,
  thresholds, value mappings, field overrides, transformations, all variable types, repeating panels/rows/tabs,
  annotations, dashboard/panel/data links, library panels, version history, panel editor and inspector.
- **Out of scope:**
  - **Data source query languages** — `promql`, `logsql`, `metricsql` are sibling skills. This skill governs how queries
    wire into panels, not query syntax.
  - **Grafana Alerting** — alert rules, contact points, notification policies belong to the `alerting` sibling skill.
    Panel-attached alert rules and the panel editor's **Alert** tab are integration points only.
  - **Provisioning, file-based dashboards, dashboards-as-code tooling** — Terraform, Grizzly, Foundation SDK, Helm
    charts, `provisioning/dashboards/*.yaml` belong to the `provisioning` sibling skill. This skill covers the JSON
    those tools emit.

## References

- **Dashboard JSON model (Classic + V2)** — [`${CLAUDE_SKILL_DIR}/references/json-model.md`] Top-level fields, panel
  object structure, `gridPos`, `timepicker`/`templating`/`annotations` blocks, library panel JSON shape, V2 Resource
  kinds, schema versioning, direct JSON edit mechanics.
- **Panels and visualizations** — [`${CLAUDE_SKILL_DIR}/references/panels.md`] Visualization-selection rules, panel-type
  catalog with `type` IDs, panel editor and inspector structure, library panel lifecycle, panel styles.
- **Panel deep dives (time series, stat, table)** — [`${CLAUDE_SKILL_DIR}/references/panel-deep-dives.md`] Per-panel
  configuration: time-series graph styles (line width, fill opacity, gradient mode, interpolation), axis placement,
  legend, tooltip, special overrides (Transform, Fill below to); stat value options, text modes, color and graph modes;
  table cell types, column filtering, sorting, tooltip-from-field, footer calculations.
- **Panel options** — [`${CLAUDE_SKILL_DIR}/references/panel-options.md`] Standard options (unit, min/max, decimals,
  color scheme, display name), thresholds, value mappings, field overrides, override precedence, display-name
  expressions.
- **Variables** — [`${CLAUDE_SKILL_DIR}/references/variables.md`] All variable types, syntax, format options, selection
  options, multi-value interpolation, multi-property variables, chained variables, regex filtering, global built-ins,
  URL sync, repeating panels/rows/tabs.
- **Transformations** — [`${CLAUDE_SKILL_DIR}/references/transformations.md`] Full catalog grouped by purpose (adding
  fields, filtering, reshaping, grouping, histograms, time-series modeling), common patterns, debugging mechanics.
- **Annotations and links** — [`${CLAUDE_SKILL_DIR}/references/annotations-links.md`] Native annotations, annotation
  queries, time regions, dashboard/panel/data links, data link variables, cross-dashboard navigation patterns.

## Dashboard structure

Six top-level concerns:

- **Identity** — `uid` (stable; externalize references via this), `title`, `tags`, `version`, `schemaVersion`. Never
  hand-edit `schemaVersion` or `version`.
- **Time** — `time.from`/`time.to`, `timezone`, `refresh`, `timepicker` (refresh intervals + quick ranges).
- **`templating.list`** — template variables. Array order = render order left-to-right.
- **`annotations.list`** — annotation queries. Built-in `-- Grafana --` query is always present.
- **`panels`** — panel objects. Layout via `gridPos` (24 columns × 30px per row unit).
- **`links`** — dashboard-level links (top of dashboard or controls menu).

Two schemas. **Classic** is the historical default and what grafana.com dashboards use. **V2 Resource**
(Kubernetes-style `apiVersion: dashboard.grafana.app/v2beta1`) supports advanced layouts and conditional rendering and
is the preferred format for new dashboards-as-code. See `json-model.md` for both schemas and the full panel object spec.

## Panel selection

Match data shape to visualization. Grafana's auto-suggestion reads shape, not intent — don't accept it blindly.

- Time-stamped numeric series → **Time series**
- Categorical numeric (one value per category) → **Bar chart**
- Distribution of values → **Histogram** (point-in-time) or **Heatmap** (over time)
- Discrete state changes over time → **State timeline**
- Periodic state snapshots → **Status history**
- Headline number with optional sparkline → **Stat**
- One value vs. min/max (radial) → **Gauge**
- Multiple values vs. min/max → **Bar gauge** (gauges scale poorly past 2–3 metrics)
- Proportional parts of a whole, segment count ≤ 7 → **Pie chart**; for ranking use **Bar chart**
- Tabular rows → **Table**; use the `sparkline` cell type with the **Time series to table** transformation for per-row
  trends
- Sequential numeric x that is not time → **Trend**
- Arbitrary x/y scatter → **XY chart**
- Logs/traces/profiles/geospatial/graph → **Logs** / **Traces** / **Flame graph** / **Geomap** / **Node graph**
- Markdown, HTML, or RSS → **Text** / **News**

Panel `type` IDs in JSON: `timeseries`, `stat`, `gauge`, `bargauge`, `barchart`, `histogram`, `heatmap`, `piechart`,
`table`, `logs`, `nodeGraph`, `traces`, `flamegraph`, `canvas`, `geomap`, `text`, `news`, `dashlist`, `alertlist`,
`annolist`, `state-timeline`, `status-history`, `candlestick`, `trend`, `xychart`.

## Panel configuration

Display pipeline order:

1. **Queries** return data frames.
2. **Transformations** reshape frames (client-side, ordered).
3. **Standard options** apply per-field (unit, min/max, decimals, color scheme, display name).
4. **Value mappings** translate values to display text and color.
5. **Thresholds** drive conditional colors (and lines/regions on supporting panels).
6. **Field overrides** apply per-field property changes. Last write wins.
7. Visualization renders.

### Standard options rules

- **Always set base units.** Pick from the catalog (`Time → seconds`, `Data → bytes`, `Throughput → reqps`). Don't
  pre-scale in queries — let Grafana scale for display.
- **For seconds-since-epoch timestamps**, multiply by 1000 with `Add field from calculation` → `Binary operation` before
  applying a `Date & time` unit. Grafana's date/time formats expect milliseconds.
- **`String` unit displays all decimals** when you need exact values without rounding.
- **Color scheme by intent:**
  - Categorical / series-name-stable → `Classic palette`
  - Series names change run-to-run → `Classic palette (by series name)`
  - Value-driven → `From thresholds (by value)` or `Single/Multiple continuous colors (by value)`
- **`No value`** — set a placeholder (`-`, `N/A`, `0`) so blank panels are unambiguous.

### Thresholds rules

- **Defaults**: `Base = green`, `80 = red`, `Mode = Absolute`. Override per panel — don't ship the default unchanged.
- **`Absolute`** when threshold values are real-domain numbers. **`Percentage`** only when comparing to dynamic
  `min`/`max`.
- **On time-series-like panels**, set `Show thresholds` explicitly (`As lines`, `As filled regions`) — default is `Off`.
- Table panels apply threshold colors only when cell display mode is `Color text` or `Color background`.

### Value mappings rules

- **Mappings bypass unit formatting** for matched values. Don't combine a mapped value with a unit suffix and expect
  both.
- **Order matters.** Grafana checks mappings top-to-bottom; first match wins.
- **`Special → Null` → "N/A"** to make missing data unambiguous in Stat/Table.

### Field overrides rules

- Match by **name** (exact), **regex**, **type**, **query refId**, or **values** (reducer condition).
- **Don't re