diff --git a/CHANGELOG.md b/CHANGELOG.md index fa5f6a4ef..6a949ef78 100644 --- a/CHANGELOG.md +++ b/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)] diff --git a/contributing/checklist-command.md b/contributing/checklist-command.md index 6d99b24d1..98685cb2f 100644 --- a/contributing/checklist-command.md +++ b/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 diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index 457ca0076..88a0fdd6b 100644 --- a/website/data/docs-navigation.js +++ b/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'] diff --git a/website/pages/docs/commands/debug.mdx b/website/pages/docs/commands/debug.mdx new file mode 100644 index 000000000..0aee6b64a --- /dev/null +++ b/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 +```