Consul Debug
Command: consul debug
The consul debug command monitors a Consul agent for the specified period of
time, recording information about the agent, cluster membership, and environment to an archive
written to the current directory.
Providing support for complex issues encountered by Consul operators often requires a large amount of debugging information to be retrieved. This command aims to shortcut that coordination and provide a simple workflow for accessing data about Consul agent, cluster membership, and environment to enable faster isolation and debugging of issues.
This command requires an operator:read ACL token in order to retrieve the
data from the target agent, if ACLs are enabled.
If the command is interrupted, as it could be given a long duration but require less time than expected, it will attempt to archive the current captured data.
Security and Privacy
By default, ACL tokens, private keys, and other sensitive material related to Consul is sanitized and not available in this archive. However, other information about the environment the target agent is running in is available in plain text within the archive.
It is recommended to validate the contents of the archive and redact any
material classified as sensitive to the target environment, or use the -capture
flag to not retrieve it initially.
Additionally, we recommend securely transmitting this archive via encryption or otherwise.
Usage
Usage: consul debug [options]
By default, the debug command will capture an archive at the current path for all targets for 5 minutes.
Command Options
-duration- Optional, the total time to capture data for from the target agent. Must be greater than the interval and longer than 10 seconds. Defaults to 5 minutes.-interval- Optional, the interval at which to capture dynamic data, such as heap and metrics. Must be longer than 5 seconds. Defaults to 30 seconds.-capture- Optional, can be specified multiple times for each capture target and will only record that information in the archive.-output- Optional, the full path of where to write the directory of data and resulting archive. Defaults to the current directory.-archive- Optional, if the tool show archive the directory of data into a compressed tar file. Defaults to true.-since- Optional, can be used to capture information since a particular time in the past
API Options
-ca-file=<value>- Path to a CA file to use for TLS when communicating with Consul. This can also be specified via theCONSUL_CACERTenvironment variable.-ca-path=<value>- Path to a directory of CA certificates to use for TLS when communicating with Consul. This can also be specified via theCONSUL_CAPATHenvironment variable.-client-cert=<value>- Path to a client cert file to use for TLS whenverify_incomingis enabled. This can also be specified via theCONSUL_CLIENT_CERTenvironment variable.-client-key=<value>- Path to a client key file to use for TLS whenverify_incomingis enabled. This can also be specified via theCONSUL_CLIENT_KEYenvironment variable.-http-addr=<addr>- Address of the Consul agent with the port. This can be an IP address or DNS address, but it must include the port. This can also be specified via theCONSUL_HTTP_ADDRenvironment variable. In Consul 0.8 and later, the default value is http://127.0.0.1:8500, and https can optionally be used instead. The scheme can also be set to HTTPS by setting the environment variableCONSUL_HTTP_SSL=true. This may be a unix domain socket usingunix:///path/to/socketif the agent is configured to listen that way.-tls-server-name=<value>- The server name to use as the SNI host when connecting via TLS. This can also be specified via theCONSUL_TLS_SERVER_NAMEenvironment variable.-token=<value>- ACL token to use in the request. This can also be specified via theCONSUL_HTTP_TOKENenvironment variable. If unspecified, the query will default to the token of the Consul agent at the HTTP address.-token-file=<value>- File containing the ACL token to use in the request instead of one specified via the-tokenargument orCONSUL_HTTP_TOKENenvironment variable. This can also be specified via theCONSUL_HTTP_TOKEN_FILEenvironment variable.
Capture Targets
The -capture flag can be specified multiple times to capture specific
information when debug is running. By default, it captures all information.
| Target | Description |
|---|---|
agent | Version and configuration information about the agent. |
host | Information about resources on the host running the target agent such as CPU, memory, and disk. |
members | A list of all the WAN and LAN members in the cluster. |
metrics | Metrics from the in-memory metrics endpoint in the target, captured at the interval. |
logs | TRACE level logs for the target agent, captured for the duration. |
pprof | Golang heap, CPU, goroutine, and trace profiling. CPU and traces are captured for duration in a single file while heap and goroutine are separate snapshots for each interval. This information is not retrieved unless enable_debug is set to true on the target agent or ACLs are enabled and an ACL token with operator:read is provided. |
Examples
This command can be run from any host with the Consul binary, but requires network access to the target agent in order to retrieve data. Once retrieved, the data is written to the specified path (defaulting to the current directory) on the host where the command runs.
By default the command will capture all available data from the default agent address on loopback for 2 minutes at 30 second intervals.
In this example, the archive is collected from a different agent on the network using the standard Consul CLI flag to change the API address.
The capture flag can be specified to only record a subset of data about the agent and environment.
The duration of the command and interval of capturing dynamic
information (such as metrics) can be specified with the -interval
and -duration flags.
To capture information since a particular time in past -since flag
can be used.