> ## 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](https://docs.cockroachlabs.com/docs/v24.2/support-resources).

The [`cockroach debug job-trace`](https://docs.cockroachlabs.com/docs/v24.2/cockroach-commands) command connects to your cluster and collects trace payloads for a running, traceable [job](https://docs.cockroachlabs.com/docs/v24.2/show-jobs#show-jobs) ([**imports**](https://docs.cockroachlabs.com/docs/v24.2/import-into) or [**backups**](https://docs.cockroachlabs.com/docs/v24.2/take-full-and-incremental-backups)). 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`](https://docs.cockroachlabs.com/docs/v24.2/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](https://docs.cockroachlabs.com/docs/v24.2/show-trace#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`](https://docs.cockroachlabs.com/docs/v24.2/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`](https://docs.cockroachlabs.com/docs/v24.2/cockroach-debug-zip), [`encryption-active-key`](https://docs.cockroachlabs.com/docs/v24.2/cockroach-debug-encryption-active-key), [`merge-logs`](https://docs.cockroachlabs.com/docs/v24.2/cockroach-debug-merge-logs), [`list-files`](https://docs.cockroachlabs.com/docs/v24.2/cockroach-debug-list-files), [`tsdump`](https://docs.cockroachlabs.com/docs/v24.2/cockroach-debug-tsdump), and [`ballast`](https://docs.cockroachlabs.com/docs/v24.2/cockroach-debug-ballast) subcommands.

We recommend using the [`encryption-decrypt`](https://docs.cockroachlabs.com/docs/v24.2/cockroach-debug-encryption-decrypt) and [`job-trace`](https://docs.cockroachlabs.com/docs/v24.2/cockroach-debug-job-trace) subcommands only when directed by the [Cockroach Labs support team](https://docs.cockroachlabs.com/docs/v24.2/support-resources).

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](https://docs.cockroachlabs.com/docs/v24.2/create-user) 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](https://docs.cockroachlabs.com/docs/v24.2/cockroach-cert) containing the CA and client certificates and client key. **Env Variable:** `COCKROACH_CERTS_DIR` **Default:** `${HOME}/.cockroach-certs/` |
|  `--url` | A [connection URL](https://docs.cockroachlabs.com/docs/v24.2/connection-parameters#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`](https://docs.cockroachlabs.com/docs/v24.2/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](https://docs.cockroachlabs.com/docs/v24.2/cockroach-start#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](https://docs.cockroachlabs.com/docs/v24.2/support-resources)
* [`cockroach` Commands Overview](https://docs.cockroachlabs.com/docs/v24.2/cockroach-commands)
* [Troubleshooting Overview](https://docs.cockroachlabs.com/docs/v24.2/troubleshooting-overview)
* [Support Resources](https://docs.cockroachlabs.com/docs/v24.2/support-resources)