materialize-monitoring Documentation#
materialize-monitoring is first-class observability for Materialize deployments — metrics, logs, events, dashboards, and alerts, packaged as a Helm chart and a Terraform module.
It is a one-stop shop for teams who want one, and every piece of it can be turned off for teams who already run their own.
If you install Materialize with the Terraform modules, the stack comes up with the cluster by default from materialize-terraform-self-managed v11 onward — set enable_observability = false to opt out.
Nothing here is required to run Materialize. If you are looking for the main Materialize documentation, see materialize.com/docs.
Pre-1.0. Interfaces are still moving, and breaking changes can ride a minor release until 1.0 is stamped. See the Roadmap for what is built and what is coming, and the Changelog for what has shipped.
Start here#
- Getting Started — the installation paths, and how to choose between them.
- Installing via Terraform — the recommended path: observability comes up with the cluster.
- Installing via Helm — the full-fidelity surface, for when Terraform is not how you deploy.
- Dependencies — what has to exist in the cluster before any of it installs.
- Production Best Practices — the checklist before this runs anywhere that matters.
How it works#
- Architecture — the umbrella chart, the components it bundles, and how telemetry moves between them.
- o11y Glossary — the vocabulary the rest of these pages assume.
By signal#
| Metrics | Collecting — the four ways metrics get in — plus scraping, storing in Thanos, and querying them back out |
| Logs & Events | The Alloy agent/gateway split, collecting, storing in Loki, querying, and rules |
| Dashboards | Available dashboards and importing the Grafana set, the Grafana Operator path that keeps it in sync, how Grafana is wired, authentication, and Datadog |
Two areas are still stubs and are not linked above: Alerting, and Metrics → Rules. They appear in the sidebar because the sections exist; the Roadmap tracks the work behind them.
Operating the stack#
- Production Best Practices — sizing, retention, replication, disruption budgets, and durability, each tagged by who owns it.
- Securing — network policy, in-cluster TLS, and exposing Grafana.
- Upgrading and Uninstalling — including the teardown ordering that avoids a finalizer deadlock.
- o11y Troubleshooting — when the monitoring itself is the thing that is broken.
Reference#
- materialize-monitoring values — the generated Helm values reference.
- Terraform variables — the generated module variable reference.
- Reference Metrics — the metrics the dashboards depend on, plus common queries and common alerts.
- Compatibility — supported versions of Materialize, Grafana, GKE, and the Terraform modules.
- Custom Resource Definitions — the custom resources the stack reads and relies on.
- Changelog — per-component release history.
For contributors#
- Contributing — the contributor guide, conventions, and the pre-commit wiring.
- Roadmap — the current source of truth for what is built, in flight, and planned next.
- Repository Layout — where things live in the repo.
- Versioning and Releasing — the per-component version streams and the release automation.
- Design Docs — the decisions behind the larger pieces.
Getting help#
Please reach out for Support, or open an issue on GitHub.