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’s a one-stop shop if you want one, and you can turn off any piece of it if you already run your 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.
To opt out, set enable_observability = false.
Nothing here is required to run Materialize. For Materialize itself, see the Materialize documentation.
From v1.0.0, a breaking change to the committed surface goes through a deprecation cycle and lands only in a major release. For what you can rely on, see the stability guarantees. For what’s planned, see the Roadmap, and for what has shipped, see the Changelog.
Start here#
- Vision — what the project is for, where it is going, and why.
- 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 |
| Alerting | The alert architecture from ruler to receiver, configuring the rule evaluators, alert channels, maintenance windows, and configuring alerting through Terraform |
| Dashboards | Available dashboards and importing the Grafana set, the Grafana Operator path that keeps it in sync, how Grafana is wired, authentication, and Datadog |
Metrics → Rules is a stub, so this page doesn’t link to it. It appears in the sidebar because the section exists, and the Roadmap tracks the work behind it.
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.
- Compatibility — supported versions of Materialize, Grafana, GKE, and the Terraform modules.
- Common Alerts — the bundled alerting rules, and the page each alert’s
runbook_urlpoints at. - Common Queries — the PromQL behind the dashboard panels.
- List of Metrics — the metrics the dashboards depend on.
- 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.