> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# cockroach debug tsdump

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

The `cockroach debug tsdump` <InternalLink path="cockroach-commands">command</InternalLink> 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 <InternalLink path="ui-overview-dashboard">DB Console Metrics</InternalLink> pages as well as internal metrics.

`cockroach debug tsdump` is mostly used in tandem with the <InternalLink path="cockroach-debug-zip">`cockroach debug zip`</InternalLink> 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 <InternalLink path="cockroach-debug-zip">`zip`</InternalLink>, <InternalLink path="cockroach-debug-encryption-active-key">`encryption-active-key`</InternalLink>, <InternalLink path="cockroach-debug-merge-logs">`merge-logs`</InternalLink>, <InternalLink path="cockroach-debug-list-files">`list-files`</InternalLink>, <InternalLink path="cockroach-debug-tsdump">`tsdump`</InternalLink>, and <InternalLink path="cockroach-debug-ballast">`ballast`</InternalLink> subcommands.

We recommend using the <InternalLink path="cockroach-debug-encryption-decrypt">`encryption-decrypt`</InternalLink> and <InternalLink path="cockroach-debug-job-trace">`job-trace`</InternalLink> subcommands only when directed by the <InternalLink path="support-resources">Cockroach Labs support team</InternalLink>.

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

## Synopsis

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach debug tsdump {flags} > {dump file destination}
```

<Note>
  The following [flags](#flags) must apply to an active CockroachDB node. If no nodes are live, you must <InternalLink path="cockroach-start">start at least one node</InternalLink>.
</Note>

## Flags

The `debug tsdump` subcommand supports the following [general-use](#general), [client connection](#client-connection), and [logging](#logging) flags.

### General

| Flag       | Description                                                                                                                         |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `--format` | The output format to write the collected diagnostic data. Valid options are `text`, `csv`, `tsv`, `raw`.  **Default:**`text`        |
| `--from`   | The oldest timestamp to include (inclusive), in the format `YYYY-MM-DD [HH:MM[:SS]]`.  **Default:**`0001-01-01 00:00:00`            |
| `--to`     | The newest timestamp to include (inclusive), in the format `YYYY-MM-DD [HH:MM[:SS]]`.  **Default:** Current timestamp plus 29 hours |

### Client connection

| Flag                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--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` like `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. |
| `--certs-dir`                         | The path to the <InternalLink path="cockroach-cert">certificate directory</InternalLink> containing the CA and client certificates and client key.  **Env Variable:**`COCKROACH\_CERTS\_DIR` **Default:**`${HOME}/.cockroach-certs/`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `--cluster-name`                      | The cluster name to use to verify the cluster's identity. If the cluster has a cluster name, you must include this flag. For more information, see <InternalLink path="cockroach-start#general">`cockroach start`</InternalLink>.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `--disable-cluster-name-verification` | Disables the cluster name check for this command. This flag must be paired with `--cluster-name`. For more information, see <InternalLink path="cockroach-start#general">`cockroach start`</InternalLink>.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `--host`                              | The server host and port number to connect to. This can be the address of any node in the cluster.  **Env Variable:**`COCKROACH\_HOST` **Default:**`localhost:26257`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `--insecure`                          | Use an insecure connection.  **Env Variable:**`COCKROACH\_INSECURE` **Default:**`false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `--url`                               | A <InternalLink path="connection-parameters#connect-using-a-url">connection URL</InternalLink> to use instead of the other arguments. To convert a connection URL to the syntax that works with your client driver, run <InternalLink path="connection-parameters#convert-a-url-for-different-drivers">`cockroach convert-url`</InternalLink>.  **Env Variable:**`COCKROACH\_URL` **Default:** no URL                                                                                                                                                                                                                                                                                                                                                       |

### Logging

By default, this command logs messages to `stdout`. If you need to troubleshoot this command's behavior, you can <InternalLink path="configure-logs">customize its logging behavior</InternalLink>.

## Examples

### Generate a tsdump `gob` file

Generate the tsdump `gob` file for an insecure CockroachDB cluster:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach debug tsdump --format=raw --insecure > tsdump.gob
```

Generate the tsdump `gob` file for a secure CockroachDB cluster:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach debug tsdump --format=raw --certs-dir=${HOME}/.cockroach-certs/ > tsdump.gob
```

<Note>
  Secure examples assume you have the appropriate certificates in the default certificate directory, `${HOME}/.cockroach-certs/`. See the <InternalLink path="cockroach-cert">`cockroach cert`</InternalLink> documentation for more information.
</Note>

### 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:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ 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:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach debug tsdump --format=raw --certs-dir=${HOME}/.cockroach-certs/ > tsdump.gob
gzip tsdump.gob
```

Secure examples assume you have the appropriate certificates in the default certificate directory, `${HOME}/.cockroach-certs/`. See the <InternalLink path="cockroach-cert">`cockroach cert`</InternalLink> documentation for more information.

### 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:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach debug tsdump --format=raw --from='2023-01-10 01:00:00' --to='2023-01-20 23:59:59' > tsdump.gob
```

## See also

* <InternalLink path="support-resources">Support Resources</InternalLink>
* <InternalLink path="cockroach-commands">`cockroach` Commands Overview</InternalLink>
* <InternalLink path="troubleshooting-overview">Troubleshooting Overview</InternalLink>