cockroach debug tsdump

On this page

The cockroach debug tsdump command connects to your cluster and collects timeseries diagnostic data from each active node (inactive nodes are not included). This includes both current and historical runtime metrics for your cluster, including those exposed in the DB Console Metrics pages as well as internal metrics.

cockroach debug tsdump is mostly used in tandem with the cockroach debug zip command to gather diagnostic data during escalations to Cockroach Labs support. Follow the steps in this procedure to gather and prepare the timeseries diagnostic data and prepare it for transit to Cockroach Labs.

Subcommands

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

We recommend using the encryption-decrypt and job-trace subcommands only when directed by the Cockroach Labs support team.

The other debug subcommands are useful only to Cockroach Labs. Output of debug commands may contain sensitive or secret information.

Synopsis

$ cockroach debug tsdump {flags} > {dump file destination} 

Flags

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

General

Available resolutions

A debug tsdump includes all the available resolutions (10s and 30m) of the raw time series values in the time range set using the --from and --to flags:

• Time series values will be dumped with a 10 seconds resolution if the supplied time range is within the 10s TTL set by the timeseries.storage.resolution_10s.ttl cluster setting (default: 10 days).
• Time series values will be dumped with a 30 minutes resolution if the supplied time range is older than the 10s TTL back to the 30m TTL set by the timeseries.storage.resolution_30m.ttl cluster setting (default: 90 days).

For example, if today was 2024-11-15 and --to was set to the current timestamp (2024-11-15), and --from was set to 15 days before the current timestamp (2024-11-01), the debug tsdump would include:

• Time series values with a 10 seconds resolution for 2024-11-05 to 2024-11-15 (within the 10s TTL of 10 days).
• Time series values with a 30 minutes resolution for 2024-11-01 to 2024-11-04 (outside the 10s TTL of 10 days, but within the 30s TTL of 90 days).

Client connection

Logging

By default, this command logs messages to stdout. If you need to troubleshoot this command's behavior, you can customize its logging behavior.

Examples

Generate a tsdump gob file

Generate the tsdump gob file for an insecure CockroachDB cluster:

$ cockroach debug tsdump --format=raw --insecure > tsdump.gob

Generate the tsdump gob file for a secure CockroachDB cluster:

$ cockroach debug tsdump --format=raw --certs-dir=${HOME}/.cockroach-certs/ > tsdump.gob

Generate a tsdump gob file and compress using gzip

Generate a tsdump gob file for an insecure CockroachDB cluster, and compress using gzip in preparation to send to Cockroach Labs for troubleshooting. Your server must have gzip installed:

$ cockroach debug tsdump --format=raw --insecure > tsdump.gob
gzip tsdump.gob

Generate a tsdump gob file for a secure CockroachDB cluster, and compress using gzip in preparation to send to Cockroach Labs for troubleshooting. Your server must have gzip installed:

$ cockroach debug tsdump --format=raw --certs-dir=${HOME}/.cockroach-certs/ > tsdump.gob
gzip tsdump.gob

Generate a tsdump gob file with a custom timestamp range

Generate a tsdump gob file specifying a custom timestamp range to limit the data collection to a specific interval. This is useful for reducing the size of the resulting gob file if the data needed to troubleshoot falls within a known timestamp range:

$ cockroach debug tsdump --format=raw --from='2023-01-10 01:00:00' --to='2023-01-20 23:59:59' > tsdump.gob

Generate a tsdump with only essential and support metrics

Use the --non-verbose flag to dump only metrics tagged as ESSENTIAL and SUPPORT. This option is ideal for:

• Standard support escalations
• Routine health checks
• Cases where you want to minimize file size and collection time

$ cockroach debug tsdump --format=raw --non-verbose --insecure > tsdump.gob

For a secure cluster:

$ cockroach debug tsdump --format=raw --non-verbose --certs-dir=${HOME}/.cockroach-certs/ > tsdump.gob

Generate a tsdump with specific metrics

Use the --metrics-list-file flag to dump only specific metrics by providing a file with metric names or regex patterns for flexible metric matching. This option is ideal for:

• Scenario-specific investigations (e.g., contention, latency, replication issues)
• Following runbooks for particular classes of issues
• Investigating new or experimental metrics that aren't yet tagged as ESSENTIAL or SUPPORT.

First, create a text file with the metrics you want to dump. You can specify exact metric names or use regex patterns. Only metrics whose names match the patterns defined in the file are included in the output. Comments (lines starting with #) and blank lines are ignored:

$ cat > metrics.txt <<EOF
# Example metrics list for investigating changefeed and transaction issues
changefeed.commit_latency
sql.txn.aborts

# Match all logical_replication metrics
logical_replication\..*

# Match all metrics containing "capacity"
.*capacity.*

# Match all sql metrics
sql.*
EOF

Then generate the tsdump with only the specified metrics:

$ cockroach debug tsdump --format=raw --metrics-list-file=metrics.txt --insecure > tsdump.gob

For a secure cluster:

$ cockroach debug tsdump --format=raw --metrics-list-file=metrics.txt --certs-dir=${HOME}/.cockroach-certs/ > tsdump.gob

See also

• File an Issue
• cockroach Commands Overview
• Troubleshooting Overview