Home  /  Tools and integrations  /  mz-debug

mz-debug emulator

mz-debug emulator debugs Docker-based Materialize deployments. It collects:

  • Docker logs and resource information.
  • Snapshots of system catalog tables from your Materialize instance.

Requirements

  • Docker installed and running. If Docker is not installed, refer to its official documentation to install
  • A valid Materialize SQL connection URL for your local emulator.

Syntax

mz-debug emulator [OPTIONS]

Options

mz-debug emulator options

Option Description
--docker-container-id <ID>

The Docker container to dump.

Required.
--dump-docker <boolean>

If true, dump debug information from the Docker container.

Defaults to true.

mz-debug global options

Option Description
--dump-heap-profiles <boolean>

If true, dump heap profiles (.pprof.gz) from your Materialize instance.

Defaults to true.
--dump-prometheus-metrics <boolean>

If true, dump prometheus metrics from your Materialize instance.

Defaults to true.
--dump-system-catalog <boolean>

If true, dump the system catalog from your Materialize instance.

Defaults to true.
--mz-connection-url <URL>

The Materialize instance’s PostgreSQL connection URL.

Defaults to postgres://127.0.0.1:6875/materialize?sslmode=prefer.

Output

The mz-debug outputs its log file (tracing.log) and the generated debug files into a directory named mz_debug_YYYY-MM-DD-HH-TMM-SSZ/ as well as zips the directory and its contents mz_debug_YYYY-MM-DD-HH-TMM-SSZ.zip.

The generated debug files are in two main categories: Docker resource files and system catalog files.

Docker resource files

In mz_debug_YYYY-MM-DD-HH-TMM-SSZ/, under the docker/<CONTAINER-ID> sub-directory, the following Docker resource debug files are generated:

Resource Type Files
Container Logs
  • logs-stdout.txt
  • logs-stderr.txt
Container Inspection
  • inspect.txt
Container Stats
  • stats.txt
Container Processes
  • top.txt

System catalog files

mz-debug outputs system catalog files if --dump-system-catalog is true (the default).

The generated files are in system-catalog sub-directory as *.csv files and contains:

  • Core catalog object definitions
  • Cluster and compute-related information
  • Data freshness and frontier metric
  • Source and sink metrics
  • Per-replica introspection metrics (under {cluster_name}/{replica_name}/*.csv)

For more information about each relation, view the system catalog.

Prometheus metrics

mz-debug outputs snapshots of prometheus metrics per service (i.e. environmentd) if --dump-prometheus-metrics is true (the default). Each file is stored under prom_metrics/{service}.txt.

Memory profiles

By default, mz-debug outputs heap profiles for each service in profiles/{service}.memprof.pprof.gz. To turn off this behavior, you can set --dump-heap-profiles to false.

Example

Debug a running local emulator container

mz-debug emulator \
    --docker-container-id 123abc456def
Back to top ↑