Dashboard on materialize-monitoring Documentation

Overview

Mon, 01 Jan 0001 00:00:00 +0000

Dashboards as Code#

Instead of more common ClickOps strategies (manually configuring dashboards in the UI), we manage dashboards as reproducible source code. Sources live under packages/dashboards/.

The audience for this section is repo contributors — SRE, Field Engineering, CloudOps, Database Engineers — and AI agents reading the corresponding dashboards-as-code skill. The audience for the dashboards themselves (panel descriptions, naming, visual choices) is the Materialize end user; see Style Guidelines for that voice.

SDKs and Schemas

Mon, 01 Jan 0001 00:00:00 +0000

SDKs and Schemas#

The Grafana ecosystem has been undergoing major transitions in how dashboard configurations are managed circa 2025; web searches frequently turn up inconsistent or outdated documentation. This page pins down what we target, what we generate, and which SDKs we use to do it.

Targets#

Currently supported:

Grafana 13 (Dashboard v2 schema) — latest as of April 2026, primary target
Grafana 12 (Dashboard v2beta1 schema)

Planned (stubs are acceptable for now):

Style Guidelines

Mon, 01 Jan 0001 00:00:00 +0000

Dashboard Style Guidelines#

Conventions for building visually consistent, operator-friendly dashboards. The audience for the dashboards themselves is Materialize end users: database-literate operators with basic graph-reading fluency but minimal cloud / Kubernetes / observability expertise. SQL is fair game; jargon like “differential dataflow’s arrangement” needs a one-liner explanation when it appears.

Layouts#

Prefer automatic layouts over fixed positioning. Dashboard v2 provides more ergonomic options like Tabs and a formal automatic layout system.

Generating and Pushing Dashboards

Mon, 01 Jan 0001 00:00:00 +0000

Generating and Pushing Dashboards#

How dashboard code is structured, how we keep generation deterministic, and how dashboards flow from source code into a live Grafana instance.

Code structure#

Dashboards live in packages/dashboards (the mz-dashboards crate), one module per backend under src/. grafana/ is the only backend today; a Datadog or Google Cloud Monitoring backend belongs beside it rather than inside it, since little is genuinely shared — the queries differ per engine and each SDK has its own panel and layout model.

Testing

Mon, 01 Jan 0001 00:00:00 +0000

Testing#

Dashboard code is tested with cargo test. Unit tests live in a #[cfg(test)] mod tests at the bottom of the module they cover; the suites that need the whole dashboard live under packages/dashboards/tests/.

For broader code-quality tooling see Generating and Pushing Dashboards > Code quality.

What each suite is for#

Suite	Covers
`dashboards/tests/env_top_parity.rs`	the port against the frozen Python render: titles, plugin/unit, queries, transformations, tab/row skeleton, variable set
`dashboards/tests/registry_contract.rs`	that every registry id a panel names resolves, and that a bad id or legend mismatch is reported rather than rendered
`mzmon-lib/tests/grafana_golden.rs`	that the generated models round-trip a real Dashboard v2 document
`mzmon-lib/tests/grafana_end_to_end.rs`	a complete dashboard built through every layer, then deserialized back through the models
`mzmon-lib/tests/grafana_query_bridge.rs`	the query bridge against the real registry under `packages/queries/`
`charts/materialize-monitoring-dashboards/tests/dashboards_test.yaml`	that the chart ships what `selected` selects — the patterns are globbed against the pre-rendered tree, so a dashboard joins or leaves the release silently otherwise — and that its resource names do not collide with the ones the umbrella chart used to create
in-module tests	per-tab structure, selector shapes, threshold ladders, panel presets

The models carry deny_unknown_fields, so anything invented along the way fails at deserialization rather than at push time.