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

# cockroach debug job-trace

> [!CAUTION]
>
> We strongly recommend only using `cockroach debug job-trace` when working directly with the [Cockroach Labs support team](/docs/stable/support-resources.md).

The [`cockroach debug job-trace`](/docs/stable/cockroach-commands) command connects to your cluster and collects trace payloads for a running, traceable [job](/docs/stable/show-jobs.md#show-jobs) ([**imports**](/docs/stable/import-into.md) or [**backups**](/docs/stable/take-full-and-incremental-backups.md)). 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 [`cockroach debug zip`](/docs/stable/cockroach-debug-zip) 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 [trace spans](/docs/stable/show-trace.md#trace-description), 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 [`SHOW JOBS`](/docs/stable/show-jobs#show-jobs) for details on capturing a `job_id`.

## Subcommands

While the `cockroach debug` command has a few subcommands, users are expected to use only the [`zip`](/docs/stable/cockroach-debug-zip), [`upload`](/docs/stable/cockroach-debug-upload), [`encryption-active-key`](/docs/stable/cockroach-debug-encryption-active-key), [`merge-logs`](/docs/stable/cockroach-debug-merge-logs), [`list-files`](/docs/stable/cockroach-debug-list-files), [`tsdump`](/docs/stable/cockroach-debug-tsdump), and [`ballast`](/docs/stable/cockroach-debug-ballast) subcommands.

We recommend using the [`encryption-decrypt`](/docs/stable/cockroach-debug-encryption-decrypt) and [`job-trace`](/docs/stable/cockroach-debug-job-trace) subcommands only when directed by the [Cockroach Labs support team](/docs/stable/support-resources.md).

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 [SQL user](/docs/stable/create-user.md) 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 `<cert-principal:<db-principal` 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 `<cert-principal`, 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 [certificate directory](/docs/stable/cockroach-cert.md) containing the CA and client certificates and client key. **Env Variable:** `COCKROACH_CERTS_DIR` **Default:** `${HOME}/.cockroach-certs/` |
|  `--url` | A [connection URL](/docs/stable/connection-parameters.md#connect-using-a-url) 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 [`SHOW TRACE FOR SESSION`](/docs/stable/show-trace#response) page for more information on trace responses.

## Example

### Generate a job-trace zip file

To generate the `job-trace` zip file, use your [connection string](/docs/stable/cockroach-start.md#standard-output) 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:

```
698977774875279361-job-trace.zip
```

## See also

* [Support Resources](/docs/stable/support-resources.md)
* [`cockroach` Commands Overview](/docs/stable/cockroach-commands)
* [Troubleshooting Overview](/docs/stable/troubleshooting-overview.md)
* [Support Resources](/docs/stable/support-resources.md)