Dashboard on materialize-monitoring Documentation

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 their respective packages within packages/. The current Python implementation lives in packages/grafana-dashboards as a uv workspace. Python helpers live in packages/py-mzmon-lib.

Within packages/grafana-dashboards, the top-level packages represent the family of concerns (e.g., mz_environment, infra). Within a family, each dashboard has its own sub-package (such as overview) with the main dashboard entrypoint suffixed with _dashboard.py.

Testing

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

Testing#

Dashboard code is tested with pytest. Unit tests are recommended to be placed next to their code with the _test.py suffix.

For broader code-quality tooling (ruff, pyright, configured linter rules), see Generating and Pushing Dashboards > Code quality.

TODO: This page is a stub. Expand with conventions for snapshot testing of dashboard JSON, fixture patterns, and integration testing against a live Grafana when those land.