> ## 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 job-trace

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>;
};

<Danger>
  We strongly recommend only using `cockroach debug job-trace` when working directly with the <InternalLink path="support-resources">Cockroach Labs support team</InternalLink>.
</Danger>

The <InternalLink path="cockroach-commands">`cockroach debug job-trace`</InternalLink> command connects to your cluster and collects trace payloads for a running, traceable <InternalLink path="show-jobs#show-jobs">job</InternalLink> (<InternalLink path="import-into">**imports**</InternalLink> or <InternalLink path="take-full-and-incremental-backups">**backups**</InternalLink>). The trace payloads are helpful for debugging why a job is not running as expected or to add more context to logs gathered from the <InternalLink path="cockroach-debug-zip">`cockroach debug zip`</InternalLink> command.

The node that `cockroach debug job-trace` is run against will communicate to all nodes in the cluster in order to retrieve the trace payloads. This will deliver a zip file that contains [trace files](#files) for all the nodes participating in the execution of the job. The files hold information on the executing job's <InternalLink path="show-trace#trace-description">trace spans</InternalLink>, which describe the sub-operations being performed. Specifically, these files will contain the spans that have not yet completed and are associated with the execution of that particular job. Using this command for a job that is not currently running will result in an empty zip file.

## Synopsis

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach debug job-trace <job_id> --url=<connection string {flags}
```

See <InternalLink path="show-jobs#show-jobs">`SHOW JOBS`</InternalLink> for details on capturing a `job_id`.

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

## Flags

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

### General

| Flag        | Description                                                                                                                                                                                |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--timeout` | Return an error if the command does not conclude within a specified nonzero value. The timeout is suffixed with `s` (seconds), `m` (minutes), or `h` (hours). For example:  `--timeout=2m` |

### Client connection

| Flag                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--user`  `-u`         | The <InternalLink path="create-user">SQL user</InternalLink> that will own the client session.  **Env Variable:**`COCKROACH\_USER` **Default:**`root`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--insecure`           | Use an insecure connection.  **Env Variable:**`COCKROACH\_INSECURE` **Default:**`false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `--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/`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `--url`                | A <InternalLink path="connection-parameters#connect-using-a-url">connection URL</InternalLink> to use instead of the other arguments.  **Env Variable:**`COCKROACH\_URL` **Default:** no URL                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

## Files

The `cockroach debug job-trace` command will output a zip file to where the command is run (`<job_id-job-trace.zip`). The zip file will contain trace files for all the nodes participating in the job's execution. For example, `node1-trace.txt`.

See the <InternalLink path="show-trace#response">`SHOW TRACE FOR SESSION`</InternalLink> page for more information on trace responses.

## Example

### Generate a job-trace zip file

To generate the `job-trace` zip file, use your <InternalLink path="cockroach-start#standard-output">connection string</InternalLink> to pull the trace spans:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
cockroach debug job-trace 698977774875279361 --url=postgresql://root@localhost:26257?sslmode=disable
```

You will find the zip file in the directory you ran the command from:

```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
698977774875279361-job-trace.zip
```

## See also

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