Skip to content

Latest commit

 

History

History
76 lines (51 loc) · 4.64 KB

cockroach-debug-job-trace.md

File metadata and controls

76 lines (51 loc) · 4.64 KB
title summary toc docs_area
cockroach debug job-trace
Learn the commands for collecting debug information from all nodes in your cluster.
true
reference.cli

{{site.data.alerts.callout_danger}} We strongly recommend only using cockroach debug job-trace when working directly with the Cockroach Labs support team. {{site.data.alerts.end}}

The cockroach debug job-trace command connects to your cluster and collects trace payloads for a running, traceable job (imports or 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 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 for all the nodes participating in the execution of the job. The files hold information on the executing job's trace spans, 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

$ cockroach debug job-trace <job_id> --url=<connection string> {flags}

See SHOW JOBS for details on capturing a job_id.

Subcommands

{% include {{ page.version.version }}/misc/debug-subcommands.md %}

Flags

The debug job-trace subcommand supports the following general-use and 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 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 containing the CA and client certificates and client key.

Env Variable: COCKROACH_CERTS_DIR
Default: ${HOME}/.cockroach-certs/
--url A connection 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 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 to pull the trace spans:

{% include_cached copy-clipboard.html %}

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