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

Option	Description
`--dump-docker <boolean>`	If `true`, dump debug information from the Docker container. Defaults to `true`.
`--docker-container-id <ID>`	The Docker container to dump. Required if `--dump-docker` is true.
`--mz-connection-url <URL>`	The URL of the Materialize’s SQL connection. Defaults to `postgres://127.0.0.1:6875/materialize?sslmode=prefer`.

--dump-docker <boolean>

If true, dump debug information from the Docker container.

Defaults to true.

--docker-container-id <ID>

The Docker container to dump.

Required if --dump-docker is true.

--mz-connection-url <URL>

The URL of the Materialize’s SQL connection.

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

`mz-debug` global options

Option Description

Option	Description
`--dump-system-catalog <boolean>`	If `true`, dump the system catalog from your Materialize instance. Defaults to `true`.

--dump-system-catalog <boolean>

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

Defaults to true.

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.

Example

Debug a running local emulator container

mz-debug emulator \
    --docker-container-id 123abc456def