Home  /  Manage Materialize  /  Monitoring and alerting

Prometheus Community Helm Chart

This guide walks you through the steps required to monitor the performance and overall health of your Materialize instance using the prometheus-community/prometheus helm chart.

Before you begin

Ensure you have:

  • A self-managed instance of Materialize installed with helm values observability.enabled=true, observability.podMetrics.enabled=true, and prometheus.scrapeAnnotations.enabled=true
  • Helm version 3.2.0+ installed
  • kubectl installed and configured
! Important: This guide assumes you have administrative access to your Kubernetes cluster and the necessary permissions to install Prometheus.

1. Install Prometheus to your Kubernetes cluster using prometheus-community/prometheus

  1. Download the Materialize Prometheus scrape configuration file:

    curl -O https://raw.githubusercontent.com/MaterializeInc/materialize/refs/heads/self-managed-docs/v25.2/doc/user/data/self_managed/prometheus.yml

  2. Download the prometheus-community default chart values:

    curl -O https://raw.githubusercontent.com/prometheus-community/helm-charts/refs/heads/main/charts/prometheus/values.yaml

  3. Replace values.yaml’s serverFiles > prometheus.yml > scrape_configs with prometheus.yml’s scrape_configs. It should look something like:

    serverFiles:
   prometheus.yml:
      scrape_configs:
         - job_name: kubernetes-pods
         ...

  4. Create a prometheus namespace

    kubectl create namespace prometheus

  5. Install the operator with the scrape configuration

    helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update
helm install --namespace prometheus prometheus prometheus-community/prometheus \
--values values.yaml

2. Validate through the Prometheus UI

NOTE: The port forwarding method described below is for testing purposes only. For production environments, configure an ingress controller to securely expose the Prometheus UI.

  1. Set up port forwarding to access the Prometheus UI:

    MZ_POD_PROMETHEUS=$(kubectl get pods -n prometheus -l app.kubernetes.io/name=prometheus -o custom-columns="NAME:.metadata.name" --no-headers)
kubectl port-forward pod/$MZ_POD_PROMETHEUS 9090:9090 -n prometheus

  2. Access the Prometheus UI by navigating to localhost:9090 in your web browser.

Back to top ↑