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.
The document
Section titled “The document”version: 1id: k8s-namespacetitle: Namespacevariables: - name: namespace source: metric: kube_pod_info label: namespacesections: - 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.
Elements
Section titled “Elements”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
Section titled “Thresholds”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
Section titled “Variables”variables: - name: namespace source: metric: kube_pod_info label: namespaceA 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.
Checking a file
Section titled “Checking a file”cargo install --git https://github.com/vedavid-dev/dashboard-dsl vedavid-dashvedavid-dash lint dashboards/vedavid-dash lint dashboards/ --deny-warnings # what CI should runEach 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.