github.com/outbrain/consul@v1.4.5/website/source/docs/commands/debug.html.markdown.erb (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Commands: Debug"
     4  sidebar_current: "docs-commands-debug"
     5  ---
     6  
     7  # Consul Debug
     8  
     9  Command: `consul debug`
    10  
    11  The `consul debug` command monitors a Consul agent for the specified period of
    12  time, recording information about the agent, cluster, and environment to an archive
    13  written to the current directory.
    14  
    15  Providing support for complex issues encountered by Consul operators often
    16  requires a large amount of debugging information to be retrieved. This command
    17  aims to shortcut that coordination and provide a simple workflow for accessing
    18  data about Consul agent, cluster, and environment to enable faster
    19  isolation and debugging of issues.
    20  
    21  This command requires an `operator:read` ACL token in order to retrieve the
    22  data from the target agent, if ACLs are enabled.
    23  
    24  If the command is interrupted, as it could be given a long duration but
    25  require less time than expected, it will attempt to archive the current
    26  captured data.
    27  
    28  ## Security and Privacy
    29  
    30  By default, ACL tokens, private keys, and other sensitive material related
    31  to Consul is sanitized and not available in this archive. However, other
    32  information about the environment the target agent is running in is available
    33  in plain text within the archive.
    34  
    35  It is recommended to validate the contents of the archive and redact any
    36  material classified as sensitive to the target environment, or use the `-capture`
    37  flag to not retrieve it initially.
    38  
    39  Additionally, we recommend securely transmitting this archive via encryption
    40  or otherwise.
    41  
    42  ## Usage
    43  
    44  `Usage: consul debug [options]`
    45  
    46  By default, the debug command will capture an archive at the current path for
    47  all targets for 2 minutes.
    48  
    49  #### API Options
    50  
    51  <%= partial "docs/commands/http_api_options_client" %>
    52  
    53  #### Command Options
    54  
    55  * `-duration` - Optional, the total time to capture data for from the target agent. Must
    56    be greater than the interval and longer than 10 seconds. Defaults to 2 minutes.
    57  
    58  * `-interval` - Optional, the interval at which to capture dynamic data, such as logs
    59    and metrics. Must be longer than 5 seconds. Defaults to 30 seconds.
    60  
    61  * `-capture` - Optional, can be specified multiple times for each [capture target](#capture-targets)
    62    and will only record that information in the archive.
    63  
    64  * `-output` - Optional, the full path of where to write the directory of data and
    65    resulting archive. Defaults to the current directory.
    66  
    67  * `-archive` - Optional, if the tool show archive the directory of data into a
    68    compressed tar file. Defaults to true.
    69  
    70  ## Capture Targets
    71  
    72  The `-capture` flag can be specified multiple times to capture specific
    73  information when `debug` is running. By default, it captures all information.
    74  
    75  | Target | Description                  |
    76  | ------ | ---------------------------- |
    77  | `agent` | Version and configuration information about the agent. |
    78  | `host` | Information about resources on the host running the target agent such as CPU, memory, and disk. |
    79  | `cluster` | A list of all the WAN and LAN members in the cluster. |
    80  | `metrics` | Metrics from the in-memory metrics endpoint in the target, captured at the interval. |
    81  | `logs` | `DEBUG` level logs for the target agent, captured for the interval. |
    82  | `pprof` | Golang heap, CPU, goroutine, and trace profiling. This information is not retrieved unless [`enable_debug`](/docs/agent/options.html#enable_debug) is set to `true` on the target agent. |
    83  
    84  ## Examples
    85  
    86  This command can be run from any host with the Consul binary, but requires
    87  network access to the target agent in order to retrieve data. Once retrieved,
    88  the data is written to the the specified path (defaulting to the current
    89  directory) on the host where the command runs.
    90  
    91  By default the command will capture all available data from the default
    92  agent address on loopback for 2 minutes at 30 second intervals.
    93  
    94  ```text
    95  $ consul debug
    96  ...
    97  ```
    98  
    99  In this example, the archive is collected from a different agent on the
   100  network using the standard Consul CLI flag to change the API address.
   101  
   102  ```text
   103  $ consul debug -http-addr=10.0.1.10:8500
   104  ...
   105  ```
   106  
   107  The capture flag can be specified to only record a subset of data
   108  about the agent and environment.
   109  
   110  ```text
   111  $ consul debug -capture agent -capture host -capture logs
   112  ...
   113  ```
   114  
   115  The duration of the command and interval of capturing dynamic
   116  information (such as metrics) can be specified with the `-interval`
   117  and `-duration` flags.
   118  
   119  ```text
   120  $ consul debug -interval=15s -duration=1m
   121  ...
   122  ```