COCKROACH-DEBUG-ZIP(1)

NAME

cockroach-debug-zip - gather cluster debug data into a zip file

SYNOPSIS

cockroach debug zip [flags]

DESCRIPTION

Gather cluster debug data into a zip file. Data includes cluster events, node liveness, node status, range status, node stack traces, node engine stats, log files, and SQL schema.

Retrieval of per-node details (status, stack traces, range status, engine stats) requires the node to be live and operating properly. Retrieval of SQL data requires the cluster to be live.

OPTIONS

--cert-principal-map=[]

A comma separated list of : mappings. This
 allows mapping the principal in a cert to a DB principal such as "node" or
 "root" or any SQL user. This is intended for use in situations where the
 certificate management system places restrictions on the Subject.CommonName or
 SubjectAlternateName fields in the certificate (e.g. disallowing a CommonName
 such as "node" or "root"). If multiple mappings are provided for the same
 , the last one specified in the list takes precedence. A
 principal not specified in the map is passed through as-is via the identity
 function. A cert is allowed to authenticate a DB principal if the DB principal
 name is contained in the mapped CommonName or DNS-type SubjectAlternateName
 fields. It is permissible for the string to contain colons.

--certs-dir="/home/builder/.cockroach-certs"

Path to the directory containing SSL certificates and keys.
 Environment variable: COCKROACH_CERTS_DIR

--cluster-name=

Sets a name to verify the identity of a remote node or cluster. The value must
 match between this node and the remote node(s) specified via --join.

This can be used as an additional verification when either the node or
 cluster, or both, have not yet been initialized and do not yet know their
 cluster ID.

To introduce a cluster name into an already-initialized cluster, pair this
 flag with --disable-cluster-name-verification.

--concurrency=15

The maximum number of nodes to request data from simultaneously. Can be set to
 1 to ensure only one node is polled for data at a time.

--cpu-profile-duration=5s

Fetch CPU profiles from the cluster with the specified sample duration. The
 zip command will block for the duration specified. Zero disables this feature.

--disable-cluster-name-verification[=false]

Tell the server to ignore cluster name mismatches. This is meant for use when
 opting an existing cluster into starting to use cluster name verification, or
 when changing the cluster name.

The cluster should be restarted once with --cluster-name and
 --disable-cluster-name-verification combined, and once all nodes have been
 updated to know the new cluster name, the cluster can be restarted again with
 this flag removed.

--exclude-files=[]

List of glob patterns that determine files that are to be excluded from the
 output. The list can be specified as a comma-delimited list of patterns, or by
 using the flag multiple times.

Patterns without '/' apply to the base name of the file (e.g. '.log').
 Patterns containing '/' are matched against the full path within the zip
 archive (e.g. 'debug/nodes//ranges.json'). The path matching uses Go's
 filepath.Match syntax, where '*' matches any sequence of non-separator
 characters within a single path component.

This flag is applied after --include-files; for example, including '*.log' and
 then excluding 'foo.log' will exclude 'barfoos.log'.

You can use the 'debug list-files' command to explore how this flag is
 applied.

--exclude-nodes=

List of nodes to exclude. Can be specified as a comma-delimited list of node
 IDs or ranges of node IDs, for example: 5,10-20,23. The default is to not
 exclude any node.

--files-from=2026-05-11 03:45:33

Limit file collection to those files modified after the specified timestamp,
 inclusive. The timestamp can be expressed as YYYY-MM-DD, YYYY-MM-DD HH:MM or
 YYYY-MM-DD HH:MM:SS and is interpreted in the UTC time zone. The default value
 for this flag is 48 hours before now.

When customizing this flag to capture a narrow range of time, consider
 adding extra seconds/minutes to the range to accommodate clock drift and
 uncertainties.

You can use the 'debug list-files' command to explore how this flag is
 applied.

--files-until=2026-05-14 03:45:33

Limit file collection to those files created before the specified timestamp,
 inclusive. The timestamp can be expressed as YYYY-MM-DD, YYYY-MM-DD HH:MM or
 YYYY-MM-DD HH:MM:SS and is interpreted in the UTC time zone. The default value
 for this flag is some time beyond the current time, to ensure files created
 during the collection are also included.

When customizing this flag to capture a narrow range of time, consider
 adding extra seconds/minutes to the range to accommodate clock drift and
 uncertainties.

You can use the 'debug list-files' command to explore how this flag is
 applied.

--format="table"

Selects how to display table rows in results. Possible values: tsv, csv,
 table, records, ndjson, json, sql, html, raw. If left unspecified, defaults to
 tsv for non-interactive sessions and table for interactive sessions.

-h, --help[=false]
    help for zip

--host=localhost:26257

CockroachDB node to connect to. This can be specified either as an
 address/hostname, or together with a port number as in -s myhost:26257. If
 the port number is left unspecified, it defaults to 26257. An IPv6 address
 can also be specified with the notation [...], for example [::1]:26257 or

Environment variable: COCKROACH_HOST

--include-files=[]

List of glob patterns that determine files that can be included in the output.
 The list can be specified as a comma-delimited list of patterns, or by using
 the flag multiple times.

Patterns without '/' apply to the base name of the file (e.g. '.json').
 Patterns containing '/' are matched against the full path within the zip
 archive (e.g. 'debug/nodes/1/.json' or 'debug/nodes//ranges.json'). The path
 matching uses Go's filepath.Match syntax, where '' matches any sequence of
 non-separator characters within a single path component.

The default is to include all files.

This flag is applied before --exclude-files; for example, including '*.log'
 and then excluding 'foo.log' will exclude 'barfoos.log'.

You can use the 'debug list-files' command to explore how this flag is
 applied.

--include-goroutine-stacks[=true]

Fetch full stack traces for all goroutines running on each targeted node
 in nodes//stacks.txt files. Note that fetching text stack traces for all
 goroutines incurs a brief "stop-the-world" pause of each node which can
 momentarily have negative impacts on SQL service latency. This flag only
 controls collection of new full dump of all current goroutine stacks --
 any previously recorded, periodic goroutine dumps retained in the logs
 directories are still included (in nodes//goroutines/*.txt.gz) and collection
 of aggregate counts of current goroutine stacks -- which does not incur a
 stop-the-world pause -- remains enabled regardless of this flag's value.

--include-range-info[=true]

Include one file per node with information about the KV ranges stored on
 that node, in nodes/{node ID}/ranges.json. Additionally, include problem
 ranges information. This information can be vital when debugging issues
 that involve the KV storage layer, such as data placement, load balancing,
 performance or other behaviors. In certain situations, on large clusters with
 large numbers of ranges, these files can be omitted if and only if the issue
 being investigated is already known to be in another layer of the system
 (for example, an error message about an unsupported feature or incompatible
 value in a SQL schema change or statement). Note however many higher-level
 issues are ultimately related to the underlying KV storage layer described by
 these files so only set this to false if directed to do so by Cockroach Labs
 support.

--include-running-job-traces[=true]

Include information about each running, traceable job in jobs///trace.zip
 files. This involves collecting cluster-wide traces for each running job in
 the cluster.

--insecure[=false]

Connect to a cluster without using TLS nor authentication. This makes the
 client-server connection vulnerable to MITM attacks. Use with care.
 Environment variable: COCKROACH_INSECURE

--nodes=

List of nodes to include. Can be specified as a comma-delimited list of node
 IDs or ranges of node IDs, for example: 5,10-20,23. The default is to include
 all nodes.

--redact[=false]

Redact anything that may contain confidential data or PII from retrieved debug
 data. An exception is made for range key data, as this data is necessary to
 support CockroachDB.

--timeout=0s

If nonzero, return with an error if the operation does not conclude within the
 specified timeout. The timeout is specified with a suffix of 's' for seconds,
 'm' for minutes, and 'h' for hours.

--url=

Connection URL, of the form:
    postgresql://[user[:passwd]@]host[:port]/[db][?parameters...]
    postgresql://[user[:passwd]@]host[:port]/cluster:[virtual-cluster]/[db][?parameters...]

For example:
    postgresql://myuser@localhost:26257/mydb
    postgresql://myuser@localhost:26257/cluster:mycluster/mydb

If left empty, the discrete connection flags are used: host, port, user,
 database, insecure, certs-dir.
 Environment variable: COCKROACH_URL

-u, --user="root"

Database user name.
 Environment variable: COCKROACH_USER

--validate-zip-file[=true]

Validate debug zip file after generation. This is a quick check to validate
 whether the generated zip file is valid and not corrupted.

OPTIONS INHERITED FROM PARENT COMMANDS

--enterprise-require-fips-ready[=false]
    abort if FIPS readiness checks fail

--log=

Logging configuration, expressed using YAML syntax. For example, you can
 change the default logging directory with: --log='file-defaults: {dir: ...}'.
 See the documentation for more options and details. To preview how the log
 configuration is applied, or preview the default configuration, you can use
 the 'cockroach debug check-log-config' sub-command.

--log-config-file=

File name to read the logging configuration from. This has the same effect as
 passing the content of the file via the --log flag.

--log-config-vars=[]

Environment variables that will be expanded if present in the body of the
 logging configuration.

--log-dir=

--log-dir=XXX is an alias for --log='file-defaults: {dir: XXX}'.

--logtostderr[=UNKNOWN]

--logtostderr=XXX is an alias for --log='sinks: {stderr: {filter: XXX}}'. If
 no value is specified, the default value for the command is inferred: INFO for
 server commands, WARNING for client commands.

--redactable-logs=false

--redactable-logs=XXX is an alias for --log='file-defaults: {redactable:
 XXX}}'.

--vmodule=
    comma-separated list of pattern=N settings for file-filtered logging (significantly hurts performance)

SEE ALSO

cockroach-debug(1)

HISTORY

13-May-2026 Auto generated by spf13/cobra