Dashboard spec reference

Embed

<a href="https://watchtowerops.net/docs/spec"><img src="https://watchtowerops.net/docs/_api/public/orgs/aa5959cb-1a0b-4a9a-bc9a-913e7ac31cd9/spaces/b7aac181-9916-4805-b253-becc5fd2ca62/pages/c939eff0-357f-4606-b2fe-43134a5a9ef7/social-card.svg?v=3e7ae33eec8b" alt="Dashboard spec reference" width="600" height="315"></a>

A dashboard is a JSON document: {"version": 1 or 2, "variables": [], "panels": [...], ...}. Version 2 only adds optional fields, so one schema covers both. The server stores the text you send verbatim (key order included) and refuses a spec that breaks a rule below, naming the path of the problem (panels[3].grid).

JSON Schema

GET /v1/projects/{prj}/dashboards/spec-schema returns the JSON Schema (draft 2020-12, application/schema+json). Use it in your editor or in CI to catch mistakes before an import. It checks shapes, names and enums; the rules in "Rules the schema cannot say" are checked only by the server.

Top level

Field	Type	Meaning
`version`	1 or 2	Required.
`panels`	array, at most 200	Required. The tiles.
`variables`	array	Template variables, usable as `$name` in queries and titles.
`sections`	array	Rows and tabs that group panels.
`filters`	object	Ad-hoc filters: `persist` (`dashboard`, `user`, `project`) and `keys`.
`annotations`	array	`{source, enabled}` references to annotation sources.
`settings`	object	Dashboard-wide settings.
`field_config`	object	Field display options every panel starts from.

Unknown fields are refused. The whole document is at most 256 KiB.

Panel

Field	Meaning
`id`	Required. `a-z`, `0-9`, `_`, `-`, 1 to 64 characters, unique in the dashboard.
`title`	Required, at most 200 characters.
`type`	Required. One of the panel types below.
`grid`	Required. `{x, y, w, h}` on a 24-column grid: `w >= 1`, `x + w <= 24`, `1 <= h <= 100`.
`query`	Required. `{kind, text}`; see Query kinds.
`options`	Free object read by the panel type (unit, thresholds, legend, and so on).
`targets`	Further queries A, B, ... and expressions over them; `query` stays the primary.
`transformations`	Steps run on the result frames, in order.
`field_config`	Display options of the result fields, laid over the spec's `field_config`.
`data_links`, `actions`, `channel`	Click-through links, buttons (at most 5) that POST to an allowed host, a live channel.
`repeat`, `section`, `time_override`, `visible_when`	One copy per selected variable value; the row or tab it belongs to; a range such as `6h`; show only while rules hold.
`library`, `powerpack`	The library panel or powerpack the panel comes from.

Panel types

Series and tables: timeseries, table, histogram, stat, gauge, barchart, heatmap, statetimeline, statushistory, trend, candlestick, scatter, toplist, pie, donut, treemap, sankey, change
Logs and traces: logs, logstable, logstream, traces, tracelist, waterfall, flamegraph, servicemap, nodegraph, profile_metric
Platform data: sql, rum, slo, alertlist, incident_stats, integration_health, activity_stats, cost_per, annolist, dashlist
Layout and content: markdown, image, iframe, canvas, geomap
plugin: a frontend panel plugin.

Query kinds

promql, logs, traces, sql, profile_metric, rum, plugin, cost_per, incident_stats, activity, cloud. text is the query string. For profile_metric, rum, plugin and cloud it is a JSON object written as a string (for example {"plugin": "name", "query": "..."}). A logs panel takes a logs query, traces a traces query, sql a sql query, and most other panels a promql query. A plugin or cloud query can feed a timeseries, table or stat panel (a plugin query also a logs panel). table accepts any kind.

Variables

name (a-z, 0-9, _, -, starts with a letter, at most 64, unique) and type:

Type	Options come from
`custom`	`options` (required, at most 100)
`query`	`query` (required): `label_values(metric, label)` or PromQL
`service`, `env`, `version`	The project's own values
`interval`	`auto` or durations in `options`; `auto_steps`, `min_interval` tune `auto`
`textbox`, `constant`	`default`
`datasource`	Data sources listed in `options`
`adhoc`	The viewer's own `key=value` filters
`switch`	`options[0]` / `options[1]`
`groupby`	Label names in `options`, or `label_names(metric)` in `query`

Optional: label, default, multi, include_all, all_value, regex, sort (none, alpha, alpha_desc, num, num_desc), depends_on, scope, refresh (load or time), server_bound.

Sections

{id, title, kind: "row" | "tab", collapsed?, parent?, repeat?, visible_when?}. Sections nest through parent, to a limited depth.

Rules the schema cannot say

Panel ids and variable names are unique.
A panel's query kind must fit its type (see Query kinds).
custom variables need options; query variables need query; options only on custom and query only on query variables.
A repeat names an existing multi or all variable; a section names an existing section.
Query texts are 1 to 4096 bytes.