2018-10-17 20:20:35 +00:00
---
2020-09-01 15:14:13 +00:00
layout: commands
2020-04-07 18:55:19 +00:00
page_title: 'Commands: Debug'
2023-01-26 18:42:13 +00:00
description: >-
The `consul debug` command monitors an agent to capture a record its actions according to defined durations and intervals.
2018-10-17 20:20:35 +00:00
---
# Consul Debug
Command: `consul debug`
The `consul debug` command monitors a Consul agent for the specified period of
2021-08-18 16:17:20 +00:00
time, recording information about the agent, cluster membership, and environment to an archive
2018-10-17 20:20:35 +00:00
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
2021-08-18 16:17:20 +00:00
data about Consul agent, cluster membership, and environment to enable faster
2018-10-17 20:20:35 +00:00
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
2023-06-13 05:37:46 +00:00
all targets for 5 minutes.
2018-10-17 20:20:35 +00:00
#### Command Options
2020-04-07 18:55:19 +00:00
- `-duration` - Optional, the total time to capture data for from the target agent. Must
2023-06-13 05:37:46 +00:00
be greater than the interval and longer than 10 seconds. Defaults to 5 minutes.
2018-10-17 20:20:35 +00:00
2021-06-07 17:00:51 +00:00
- `-interval` - Optional, the interval at which to capture dynamic data, such as heap
2018-10-17 20:20:35 +00:00
and metrics. Must be longer than 5 seconds. Defaults to 30 seconds.
2020-04-07 18:55:19 +00:00
- `-capture` - Optional, can be specified multiple times for each [capture target](#capture-targets)
2018-10-17 20:20:35 +00:00
and will only record that information in the archive.
2020-04-07 18:55:19 +00:00
- `-output` - Optional, the full path of where to write the directory of data and
2018-10-17 20:20:35 +00:00
resulting archive. Defaults to the current directory.
2020-04-07 18:55:19 +00:00
- `-archive` - Optional, if the tool show archive the directory of data into a
2018-10-17 20:20:35 +00:00
compressed tar file. Defaults to true.
2022-07-27 06:17:11 +00:00
#### API Options
@include 'http_api_options_client.mdx'
2018-10-17 20:20:35 +00:00
## Capture Targets
The `-capture` flag can be specified multiple times to capture specific
information when `debug` is running. By default, it captures all information.
2021-06-07 17:00:51 +00:00
| 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. |
2021-08-18 16:17:20 +00:00
| `members` | A list of all the WAN and LAN members in the cluster. |
2021-06-07 17:00:51 +00:00
| `metrics` | Metrics from the in-memory metrics endpoint in the target, captured at the interval. |
2023-06-13 05:37:46 +00:00
| `logs` | `TRACE` level logs for the target agent, captured for the duration. |
2023-06-27 02:19:07 +00:00
| `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`](/consul/docs/agent/config/config-files#enable_debug) is set to `true` on the target agent or ACLs are enabled and an ACL token with `operator:read` is provided. |
2018-10-17 20:20:35 +00:00
## 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 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.
2020-05-19 18:32:38 +00:00
```shell-session
2018-10-17 20:20:35 +00:00
$ consul debug
...
```
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.
2020-05-19 18:32:38 +00:00
```shell-session
2018-10-17 20:20:35 +00:00
$ consul debug -http-addr=10.0.1.10:8500
...
```
The capture flag can be specified to only record a subset of data
about the agent and environment.
2020-05-19 18:32:38 +00:00
```shell-session
2018-10-17 20:20:35 +00:00
$ consul debug -capture agent -capture host -capture logs
...
```
The duration of the command and interval of capturing dynamic
information (such as metrics) can be specified with the `-interval`
and `-duration` flags.
2020-05-19 18:32:38 +00:00
```shell-session
2018-10-17 20:20:35 +00:00
$ consul debug -interval=15s -duration=1m
...
2020-04-07 18:55:19 +00:00
```
