# materialize-monitoring Documentation

> materialize-monitoring Documentation

## Pages
- [materialize-monitoring Documentation](https://materializeinc.github.io/materialize-monitoring/index.md)
- [Architecture](https://materializeinc.github.io/materialize-monitoring/architecture/index.md): Architecture Overview# This section provides an overview of the architecture of materialize-monitoring and its …
- [o11y Glossary](https://materializeinc.github.io/materialize-monitoring/o11y-glossary/index.md):  Glossary of Observability Terms# A reference for the vocabulary you’ll see across these docs. The audience is a …

## Getting Started
- [Getting Started](https://materializeinc.github.io/materialize-monitoring/getting-started/index.md)

- [Overview](https://materializeinc.github.io/materialize-monitoring/getting-started/overview/index.md): Getting Started with materialize-monitoring# There are a lot of ways to get started with materialize-monitoring. The …
- [Dependencies](https://materializeinc.github.io/materialize-monitoring/getting-started/dependencies/index.md): materialize-monitoring Dependencies# What has to exist before materialize-monitoring installs, and who provides it. …
- [Terraform](https://materializeinc.github.io/materialize-monitoring/getting-started/terraform/index.md): Installing via Terraform# For teams standing up self-managed Materialize with materialize-terraform-self-managed. The …
- [Helm](https://materializeinc.github.io/materialize-monitoring/getting-started/helm/index.md): Installing via Helm# If you are not using the terraform module to install materialize-monitoring, you can use the …

## Metrics
- [Metrics](https://materializeinc.github.io/materialize-monitoring/metrics/index.md)

- [Overview](https://materializeinc.github.io/materialize-monitoring/metrics/collecting/overview/index.md): Collecting Metrics# There are four ways metrics reach materialize-monitoring, and most deployments use more than one. …
- [Prometheus Remote Write](https://materializeinc.github.io/materialize-monitoring/metrics/collecting/prometheus-remote-write/index.md): Prometheus Remote Write# If you already run Prometheus, the simplest way to get its metrics into this stack is to have …
- [Scraping](https://materializeinc.github.io/materialize-monitoring/metrics/scraping/index.md): Scraping Metrics with materialize-monitoring# By default, materialize-monitoring is configured to scrape metrics from …
- [OpenTelemetry Endpoint](https://materializeinc.github.io/materialize-monitoring/metrics/collecting/opentelemetry-endpoint/index.md): OpenTelemetry Endpoint# The gateway accepts OTLP directly, so an OpenTelemetry Collector — or any application that emits …
- [Storing](https://materializeinc.github.io/materialize-monitoring/metrics/storing/index.md): Storing Metrics# alloy-gateway forwards the metrics it collects to one or more storage backends. Out of the box that is …
- [Prometheus Scraper](https://materializeinc.github.io/materialize-monitoring/metrics/collecting/prometheus-scraper/index.md): Prometheus Scraper (classic scrape_config)# For a Prometheus that is not operator-managed, or where this stack is not in …
- [Querying](https://materializeinc.github.io/materialize-monitoring/metrics/querying/index.md): Querying Metrics# Metrics are queried in PromQL, almost always through Grafana.
In the bundled stack, Grafana ships with …
- [Prometheus Operator](https://materializeinc.github.io/materialize-monitoring/metrics/collecting/prometheus-operator/index.md): Prometheus Operator (ServiceMonitors and PodMonitors)# This is the default path, and the one to reach for first when the …
- [Rules](https://materializeinc.github.io/materialize-monitoring/metrics/rules/index.md): Metric Rules#

## Logs & Events
- [Logs & Events](https://materializeinc.github.io/materialize-monitoring/logs-and-events/index.md)

- [Architecture](https://materializeinc.github.io/materialize-monitoring/logs-and-events/architecture/index.md): Logging Architecture# This page describes how container logs and Kubernetes events move through materialize-monitoring: …
- [Collecting](https://materializeinc.github.io/materialize-monitoring/logs-and-events/collecting/index.md): Collecting Logs & Events# Logs and Kubernetes events enter Loki through its write path after Alloy collects and …
- [Storing](https://materializeinc.github.io/materialize-monitoring/logs-and-events/storing/index.md): Storing Logs# Loki keeps all durable log data in a single object storage backend, maintained by the Loki Compactor. This …
- [Querying](https://materializeinc.github.io/materialize-monitoring/logs-and-events/querying/index.md): Querying Logs# Queries — almost always issued through Grafana — are served by Loki’s read path. This page covers …
- [Rules](https://materializeinc.github.io/materialize-monitoring/logs-and-events/rules/index.md): Log and Event Rules# Alerting and recording rules over logs are evaluated by the Loki Ruler on a schedule. This page …

## Dashboards
- [Dashboards](https://materializeinc.github.io/materialize-monitoring/dashboards/index.md)

- [Available Dashboards](https://materializeinc.github.io/materialize-monitoring/dashboards/all/index.md): Available Dashboards# Five dashboards ship today: three scoped to a Materialize environment (env-*), and two to the …
- [Importing Dashboards](https://materializeinc.github.io/materialize-monitoring/dashboards/grafana/importing/index.md): Importing Grafana Dashboards# This page covers the ways to get a Materialize dashboard into a Grafana instance. For the …
- [Grafana Architecture](https://materializeinc.github.io/materialize-monitoring/dashboards/grafana/architecture/index.md): Grafana Architecture# materialize-monitoring installs two Grafana-related subcharts, and they do different jobs. This …
- [Authentication](https://materializeinc.github.io/materialize-monitoring/dashboards/grafana/auth/index.md): Authentication# A fresh install has exactly one account: the admin, with a generated password. That is fine behind …
- [Grafana Operator](https://materializeinc.github.io/materialize-monitoring/dashboards/grafana/grafana-operator/index.md): Managing Dashboards with Grafana Operator# The Grafana Operator reconciles Kubernetes resources into a Grafana instance …
- [Datadog](https://materializeinc.github.io/materialize-monitoring/dashboards/datadog/index.md): Datadog# There is no Materialize dashboard set for Datadog yet. It is tracked as DEP-115 and scheduled for OO-M3, …

## Alerting
- [Alerting](https://materializeinc.github.io/materialize-monitoring/alerting/index.md)

- [Configuring](https://materializeinc.github.io/materialize-monitoring/alerting/configuring/index.md): TODO

- [Alert Channels](https://materializeinc.github.io/materialize-monitoring/alerting/channels/index.md): Alert Channels#
- [Maintenance Windows](https://materializeinc.github.io/materialize-monitoring/alerting/maintenance/index.md): Maintenance Windows#

## materialize-monitoring Operations
- [materialize-monitoring Operations](https://materializeinc.github.io/materialize-monitoring/operating/index.md)

- [Production Best Practices](https://materializeinc.github.io/materialize-monitoring/operating/production-best-practices/index.md): Production Best Practices# Production guidance for the materialize-monitoring stack, organized by backend. Every …
- [o11y Troubleshooting](https://materializeinc.github.io/materialize-monitoring/operating/o11y-troubleshooting/index.md): o11y Troubleshooting# Indexed by what you actually see — an error string, a pod that will not start, a change that …
- [Troubleshooting Materialize](https://materializeinc.github.io/materialize-monitoring/operating/troubleshooting-materialize/index.md): Troubleshooting Materialize# For when Materialize is unhealthy and the evidence has to come out of this stack — metrics, …
- [Meta Observability](https://materializeinc.github.io/materialize-monitoring/operating/meta-observability/index.md): Meta Observability#
- [Upgrading materialize-monitoring](https://materializeinc.github.io/materialize-monitoring/operating/upgrading/index.md): Upgrading materialize-monitoring# StatefulSet fields that cannot be patched# Most of a StatefulSet is mutable, but …
- [Uninstalling](https://materializeinc.github.io/materialize-monitoring/operating/uninstalling/index.md): Uninstalling materialize-monitoring# Uninstalling is not symmetric with installing. The chart’s Grafana resources …
- [Securing](https://materializeinc.github.io/materialize-monitoring/operating/securing/index.md): Securing materialize-monitoring# This page reads across the whole stack: what its trust boundaries are, what it is …
- [Tuning](https://materializeinc.github.io/materialize-monitoring/operating/tuning/index.md): Tuning your Observability Stack#

## Reference
- [Reference](https://materializeinc.github.io/materialize-monitoring/reference/index.md)

- [Contributing](https://materializeinc.github.io/materialize-monitoring/reference/internal/contributing/index.md): Contributing to materialize-monitoring# This is the canonical entry point for repo contributors. The audience is SRE, …
- [Overview](https://materializeinc.github.io/materialize-monitoring/reference/internal/dashboard/overview/index.md): Dashboards as Code# Instead of more common ClickOps strategies (manually configuring dashboards in the UI), we manage …
- [Overview](https://materializeinc.github.io/materialize-monitoring/reference/internal/design-docs/overview/index.md): Design Docs# These are proposed changes to materialize-monitoring.
Opening a non-draft pull request that adds a page …
- [Overview](https://materializeinc.github.io/materialize-monitoring/reference/internal/pipelines/overview/index.md): Pipelines as Code# Instead of hand-maintained alloy config files, we author pipeline definitions as YAML, validate them …
- [Overview](https://materializeinc.github.io/materialize-monitoring/reference/internal/queries/overview/index.md): Queries as Code# Monitoring queries are authored once as YAML under packages/queries/, validated against a project-owned …
- [Authoring](https://materializeinc.github.io/materialize-monitoring/reference/internal/pipelines/authoring/index.md): Authoring Pipelines# This page covers the model and conventions for authoring alloy pipelines as YAML under …
- [Alloy](https://materializeinc.github.io/materialize-monitoring/reference/images/alloy/index.md): Materialize Monitoring Alloy# mzmon-alloy is a minimal, distroless repackaging of Grafana Alloy hardened for use in …
- [List of Metrics](https://materializeinc.github.io/materialize-monitoring/reference/stable-metrics/list-metrics/index.md): List of Metrics# This has the list of metrics which are available for usage. In many systems, only a subset of metrics …
- [materialize-monitoring values](https://materializeinc.github.io/materialize-monitoring/reference/helm/materialize-monitoring-values/index.md):  materialize-monitoring Helm Reference# Unified observability stack for Materialize: Alloy-based pipeline, optional …
- [Metrics](https://materializeinc.github.io/materialize-monitoring/reference/internal/pipelines/metrics/index.md): Metrics Pipelines# Metrics are processed primarily in otelcol: Prometheus ingest and the final write use the …
- [Repo Layout](https://materializeinc.github.io/materialize-monitoring/reference/internal/repo-layout/index.md): This page is a convenience cache of where things live in the repo. The repository is under active development, so this …
- [SDKs and Schemas](https://materializeinc.github.io/materialize-monitoring/reference/internal/dashboard/sdks/index.md): SDKs and Schemas# The Grafana ecosystem has been undergoing major transitions in how dashboard configurations are …
- [Terraform variables](https://materializeinc.github.io/materialize-monitoring/reference/terraform/materialize-monitoring-variables/index.md):  Terraform variable reference# Inputs and outputs of the common materialize-monitoring Terraform module.
Most …
- [Datadog Translations](https://materializeinc.github.io/materialize-monitoring/reference/internal/queries/datadog/index.md): Datadog Translations# Every query in packages/queries/ carries a datadogQuery alongside its promQL. They render side by …
- [Logging](https://materializeinc.github.io/materialize-monitoring/reference/internal/pipelines/logging/index.md): Logging Pipeline# This is the authoritative reference for the log-processing pipelines that run on alloy-agent and …
- [Skills](https://materializeinc.github.io/materialize-monitoring/reference/internal/skills/index.md): Skills# .claude/skills/ holds authoring conventions that are consumed by both contributors and AI agents. They exist so …
- [Style Guidelines](https://materializeinc.github.io/materialize-monitoring/reference/internal/dashboard/style-guidelines/index.md): Dashboard Style Guidelines# Conventions for building visually consistent, operator-friendly dashboards. The audience for …
- [Common Alerts](https://materializeinc.github.io/materialize-monitoring/reference/stable-metrics/common-alerts/index.md): Common Alerts# Many of these alerts are not suited for all deployments. Do not use the entire set as is!
infra-alerts# …
- [Common Queries](https://materializeinc.github.io/materialize-monitoring/reference/stable-metrics/common-queries/index.md): Common Queries# These queries are used in various dashboards and may be a good starting point for a dashboard developer …
- [Generating and Pushing Dashboards](https://materializeinc.github.io/materialize-monitoring/reference/internal/dashboard/generating/index.md): Generating and Pushing Dashboards# How dashboard code is structured, how we keep generation deterministic, and how …
- [Stability Guarantees and Deprecation Policy](https://materializeinc.github.io/materialize-monitoring/reference/stability/index.md): Stability Guarantees and Deprecation Policy# This page describes what functionality provided by materialize-monitoring a …
- [Compatibility](https://materializeinc.github.io/materialize-monitoring/reference/compatibility/index.md): Release Compatibility# This shows the compatibility of materialize-monitoring with various technologies.
It is also …
- [Testing](https://materializeinc.github.io/materialize-monitoring/reference/internal/dashboard/testing/index.md): Testing# Dashboard code is tested with cargo test. Unit tests live in a #[cfg(test)] mod tests at the bottom of the …
- [Custom Resource Definitions (CRDs)](https://materializeinc.github.io/materialize-monitoring/reference/crds/index.md): Custom Resource Definitions (CRDs)# Kubernetes Custom Resource Definitions (CRDs) extend the Kubernetes API with custom …
- [Helm](https://materializeinc.github.io/materialize-monitoring/reference/internal/helm/index.md): TODO

- [Roadmap](https://materializeinc.github.io/materialize-monitoring/reference/internal/roadmap/index.md):  Roadmap# The goal of materialize-monitoring is first-class, composable observability for self-managed Materialize — …
- [Releasing](https://materializeinc.github.io/materialize-monitoring/reference/internal/releasing/index.md): Releasing# Each artifact releases on its own version stream (see Versioning).
Changes-pending placeholders# The top of …
- [Versioning](https://materializeinc.github.io/materialize-monitoring/reference/internal/versioning/index.md): Versioning in materialize-monitoring# All artifacts of this repo have separate versioning streams. They generally follow …
- [Changelog](https://materializeinc.github.io/materialize-monitoring/reference/changelog/index.md):  materialize-monitoring Changelog# materialize-monitoring (Helm chart + Terraform module) v0.23.0 (Unreleased)# Changes …
- [First-Class Production Loki Infrastructure](https://materializeinc.github.io/materialize-monitoring/reference/internal/design-docs/20260627-loki-production-infrastructure/index.md): First-Class Production Loki Infrastructure# author Heather Lapointe lastmod 2026-06-28 00:00:00 +0000 UTC …
- [Terraform Modules for materialize-monitoring](https://materializeinc.github.io/materialize-monitoring/reference/internal/design-docs/20260803-terraform-modules/index.md): Terraform Modules for materialize-monitoring# author Heather Lapointe lastmod 2026-08-03 00:00:00 +0000 UTC …
- [Observability for Bring-Your-Own-Cloud](https://materializeinc.github.io/materialize-monitoring/reference/internal/design-docs/20260813-byoc-observability/index.md): Observability for Bring-Your-Own-Cloud# author Heather Lapointe lastmod 2026-08-13 00:00:00 +0000 UTC publishdate …
- [In-cluster TLS and Certificate Authentication](https://materializeinc.github.io/materialize-monitoring/reference/internal/design-docs/20260816-tls-authentication/index.md): In-cluster TLS and Certificate Authentication# author Heather Lapointe lastmod 2026-08-16 00:00:00 +0000 UTC …
- [Stability Guarantees and Deprecation Policy](https://materializeinc.github.io/materialize-monitoring/reference/internal/design-docs/20260823-deprecation-policy/index.md): Stability Guarantees and Deprecation Policy# author Heather Lapointe lastmod 2026-08-24 00:00:00 +0000 UTC …
- [A Tenant-Scoped Query API for Console and Customer Grafana](https://materializeinc.github.io/materialize-monitoring/reference/internal/design-docs/20260916-tenant-query-api/index.md): A Tenant-Scoped Query API for Console and Customer Grafana# agent Claude Opus 5 author Heather Lapointe lastmod …
- [Call-Home: Opt-In Telemetry from Self-Managed to the Control Plane](https://materializeinc.github.io/materialize-monitoring/reference/internal/design-docs/20260917-call-home-self-managed/index.md): Call-Home: Opt-In Telemetry from Self-Managed to the Control Plane# agent Claude Opus 5 author Heather Lapointe lastmod …