github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/website/content/docs/commands/operator/debug.mdx (about)

     1  ---
     2  layout: docs
     3  page_title: 'Commands: operator debug'
     4  description: |
     5    Build an archive of debug data.
     6  ---
     7  
     8  # Command: operator debug
     9  
    10  The `operator debug` command builds an archive containing Nomad cluster
    11  configuration and state information, Nomad server and client node
    12  logs, and pprof profiles from the selected servers and client nodes.
    13  
    14  If no selection option is specified, the debug archive contains only
    15  cluster meta information.
    16  
    17  ## Usage
    18  
    19  ```plaintext
    20  nomad operator debug [options]
    21  ```
    22  
    23  This command accepts comma separated `server-id` and `node-id` IDs for
    24  monitoring and pprof profiling. If IDs are provided, the command will
    25  monitor logs for the `duration`, saving a snapshot of Nomad state
    26  every `interval`. Captured logs and configurations are subjected to
    27  redaction, but may still contain sensitive information and the archive
    28  contents should be reviewed before sharing.
    29  
    30  If an `output` path is provided, `debug` will create a timestamped
    31  directory in that path instead of an archive. By default, the command
    32  creates a compressed tar archive in the current directory.
    33  
    34  Consul and Vault status and version information are included if
    35  configured.
    36  
    37  If ACLs are enabled, this command will require a token with the 'node:read'
    38  capability to run. In order to collect information, the token will also
    39  require the 'agent:read' and 'operator:read' capabilities, as well as the
    40  'list-jobs' capability for all namespaces. To collect pprof profiles the
    41  token will also require 'agent:write', or enable_debug configuration set to
    42  true.
    43  
    44  ## General Options
    45  
    46  @include 'general_options.mdx'
    47  
    48  ## Debug Options
    49  
    50  - `-duration=2m`: Set the duration of the debug capture. Logs will be captured from
    51    specified servers and nodes at `log-level`. Defaults to `2m`.
    52  
    53  - `-interval=30s`: The interval between snapshots of the Nomad state.
    54    If unspecified, only one snapshot is captured. Defaults to `30s`.
    55  
    56  - `-log-level=DEBUG`: The log level to monitor. Defaults to `DEBUG`.
    57  
    58  - `-max-nodes=<count>`: Cap the maximum number of client nodes included
    59    in the capture. Defaults to 10, set to 0 for unlimited.
    60  
    61  - `-node-class=<node-class>`: Filter client nodes based on node class.
    62  
    63  - `-node-id=<node1>,<node2>`: Comma separated list of Nomad client node ids
    64    to monitor for logs, API outputs, and pprof profiles. Accepts id prefixes, and
    65    "all" to select all nodes (up to count = max-nodes). Defaults to `all`.
    66  
    67  - `-pprof-duration=<duration>`: Duration for pprof
    68    collection. Defaults to 1s or `-duration`, whichever is less.
    69  
    70  - `-pprof-interval=<pprof-interval>`: The interval between pprof
    71      collections. Set interval equal to duration to capture a single
    72      snapshot. Defaults to 250ms or `-pprof-duration`, whichever is
    73      less.
    74  
    75  - `-server-id=<server1>,<server2>`: Comma separated list of Nomad server names to
    76    monitor for logs, API outputs, and pprof profiles. Accepts server names, "leader", or
    77    "all". Defaults to `all`.
    78  
    79  - `-stale=<true|false>`: If "false", the default, get membership data from the
    80    cluster leader. If the cluster is in an outage unable to establish
    81    leadership, it may be necessary to get the configuration from a non-leader
    82    server.
    83  
    84  - `-event-topic=<allocation,evaluation,job,node,*>:<filter>`: Enable event
    85    stream capture. Filter by comma delimited list of topic filters or "all".
    86    Defaults to "none" (disabled).  Refer to the [Events API](/api-docs/events) for
    87    additional detail.
    88  
    89  - `-verbose`: Enable verbose output
    90  
    91  - `-output=path`: Path to the parent directory of the output
    92    directory. Defaults to the current directory. If specified, no
    93    archive is built.
    94  
    95  - `-consul-http-addr=<addr>`: The address and port of the Consul HTTP
    96    agent. Overrides the `CONSUL_HTTP_ADDR` environment variable.
    97  
    98  - `-consul-token=<token>`: Token used to query Consul. Overrides the
    99    `CONSUL_HTTP_TOKEN` environment variable and the Consul token
   100    file.
   101  
   102  - `-consul-token-file=<path>`: Path to the Consul token file. Overrides the `CONSUL_HTTP_TOKEN_FILE`
   103    environment variable.
   104  
   105  - `-consul-client-cert=<path>`: Path to the Consul client cert file. Overrides the `CONSUL_CLIENT_CERT`
   106    environment variable.
   107  
   108  - `-consul-client-key=<path>`: Path to the Consul client key file. Overrides the `CONSUL_CLIENT_KEY`
   109    environment variable.
   110  
   111  - `-consul-ca-cert=<path>`: Path to a CA file to use with Consul. Overrides the `CONSUL_CACERT`
   112    environment variable and the Consul CA path.
   113  
   114  - `-consul-ca-path=<path>`: Path to a directory of PEM encoded CA cert files to verify the Consul
   115    certificate. Overrides the `CONSUL_CAPATH` environment variable.
   116  
   117  - `-vault-address=<addr>`: The address and port of the Vault HTTP agent. Overrides the `VAULT_ADDR`
   118    environment variable.
   119  
   120  - `-vault-token=<token>`: Token used to query Vault. Overrides the `VAULT_TOKEN` environment
   121    variable.
   122  
   123  - `-vault-client-cert=<path>`: Path to the Vault client cert file. Overrides the `VAULT_CLIENT_CERT`
   124    environment variable.
   125  
   126  - `-vault-client-key=<path>`: Path to the Vault client key file. Overrides the `VAULT_CLIENT_KEY`
   127    environment variable.
   128  
   129  - `-vault-ca-cert=<path>`: Path to a CA file to use with Vault. Overrides the `VAULT_CACERT`
   130    environment variable and the Vault CA path.
   131  
   132  - `-vault-ca-path=<path>`: Path to a directory of PEM encoded CA cert files to verify the Vault
   133    certificate. Overrides the `VAULT_CAPATH` environment variable.
   134  
   135  ## Output
   136  
   137  This command prints a summary of the capture and the name of the timestamped
   138  archive file produced.
   139  
   140  ## Examples
   141  
   142  ```shell-session
   143  $ nomad operator debug -duration 5s -interval 5s -server-id all -node-id b5,20
   144  Starting debugger...
   145  
   146            Servers: (3/3) [server1.global server2.global server3.global]
   147            Clients: (2/3) [b547cd3a-085f-68c2-55f4-e99beebb0433 20c0964b-72cc-4083-87fe-ec6905b6230a]
   148           Interval: 5s
   149           Duration: 5s
   150  
   151  Capturing cluster data...
   152      Capture interval 0000
   153      Capture interval 0001
   154      Capture interval 0002
   155      Capture interval 0003
   156  Created debug archive: nomad-debug-2020-12-08-034455Z.tar.gz
   157  ```
   158  
   159  ```shell-session
   160  $ nomad operator debug -duration 5s -interval 5s -server-id all -node-id all -max-nodes=1
   161  Starting debugger...
   162  
   163            Servers: (3/3) [server1.global server2.global server3.global]
   164            Clients: (1/3) [b547cd3a-085f-68c2-55f4-e99beebb0433]
   165                     Max node count reached (1)
   166           Interval: 5s
   167           Duration: 5s
   168  
   169  Capturing cluster data...
   170      Capture interval 0000
   171      Capture interval 0001
   172      Capture interval 0002
   173      Capture interval 0003
   174  Created debug archive: nomad-debug-2020-12-08-034113Z.tar.gz
   175  ```