(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

@@ -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:

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: