From 3e7db13b816ddb7b8ef700df438111475634ea82 Mon Sep 17 00:00:00 2001 From: Florence Morris Date: Tue, 3 Oct 2023 11:12:27 -0400 Subject: [PATCH] (1) Updated cockroach debug zip page with cluster impact warning and recommendation to filter by time range. --- src/current/v23.1/cockroach-debug-zip.md | 19 +++++++++++++++++-- src/current/v23.2/cockroach-debug-zip.md | 19 +++++++++++++++++-- 2 files changed, 34 insertions(+), 4 deletions(-) diff --git a/src/current/v23.1/cockroach-debug-zip.md b/src/current/v23.1/cockroach-debug-zip.md index 6561a891a45..e3b9d989269 100644 --- a/src/current/v23.1/cockroach-debug-zip.md +++ b/src/current/v23.1/cockroach-debug-zip.md @@ -18,16 +18,22 @@ The files produced by `cockroach debug zip` can contain highly [sensitive, perso ### Use cases +{{site.data.alerts.callout_danger}} + `cockroach debug zip` is an expensive operation and impacts cluster performance. + +Only use this command as an emergency measure under the guidance of Cockroach Labs. +{{site.data.alerts.end}} + There are two scenarios in which `debug zip` is useful: +- If you experience severe or difficult-to-reproduce issues with your cluster, Cockroach Labs might ask you to send us your cluster's debugging information using `cockroach debug zip`. We recommend reducing the `*.zip` file size by only [retrieving debugging information for the relevant time range](#generate-a-debug-zip-file-for-a-time-range) of the issue by using the `--files-from`, and/or `--files-until` [flags](#flags). + - To collect all of your nodes' logs, which you can then parse to locate issues. You can optionally use the [flags](#flags) to [retrieve only the log files](#generate-a-debug-zip-file-with-logs-only). For more information about logs, see [Logging]({% link {{ page.version.version }}/logging-overview.md %}). Also note: - Nodes that are currently [down]({% link {{ page.version.version }}/cluster-setup-troubleshooting.md %}#node-liveness-issues) cannot deliver their logs over the network. For these nodes, you must log on to the machine where the `cockroach` process would otherwise be running, and gather the files manually. - Nodes that are currently up but disconnected from other nodes (e.g., because of a [network partition]({% link {{ page.version.version }}/cluster-setup-troubleshooting.md %}#network-partition)) may not be able to respond to `debug zip` requests forwarded by other nodes, but can still respond to requests for data when asked directly. In such situations, we recommend using the [`--host` flag](#client-connection) to point `debug zip` at each of the disconnected nodes until data has been gathered for the entire cluster. -- If you experience severe or difficult-to-reproduce issues with your cluster, Cockroach Labs might ask you to send us your cluster's debugging information using `cockroach debug zip`. - ### Files `cockroach debug zip` collects log files, heap profiles, CPU profiles, and goroutine dumps from the last 48 hours, by default. @@ -148,6 +154,15 @@ $ cockroach debug zip ./cockroach-data/logs/debug.zip --host=200.100.50.25 Secure examples assume you have the appropriate certificates in the default certificate directory, `${HOME}/.cockroach-certs/`. {{site.data.alerts.end}} +### Generate a debug zip file for a time range + +Generate a debug zip file containing only debugging information for a specified time range: + +{% include_cached copy-clipboard.html %} +~~~ shell +$ cockroach debug zip ./cockroach-data/logs/debug.zip --files-from='2023-10-03 13:30' --files-until='2023-10-03 14:30' +~~~ + ### Generate a debug zip file with logs only Generate a debug zip file containing only log files: diff --git a/src/current/v23.2/cockroach-debug-zip.md b/src/current/v23.2/cockroach-debug-zip.md index 6561a891a45..e3b9d989269 100644 --- a/src/current/v23.2/cockroach-debug-zip.md +++ b/src/current/v23.2/cockroach-debug-zip.md @@ -18,16 +18,22 @@ The files produced by `cockroach debug zip` can contain highly [sensitive, perso ### Use cases +{{site.data.alerts.callout_danger}} + `cockroach debug zip` is an expensive operation and impacts cluster performance. + +Only use this command as an emergency measure under the guidance of Cockroach Labs. +{{site.data.alerts.end}} + There are two scenarios in which `debug zip` is useful: +- If you experience severe or difficult-to-reproduce issues with your cluster, Cockroach Labs might ask you to send us your cluster's debugging information using `cockroach debug zip`. We recommend reducing the `*.zip` file size by only [retrieving debugging information for the relevant time range](#generate-a-debug-zip-file-for-a-time-range) of the issue by using the `--files-from`, and/or `--files-until` [flags](#flags). + - To collect all of your nodes' logs, which you can then parse to locate issues. You can optionally use the [flags](#flags) to [retrieve only the log files](#generate-a-debug-zip-file-with-logs-only). For more information about logs, see [Logging]({% link {{ page.version.version }}/logging-overview.md %}). Also note: - Nodes that are currently [down]({% link {{ page.version.version }}/cluster-setup-troubleshooting.md %}#node-liveness-issues) cannot deliver their logs over the network. For these nodes, you must log on to the machine where the `cockroach` process would otherwise be running, and gather the files manually. - Nodes that are currently up but disconnected from other nodes (e.g., because of a [network partition]({% link {{ page.version.version }}/cluster-setup-troubleshooting.md %}#network-partition)) may not be able to respond to `debug zip` requests forwarded by other nodes, but can still respond to requests for data when asked directly. In such situations, we recommend using the [`--host` flag](#client-connection) to point `debug zip` at each of the disconnected nodes until data has been gathered for the entire cluster. -- If you experience severe or difficult-to-reproduce issues with your cluster, Cockroach Labs might ask you to send us your cluster's debugging information using `cockroach debug zip`. - ### Files `cockroach debug zip` collects log files, heap profiles, CPU profiles, and goroutine dumps from the last 48 hours, by default. @@ -148,6 +154,15 @@ $ cockroach debug zip ./cockroach-data/logs/debug.zip --host=200.100.50.25 Secure examples assume you have the appropriate certificates in the default certificate directory, `${HOME}/.cockroach-certs/`. {{site.data.alerts.end}} +### Generate a debug zip file for a time range + +Generate a debug zip file containing only debugging information for a specified time range: + +{% include_cached copy-clipboard.html %} +~~~ shell +$ cockroach debug zip ./cockroach-data/logs/debug.zip --files-from='2023-10-03 13:30' --files-until='2023-10-03 14:30' +~~~ + ### Generate a debug zip file with logs only Generate a debug zip file containing only log files: