Merge pull request #33130 from sbeskin-redhat/1962488_Prometheus_metrics_to_must-gather_section

BZ1962488: Viewing metrics with Prometheus added to 'Collecting logs and metrics with the must-gather tool' section of Troubleshooting

Author: apinnick

modules/migration-using-must-gather.adoc

@@ -4,28 +4,68 @@
 // * migration-toolkit-for-containers/troubleshooting-mtc
 
 [id="migration-using-must-gather_{context}"]
-= Using must-gather to collect data
 
-You must run the `must-gather` tool if you open a customer support case on the link:https://access.redhat.com[Red Hat Customer Portal] for the {mtc-full} ({mtc-short}).
 
-The `openshift-migration-must-gather-rhel8` image for {mtc-short} collects migration-specific logs and data that are not collected by the default `must-gather` image.
+
+= Using the must-gather tool
+
+You can collect logs, metrics, and information about {MTC-short} custom resources by using the `must-gather` tool.
+
+The `must-gather` data must be attached to all customer cases.
+
+You can collect data for a one-hour or a 24-hour period and view the data with the Prometheus console.
+
+.Prerequisites
+
+* You must be logged in to the {product-title} cluster as a user with the `cluster-admin` role.
+* You must have the OpenShift CLI installed.
 
 .Procedure
 
 . Navigate to the directory where you want to store the `must-gather` data.
-. Run the `must-gather` command:
+. Run the `oc adm must-gather` command:
+
+* To gather data for the past hour:
 +
 [source,terminal,subs="attributes+"]
 ----
 $ oc adm must-gather --image=registry.redhat.io/rhmtc/openshift-migration-must-gather-rhel8:v{mtc-version}
 ----
++
+The data is saved as `/must-gather/must-gather.tar.gz`. You can upload this file to a support case on the link:https://access.redhat.com/[Red Hat Customer Portal].
+
+* To gather data for the past 24 hours:
++
+[source,terminal,subs="attributes+"]
+----
+$ oc adm must-gather --image= \
+  registry.redhat.io/rhmtc/openshift-migration-must-gather-rhel8: \
+  v{mtc-version} -- /usr/bin/gather_metrics_dump
+----
++
+This operation can take a long time. The data is saved as `/must-gather/metrics/prom_data.tar.gz`. You can view this file with the Prometheus console.
+
+.To view data with the Prometheus console
 
-. Remove authentication keys and other sensitive information.
-. Create an archive file containing the contents of the `must-gather` data directory:
+. Create a local Prometheus instance:
++
+[source,terminal]
+----
+$ make prometheus-run
+----
++
+The command outputs the Prometheus URL:
 +
+.Output
 [source,terminal]
 ----
-$ tar cvaf must-gather.tar.gz must-gather.local.<uid>/
+Started Prometheus on http://localhost:9090
 ----
 
-. Upload the compressed file as an attachment to your customer support case.
+. Launch a web browser and navigate to the URL to view the data by using the Prometheus web console.
+. After you have viewed the data, delete the Prometheus instance and data:
++
+[source,terminal]
+----
+$ make prometheus-cleanup
+----