dashboards-as-code

Generates and maintains Grafana dashboards as Rust code with PromQL and LogQL queries for Materialize observability.

3|Updated May 1, 2026
One-click install
npx skills add https://github.com/MaterializeInc/materialize-monitoring --skill dashboards-as-code-materializeinc
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: dashboards-as-code
Source: https://github.com/MaterializeInc/materialize-monitoring/tree/main/.claude/skills/dashboards-as-code
Command: npx skills add https://github.com/MaterializeInc/materialize-monitoring --skill dashboards-as-code-materializeinc

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Building and maintaining Grafana dashboards for Materialize observability by hand is error-prone: schema shapes change across Grafana versions, PromQL queries drift from panel prose, and pushing updates requires knowing the exact API envelope. This Skill codifies the conventions, schema references, and current dashboard state so dashboards are generated from Rust against vendored Grafana schemas and stay consistent. ## Core Features & Use Cases - Dashboard generation from Rust: Build, modify, review, and push dashboards under packages/dashboards/ generated against cog-generated Grafana JSON schemas (v1, v2beta1, v2) vendored from the grafana-foundation-sdk. - Query registry integration: Panels draw PromQL and LogQL from the query registry under packages/queries/ rather than writing queries inline, keeping prose and queries in sync. - Materialize-specific guidance: Conventions for cluster/replica filtering, peek latency, source/sink metrics, label-family quirks, palettes, tab theming, and panel description voice. - Use Case: Add a new tab to the env-top dashboard showing sink throughput, reusing registry queries and the per-tab theme, then render and push it to a local Grafana via the documented PUT body shape. ## Quick Start Ask the assistant to add a new panel to the env-top Compute tab using a query from the packages/queries registry and render the updated dashboard JSON.

Frequently Asked Questions about dashboards-as-code

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I generate Grafana dashboards from Rust code?

Dashboards are defined as Rust modules under packages/dashboards/ using types generated from vendored Grafana JSON schemas, then rendered with mz-monitoring-build gen-dashboards. Output goes to chart YAML and docsite JSON, one file per dashboard.

How do panels get their PromQL queries in this project?

Panels do not write PromQL inline; they reference the query registry under packages/queries/, which defines the schema, engines, and templating. This keeps panel prose and queries synchronized across dashboards.

Which Grafana dashboard schema versions are supported?

Three cog-generated JSON Schema documents are vendored: dashboard v1 (tracking Grafana v11.6.0), v2beta1, and v2 (both tracking Grafana v13.0.2). They come from the grafana-foundation-sdk release tag v0.0.18.

How do I push a generated dashboard to a local Grafana instance?

Render with mz-monitoring-build gen-dashboards --format json, then PUT with the Kubernetes-style envelope carrying the live resourceVersion and folder annotation. The gcx context local-mzmon targets http://localhost:13000.

Why do rate() panels show no data on some Materialize metrics?

A datasource timeInterval misconfiguration can empty rate() panels, and some metrics like hydration state have no self-managed Prometheus equivalent. The style guide documents these known metric quirks and the SQL-backed fallbacks.

Can these dashboards query cloud Materialize environments?

The dashboards target self-managed Materialize, scoped by materialize_cloud_organization_name; cloud-only labels like materialize_cloud_organization_id and the v2_mz_* metric family do not exist on self-managed. Always verify labels with list_prometheus_label_names before querying.