doc: nomad debug cli

CHANGELOG.md

@@ -5,6 +5,7 @@ FEATURES:
  * **Licensing (Enterprise)**: Nomad Enterprise now requires a license [[GH-8076](https://github.com/hashicorp/nomad/issues/8076)]
  * **Multiregion Deployments (Enterprise)**: Nomad Enterprise now enables orchestrating deployments across multiple regions. [[GH-8184](https://github.com/hashicorp/nomad/issues/8184)]
  * **Snapshot Backup and Restore**: Nomad eases disaster recovery with new endpoints and commands for point-in-time snapshots.
+ * **Debug Log Archive**: Nomad debug captures state and logs to facilitate support [[GH-8273](https://github.com/hashicorp/nomad/issues/8273)]
  * **Container Network Interface (CNI)**: Support for third-party vendors using the CNI plugin system. [[GH-7518](https://github.com/hashicorp/nomad/issues/7518)]
  * **Multi-interface Networking**: Support for scheduling on specific network interfaces. [[GH-8208](https://github.com/hashicorp/nomad/issues/8208)]
  * **Consul Connect Native**: Support for running Consul Connect Native tasks. [[GH-6083](https://github.com/hashicorp/nomad/issues/6083)]

contributing/checklist-command.md

@@ -30,6 +30,7 @@ CLI (command/) -> API Client (api/) -> HTTP API (command/agent) -> RPC (nomad/)
 ## Docs
 
 * [ ] Changelog
-* [ ] API docs https://www.nomadproject.io/api/index.html
-* [ ] CLI docs https://www.nomadproject.io/docs/commands/index.html
+* [ ] API docs https://www.nomadproject.io/api
+* [ ] CLI docs https://www.nomadproject.io/docs/commands
+* [ ] If adding new docs see [website README](../website/README.md#editing-navigation-sidebars)
 * [ ] Consider if it needs a guide https://www.nomadproject.io/guides/index.html

website/data/docs-navigation.js

@@ -83,7 +83,7 @@ export default [
         category: 'alloc',
         content: ['exec', 'fs', 'logs', 'restart', 'signal', 'status', 'stop']
       },
-
+      'debug',
       {
         category: 'deployment',
         content: ['fail', 'list', 'pause', 'promote', 'resume', 'status', 'unblock']

website/pages/docs/commands/debug.mdx

@@ -0,0 +1,77 @@
+---
+layout: docs
+page_title: 'Commands: debug'
+sidebar_title: debug
+description: |
+  Build a debug archive.
+---
+
+# Command: debug
+
+The `debug` command builds an archive containing Nomad cluster
+configuration and state information, Nomad server and client node
+logs, and pprof profiles from the selected servers and client nodes.
+
+If no selection option is specified, the debug archive contains only
+cluster meta information.
+
+## Usage
+
+```plaintext
+nomad debug [options]
+```
+
+This command accepts comma separated `server-id` and `node-id` IDs for
+monitoring and pprof profiling. If IDs are provided, the command will
+monitor logs for the `duration`, saving a snapshot of Nomad state
+every `interval`. Captured logs and configurations are subjected to
+redaction, but may still contain sensitive information and the archive
+contents should be reviewed before sharing.
+
+If an `output` path is provided, `debug` will create a timestamped
+directory in that path instead of an archive. By default, the command
+creates a compressed tar archive in the current directory.
+
+Consul and Vault status and version information are included if
+configured.
+
+## General Options
+
+@include 'general_options.mdx'
+
+## Debug Options
+
+- `-duration=2m`: Set the duration of the log monitor command.
+  Defaults to `"2m"`. Logs will be captured from specified servers and
+  nodes at `log-level`.
+
+- `-interval=2m`: The interval between snapshots of the Nomad state.
+   If unspecified, only one snapshot is captured.
+
+- `-log-level=DEBUG`: The log level to monitor. Defaults to `DEBUG`.
+
+- `-node-id=n1,n2`: Comma separated list of Nomad client node ids, to
+   monitor for logs and include pprof data. Accepts id prefixes.
+
+- `-server-id=s1,s2`: Comma separated list of Nomad server names, or
+   the special server name "leader" to monitor for logs and include
+   pprof data.
+
+- `-output=path`: Path to the parent directory of the output
+   directory. Defaults to the current directory. If specified, no
+   archive is built.
+
+- `-consul-token`: Token used to query Consul. Defaults to `CONSUL_TOKEN`
+
+- `-vault-token`: Token used to query Vault. Defaults to `VAULT_TOKEN`
+
+## Output
+
+This command prints the name of the timestamped archive file produced.
+
+## Examples
+
+```shell-session
+$ nomad debug -duration 20s -interval 5s -server-id leader -node-id 6e,dd
+Created debug archive: nomad-debug-2020-06-10-145821Z.tar.gz
+```