cockroach debug zip

On this page

The cockroach debug zip command connects to your cluster and gathers information from each active node into a single file (inactive nodes are not included):

• Log files
• Secondary log files (e.g., RocksDB logs, execution logs, slow query logs)
• Cluster events
• Schema change events
• Node liveness
• Gossip data
• Stack traces
• Range lists
• A list of databases and tables
• Jobs
• Cluster Settings
• Metrics
• Alerts
• Heap profiles
• Problem ranges
• Sessions
• Queries
• Thread stack traces (Linux only)
• CPU profiles

Additionally, you can run the debug merge-logs command to merge the collected logs in one file, making it easier to parse them to locate an issue with your cluster.

Details

Use cases

There are two scenarios in which debug zip is useful:

• To collect all of your nodes' logs, which you can then parse to locate issues. It's important to note, though, that debug zip can only access logs from active nodes. For more information, see Collecting log files below.

• If you experience severe or difficult-to-reproduce issues with your cluster, Cockroach Labs might ask you to send us your cluster's debugging information using cockroach debug zip.

Collecting log files

When you issue the debug zip command, the node that receives the request connects to each other node in the cluster. Once it's connected, the node requests the content of all log files stored on the node, the location of which is determined by the --log-dir value when you started the node.

Because debug zip relies on CockroachDB's distributed architecture, this means that nodes not currently connected to the cluster cannot respond to the request, so their log files are not included. In such situations, we recommend using the --host flag to point debug zip at individual nodes until data has been gathered for the entire cluster.

After receiving the log files from all of the active nodes, the requesting node aggregates the files and writes them to an archive file you specify.

You can locate logs in the unarchived file's debug/nodes/[node dir]/logs directories.

Subcommands

While the cockroach debug command has a few subcommands, users are expected to use only the zip, encryption-active-key, merge-logs, and ballast subcommands.

The other debug subcommands are useful only to CockroachDB's developers and contributors.

Synopsis

$ cockroach debug zip [ZIP file destination] [flags]

It's important to understand that the [flags] here are used to connect to CockroachDB nodes. This means the values you use in those flags must connect to an active node. If no nodes are live, you must start at least one node.

Flags

The debug zip subcommand supports the following general-use, client connection, and logging flags.

General

Client connection

Logging

By default, the debug zip command logs errors it experiences to stderr. Note that these are errors executing debug zip; these are not errors that the logs collected by debug zip contain.

If you need to troubleshoot this command's behavior, you can also change its logging behavior.

Examples

Generate a debug zip file

# Generate the debug zip file for an insecure cluster:
$ cockroach debug zip ./cockroach-data/logs/debug.zip --insecure --host=200.100.50.25

# Generate the debug zip file for a secure cluster:
$ cockroach debug zip ./cockroach-data/logs/debug.zip --host=200.100.50.25

See also

• File an Issue
• Other Cockroach Commands
• Troubleshooting Overview

Was this helpful?