Implementation:MaterializeInc Materialize Monitoring Mzcompose

Overview

The monitoring mzcompose module defines a Docker Compose workflow that spins up a local observability stack for Materialize development. It provisions Prometheus, Tempo, and Grafana as containerized services, enabling developers to collect metrics, traces, and visualize them through dashboards.

The module is located at misc/monitoring/mzcompose.py.

Services

The composition defines three services:

Service	Image	Ports	Purpose
Prometheus	prom/prometheus:v2.46.0	9090:9090	Metrics collection and querying
Tempo	grafana/tempo:2.2.0	4317:4317, 3200:3200	Distributed tracing backend
Grafana	grafana/grafana:10.0.3	3000:3000	Visualization and dashboarding

Prometheus

Prometheus is configured to receive metrics via its remote write receiver:

Service(
    "prometheus",
    {
        "image": "prom/prometheus:v2.46.0",
        "ports": ["9090:9090"],
        "volumes": [
            "./prometheus.yml:/etc/prometheus/prometheus.yml",
            "../../mzdata/prometheus:/mnt/services",
        ],
        "command": [
            "--config.file=/etc/prometheus/prometheus.yml",
            "--web.enable-remote-write-receiver",
        ],
        "extra_hosts": ["host.docker.internal:host-gateway"],
        "allow_host_ports": True,
    },
)

Key configuration details:

• Mounts a local prometheus.yml configuration file.
• Binds mzdata/prometheus from the repository root for persistent data.
• Enables the remote write receiver endpoint (--web.enable-remote-write-receiver).
• Maps host.docker.internal to the host gateway for scraping host-side services.

Tempo

Tempo provides distributed tracing with OpenTelemetry Protocol (OTLP) ingestion:

• Port 4317 accepts OTLP gRPC trace data.
• Port 3200 serves the Tempo query API.
• Trace data is stored in mzdata/tempo from the repository root.

Grafana

Grafana is pre-configured with anonymous admin access for local development:

"environment": [
    "GF_AUTH_ANONYMOUS_ENABLED=true",
    "GF_AUTH_ANONYMOUS_ORG_ROLE=Admin",
],

• Anonymous authentication is enabled with full Admin privileges.
• Datasource provisioning is handled by mounting configurations from ./grafana/datasources.

Workflow

The workflow_default function performs the following steps:

1. Creates bind mount directories -- Ensures mzdata/prometheus and mzdata/tempo directories exist before Docker Compose starts, preventing the Docker daemon from creating them as root (which would block environmentd writes).
2. Starts all services -- Calls c.up() to bring up the full monitoring stack.
3. Prints access URLs -- Outputs the URLs for each service with their dynamically resolved ports.

def workflow_default(c: Composition) -> None:
    (MZ_ROOT / "mzdata" / "prometheus").mkdir(parents=True, exist_ok=True)
    (MZ_ROOT / "mzdata" / "tempo").mkdir(parents=True, exist_ok=True)
    c.up()
    print(f"Prometheus running at http://localhost:{c.default_port('prometheus')}")
    print(f"Tempo running at http://localhost:{c.default_port('tempo')}")
    print(f"Grafana running at http://localhost:{c.default_port('grafana')}")

Volume Mounts

Service	Container Path	Host Path	Purpose
Prometheus	/etc/prometheus/prometheus.yml	./prometheus.yml	Configuration file
Prometheus	/mnt/services	../../mzdata/prometheus	Persistent data
Tempo	/etc/tempo.yml	./tempo.yml	Configuration file
Tempo	/tmp/tempo	../../mzdata/tempo	Trace storage
Grafana	/etc/grafana/provisioning/datasources	./grafana/datasources	Datasource provisioning

Key Source Files

File	Path
Monitoring compose workflow	misc/monitoring/mzcompose.py