Skip to content

Dashboard schema

A dashboard is one YAML document. The open-source compiler turns it into what the app renders, and vedavid-dash lint reports every problem in a file in one run. An unknown field is an error, not something ignored, so a file that lints today keeps its meaning on every later version.

dashboards/namespace.yaml
version: 1
id: k8s-namespace
title: Namespace
variables:
- name: namespace
source:
metric: kube_pod_info
label: namespace
sections:
- title: Compute
elements:
- type: line
title: CPU by pod
query: sum by (pod) (rate(container_cpu_usage_seconds_total{namespace="$namespace"}[5m]))
unit: cores
series:
label: "{{pod}}"
top: 5
- type: list
title: Memory by pod
query: sum by (pod) (container_memory_working_set_bytes{namespace="$namespace"})
unit: bytes
label: "{{pod}}"
Field Required Meaning
version yes The grammar the file is written in. Only 1 exists.
id yes The dashboard’s identity, used by the app and the connector. The filename carries no meaning.
title yes Shown in the app’s list.
variables no Values a query may refer to as $name; see below.
sections one of Titled groups of elements, in order. Section titles must be unique.
elements one of A single untitled section, for a short dashboard.

There is no size, position or column anywhere. Layout is a full-width vertical scroll in document order; the app lays consecutive stat elements out side by side.

Every element has these fields:

Field Required Meaning
type yes stat, line or list.
title yes Shown above the panel.
query yes PromQL. stat and list run it as an instant query, line as a range query over the window the app is showing.
unit yes How the numbers are formatted; see the list below.
id no Stable identity for the element; derived from the title when absent.
description no A sentence under the title.
thresholds no When a value is bad; see below.

One number, from a query that returns one series.

Field Default Meaning
decimals by unit Digits after the point.

One line per series over time.

Field Default Meaning
stack false Stack the series. Say this only when the series are parts of a whole.
min, max from the data Pin the axis.
series.label the series’ labels A template such as "{{pod}}" or "{{namespace}}/{{pod}}" naming each series.
series.top all Keep only this many series.
series.rank_by max How top chooses: max, mean, min or last. Needs top.

A labelled row per series, with the current value.

Field Default Meaning
label required A template naming each row, as for series.label.
sort desc desc, asc or label.
limit all Rows to show. Five is as many as a phone should ask anyone to read.
sparkline false Draw the recent trend beside each row.

short, count, percent, ratio, bytes, bytes_per_sec, seconds, milliseconds, duration, ops_per_sec, requests_per_sec, cores.

Every element needs one, because PromQL returns bare floats and nothing downstream can tell whether 1.4e9 is bytes or requests per second.

thresholds:
direction: above
steps:
- { at: 70, level: warning }
- { at: 90, level: critical }

direction is above, larger is worse, or below. at is an integer, so a ratio is best expressed as a percentage. level is ok, warning or critical. Steps must already be ordered in the declared direction; a misordered list is rejected rather than sorted, because it usually means something else was intended. A stat with thresholds is coloured by the level its value reaches, and a list colours each row.

variables:
- name: namespace
source:
metric: kube_pod_info
label: namespace

A variable’s values come from the label of a metric, and a query refers to it as $namespace. A query that names an undeclared variable is an error. The app asks for a value before running the panel.

shell
cargo install --git https://github.com/vedavid-dev/dashboard-dsl vedavid-dash
vedavid-dash lint dashboards/
vedavid-dash lint dashboards/ --deny-warnings # what CI should run

Each diagnostic carries a stable code and a path into the file:

error E-010: query references undeclared variable $cluster [elements[0].query]

E- codes fail compilation. W- codes do not, and cover things like a stat whose query has a by clause, which is likely to return more than one series, or a dashboard long enough to be a chore on a phone.