Materialize Documentation
Join the Community github/materialize

Monitor Cloud

Materialize Cloud is in beta and is not subject to Materialize's backwards compatibility guarantee.

We want to make it possible for you to monitor Materialize Cloud with the same tools you use for the rest of your pipeline. Currently Materialize Cloud only supports Prometheus, but we are working on a Datadog integration. If there are any other tools you’re interested in, please let us know.

We also provide some internal tools that can be helpful for monitoring or debugging:

Connect to Materialize Cloud

No matter which tool you use, you first need to download and unzip the TLS certificates in a location where they can be accessed by your monitoring tool, and then connect to Materialize Cloud.

  1. Click on a deployment to see the individual deployment view.

  2. If you are connecting through Tailscale VPN, go to the Integrations card, then the Tailscale tab. Click Enable, then enter the Tailscale auth key in the Tailscale Authentication dialog and click Save. The deployment will automatically restart.

    Tailscale integration must enabled separately for each deployment.

    For help generating an auth key, please see the Tailscale documentation. Make sure you create a one-off key.

  3. In the Connect card, go to the psql tab and click Download certificates.

  4. Unzip the certificate package.

    The certificate package is named <deployment-name>.zip and contains the TLS certificates and keys you need to connect.

  5. To connect to the deployment, you can use any Materialize-compatible CLI, like psql. If you have psql installed on your machine, proceed to the next step.

    Otherwise, follow the installation instructions.

  6. Open a terminal window on your machine, copy the psql command from the connection dialog and run it from the directory that contains the certificates.

    If you’re connecting through Tailscale, replace the hostname in the copied command with the address of your Materialize connection in Tailscale.

    On connection success, you should see an open prompt waiting for your next commands:

    psql (13.2, server 9.5.0)
    SSL connection (protocol: TLSv1.3, cipher:
    TLS_AES_256_GCM_SHA384, bits: 256, compression: off)
    Type "help" for help.


Set up Prometheus

Next, you need to add Materialize to the configuration file for your Prometheus installation.

Add the following configuration to prometheus.yml:

  - job_name: materialized
  - tls: config:
    - ca_file: ca.crt
    - cert_file: materialize.crt
    - key_file: materialize.key
    -  targets:
      - <deployment_hostname>:6875

You can find the hostname listed next to the deployment name on your Deployments page. You can also copy the complete configuration update already customized for your deployment by clicking on the deployment, going to the Prometheus tab, and clicking the copy icon in the code box.

View Prometheus metrics

Materialize exposes Prometheus metrics at the default path, <materialized host>/metrics.

Materialize broadly publishes the following types of data there:


Materialize provides a recommended dashboard that you can import into Grafana. It relies on you having configured Prometheus to scrape Materialize.

System catalog SQL interface

The mz_catalog SQL interface provides a variety of ways to introspect Materialize. An introduction to this catalog is available as part of our SQL documentation.

A user guide for debugging a running materialized using the system catalog is available in the form of a walkthrough of useful diagnostic queries.

Did this info help?
Yes No