[enterprise-4.2] Add the "Examining cluster metrics" section (#16778)

- Add content for cluster metrics

_topic_map.yml

@@ -818,6 +818,8 @@ Topics:
     File: configuring-the-monitoring-stack
   - Name: Managing cluster alerts
     File: managing-cluster-alerts
+  - Name: Examining cluster metrics
+    File: examining-cluster-metrics
   - Name: Accessing Prometheus, Alertmanager, and Grafana
     File: prometheus-alertmanager-and-grafana
 - Name: Exposing custom application metrics for autoscaling

modules/monitoring-accessing-prometheus-alerting-ui-grafana-using-the-web-console.adoc

@@ -3,9 +3,9 @@
 // * monitoring/cluster-monitoring/prometheus-alertmanager-and-grafana.adoc
 
 [id="monitoring-accessing-prometheus-alerting-ui-grafana-using-the-web-console_{context}"]
-= Accessing Prometheus, Alerting UI, and Grafana using the Web console
+= Accessing Prometheus, Alerting UI, and Grafana using the web console
 
-You can access Prometheus, Alerting UI, and Grafana web UIs using a Web browser through the {product-title} Web console.
+You can access Prometheus, Alerting UI, and Grafana web UIs using a web browser through the {product-title} web console.
 
 [NOTE]
 ====
@@ -18,11 +18,11 @@ The Alerting UI accessed in this procedure is the new interface for Alertmanager
 
 .Procedure
 
-. Navigate to the {product-title} Web console and authenticate.
+. Navigate to the {product-title} web console and authenticate.
 
-. To access Prometheus, navigate to "Monitoring" -> "Metrics".
+. To access Prometheus, navigate to the "Monitoring" -> "Metrics" page.
 +
-To access the Alerting UI, navigate to "Monitoring" -> "Alerts" or "Monitoring" -> "Silences".
+To access the Alerting UI, navigate to the "Monitoring" -> "Alerting" page.
 +
-To access Grafana, navigate to "Monitoring" -> "Dashboards".
+To access Grafana, navigate to the "Monitoring" -> "Dashboards" page.
 

modules/monitoring-accessing-prometheus-alertmanager-grafana-directly.adoc

@@ -5,7 +5,7 @@
 [id="monitoring-accessing-prometheus-alertmanager-grafana-directly_{context}"]
 = Accessing Prometheus, Alertmanager, and Grafana directly
 
-You can access Prometheus, Alertmanager, and Grafana web UIs using the `oc` tool and a Web browser.
+You can access Prometheus, Alertmanager, and Grafana web UIs using the `oc` tool and a web browser.
 
 [NOTE]
 ====
@@ -38,5 +38,5 @@ For example, this is the resulting URL for Alertmanager:
 https://alertmanager-main-openshift-monitoring.apps._url_.openshift.com
 ----
 
-. Navigate to the address using a Web browser and authenticate.
+. Navigate to the address using a web browser and authenticate.
 

modules/monitoring-configuring-cluster-for-application-monitoring.adoc

@@ -13,6 +13,6 @@ Before application developers can monitor their applications, the human operator
 
 .Procedure
 
-. In the {product-title} web console, navigate to *Operators* -> *OperatorHub* and install the Prometheus Operator in the namespace where your application is.
+. In the {product-title} web console, navigate to the *Operators* -> *OperatorHub* page and install the Prometheus Operator in the namespace where your application is.
 
-. Navigate to *Catalog* -> *Developer Catalog* and install Prometheus, Alertmanager, Prometheus Rule, and Service Monitor in the same namespace.
+. Navigate to the *Catalog* -> *Developer Catalog* page and install Prometheus, Alertmanager, Prometheus Rule, and Service Monitor in the same namespace.

modules/monitoring-contents-of-the-alerting-ui.adoc

@@ -5,13 +5,13 @@
 [id="contents-of-the-alerting-ui_{context}"]
 = Contents of the Alerting UI
 
-This section shows and explains the contents of the Alerting UI, a Web interface to the Alertmanager.
+This section shows and explains the contents of the Alerting UI, a web interface to the Alertmanager.
 
 The main three pages of the Alerting UI are the *Alerts*, the *Silences*, and the *YAML* pages.
 
-The *Alerts* page is located in *Monitoring* -> *Alerts* of the {product-title} web console.
+The *Alerts* page is accessible by clicking *Monitoring* -> *Alerts* in the {product-title} web console.
 
-image::alerts-screen.png[]
+image::monitoring-alerts-screen.png[]
 
 . Filtering alerts by their names.
 . Filtering the alerts by their states. To fire, some alerts need a certain condition to be true for the duration of a timeout. If a condition of an alert is currently true, but the timeout has not been reached, such an alert is in the *Pending* state.
@@ -21,9 +21,9 @@ image::alerts-screen.png[]
 . Value of the Severity label of the alert.
 . Actions you can do with the alert.
 
-The *Silences* page is located in *Monitoring* -> *Silences* of the {product-title} web console.
+The *Silences* page is accessible by clicking *Monitoring* -> *Silences* in the {product-title} web console.
 
-image::silences-screen.png[]
+image::monitoring-silences-screen.png[]
 
 . Creating a silence for an alert.
 . Filtering silences by their name.
@@ -33,9 +33,9 @@ image::silences-screen.png[]
 . Number of alerts that are being silenced by the silence.
 . Actions you can do with a silence.
 
-The *YAML* page is located in *Monitoring* -> *Alerting* -> *YAML* of the OpenShift Container Platform web console.
+The *YAML* page is accessible by clicking *Monitoring* -> *Alerting* -> *YAML* in the {product-title} web console.
 
-image::yaml-screen.png[]
+image::monitoring-yaml-screen.png[]
 
 . Upload a file with Alertmanager configuration.
 . Examine and edit the current Alertmanager configuration.

modules/monitoring-contents-of-the-metrics-ui.adoc

@@ -0,0 +1,35 @@
+// Module included in the following assemblies:
+//
+// * monitoring/cluster-monitoring/examining-cluster-metrics.adoc
+
+[id="contents-of-the-metrics-ui_{context}"]
+= Contents of the Metrics UI
+
+This section shows and explains the contents of the Metrics UI, a web interface to Prometheus.
+
+The *Metrics* page is accessible by clicking *Monitoring* -> *Metrics* in the {product-title} web console.
+
+image::monitoring-metrics-screen.png[]
+
+. Actions.
+* Add query.
+* Expand all query tables.
+* Delete all queries.
+. Hide the plot.
+. The interactive plot.
+. The catalog of available metrics.
+. Add query.
+. Run queries.
+. Query forms.
+. Expand or collapse the form.
+. The query.
+. Clear query.
+. Disable query.
+. Actions for a specific query.
+* Disable query.
+* Hide all series of the query from the plot.
+* Delete query.
+. The metrics table for a query.
+. Color assigned to the graph of the metric. Clicking the square shows or hides the metric's graph.
+
+Additionally, there is a link to the old Prometheus interface next to the title of the page.

modules/monitoring-editing-silences.adoc

@@ -9,7 +9,7 @@ You can edit a silence, which will expire the existing silence and create a new
 
 .Procedure
 
-. Navigate to the *Monitoring* -> *Silences* screen.
+. Navigate to the *Monitoring* -> *Alerting* -> *Silences* page.
 
 . For the silence you want to modify, click the button in the last column and click *Edit silence*.
 +

modules/monitoring-expiring-silences.adoc

@@ -9,7 +9,7 @@ You can expire a silence. Expiring a silence deactivates it forever.
 
 .Procedure
 
-. Navigate to the *Monitoring* -> *Silences* page.
+. Navigate to the *Monitoring* -> *Alerting* -> *Silences* page.
 
 . For the silence you want to expire, click the button in the last column and click *Expire Silence*.
 +

modules/monitoring-exploring-the-visualized-metrics.adoc

@@ -0,0 +1,26 @@
+// Module included in the following assemblies:
+//
+// * monitoring/cluster-monitoring/examining-cluster-metrics.adoc
+
+[id="exploring-the-visualized-metrics_{context}"]
+= Exploring the visualized metrics
+
+After running the queries, the metrics are displayed on the interactive plot. The X axis of the plot represents time. The Y axis represents the metrics values. Each metric is shown as a colored graph. You can manipulate the plot and explore the metrics.
+
+.Procedure
+
+. Initially, all metrics from all enabled queries are shown on the plot. You can select which metrics are shown.
+* To hide all metrics from a query, click {kebab} for the query and click *Hide all series*.
+* To hide a specific metric, go to the query table and click the colored square near the metric name.
+. To zoom into the plot and change the shown time range, do one of the following:
++
+--
+* Visually select the time range by clicking and dragging on the plot horizontally.
+* Use the menu in the left upper corner to select the time range.
+--
++
+To reset the time range, click *Reset Zoom*.
+. To display outputs of all queries at a specific point in time, hold the mouse cursor on the plot at that point. The query outputs will appear in a pop-up box.
+. For more detailed information about metrics of a specific query, expand the table of that query using the drop-down button. Every metric is shown with its current value.
+. To hide the plot, click *Hide Graph*.
+

modules/monitoring-getting-information-about-alerts-and-alerting-rules.adoc

@@ -9,7 +9,7 @@ You can find an alert and see information about it or its governing alerting rul
 
 .Procedure
 
-. Open the {product-title} web console and navigate to *Monitoring* -> *Alerts*.
+. Open the {product-title} web console and navigate to the *Monitoring* -> *Alerting* -> *Alerts* page.
 
 . Optional: Filter the alerts by name using the *Filter alerts by name* field.
 
@@ -21,7 +21,7 @@ You can find an alert and see information about it or its governing alerting rul
 +
 To see alert details, click on the name of the alert. This is the page with alert details:
 +
-image::alert-overview.png[]
+image::monitoring-alert-overview.png[]
 +
 The page has the graph with timeseries of the alert. It also has information about the alert, including:
 +
@@ -32,7 +32,7 @@ The page has the graph with timeseries of the alert. It also has information abo
 +
 To see alerting rule details, click the button in the last column and select *View Alerting Rule*. This is the page with alerting rule details:
 +
-image::alerting-rule-overview.png[]
+image::monitoring-alerting-rule-overview.png[]
 +
 The page has information about the alerting rule, including:
 +

modules/monitoring-getting-information-about-silences.adoc

@@ -9,7 +9,7 @@ You can find a silence and view its details.
 
 .Procedure
 
-. Open the {product-title} web console and navigate to *Monitoring* -> *Silences*.
+. Open the {product-title} web console and navigate to the *Monitoring* -> *Alerting* -> *Silences* page.
 
 . Optional: Filter the silences by name using the *Filter Silences by name* field.
 

modules/monitoring-running-metrics-queries.adoc

@@ -0,0 +1,30 @@
+// Module included in the following assemblies:
+//
+// * monitoring/cluster-monitoring/examining-cluster-metrics.adoc
+
+[id="running-metrics-queries_{context}"]
+= Running metrics queries
+
+You begin working with metrics by entering one or several Prometheus Query Language (PromQL) queries.
+
+.Procedure
+
+. Open the {product-title} web console and navigate to the *Monitoring* -> *Metrics* page.
+
+. In the query field, enter your PromQL query.
+* To show all available metrics and PromQL functions, click *Insert Metric at Cursor*.
+. For multiple queries, click *Add Query*.
+. For deleting queries, click {kebab} for the query, then select *Delete query*.
+. For keeping but not running a query, click the *Disable query* button.
+. Once you finish creating queries, click the *Run Queries* button. The metrics from the queries are visualized on the plot. If a query is invalid, the UI shows an error message.
++
+[NOTE]
+====
+Queries that operate on large amounts of data might timeout or overload the browser when drawing timeseries graphs. To avoid this, hide the graph and calibrate your query using only the metrics table. Then, after finding a feasible query, enable the plot to draw the graphs.
+====
++
+. Optional: The page URL now contains the queries you ran. To use this set of queries again in the future, save this URL.
+
+.Additional resources
+
+See the link:https://prometheus.io/docs/prometheus/latest/querying/basics/[Prometheus Query Language documentation].

modules/monitoring-silencing-alerts.adoc

@@ -11,7 +11,7 @@ You can either silence a specific alert or silence alerts that match a specifica
 
 To silence a set of alerts by creating an alert specification:
 
-. Navigate to the *Monitoring* -> *Silences* page of the {product-title} web console.
+. Navigate to the *Monitoring* -> *Alerting* -> *Silences* page of the {product-title} web console.
 
 . Click *Create Silence*.
 
@@ -21,7 +21,7 @@ To silence a set of alerts by creating an alert specification:
 
 To silence a specific alert:
 
-. Navigate to the *Monitoring* -> *Alerts* page of the {product-title} web console.
+. Navigate to the *Monitoring* -> *Alerting* -> *Alerts* page of the {product-title} web console.
 
 . For the alert that you want to silence, click the button in the last column and click *Silence Alert*. The *Create Silence* form will appear with prepopulated specification of the chosen alert.
 

monitoring/cluster-monitoring/examining-cluster-metrics.adoc

@@ -0,0 +1,17 @@
+[id="examining-cluster-metrics"]
+= Examining cluster metrics
+include::modules/common-attributes.adoc[]
+:context: querying-metrics
+
+toc::[]
+
+{product-title} {product-version} provides a web interface to Prometheus, which enables you to run Prometheus Query Language (PromQL) queries and examine the metrics visualized on a plot. This functionality provides an extensive overview of the cluster state and enables you to troubleshoot problems.
+
+include::modules/monitoring-contents-of-the-metrics-ui.adoc[leveloffset=+1]
+include::modules/monitoring-running-metrics-queries.adoc[leveloffset=+1]
+include::modules/monitoring-exploring-the-visualized-metrics.adoc[leveloffset=+1]
+
+.Next steps
+
+xref:../../monitoring/cluster-monitoring/prometheus-alertmanager-and-grafana.adoc#prometheus-alertmanager-and-grafana[Access the Prometheus, Alertmanager, and Grafana.]
+

monitoring/cluster-monitoring/managing-cluster-alerts.adoc

@@ -5,7 +5,7 @@ include::modules/common-attributes.adoc[]
 
 toc::[]
 
-{product-title} 4 provides a Web interface to the Alertmanager, which enables you to manage alerts. This section demonstrates how to use the Alerting UI.
+{product-title} {product-version} provides a web interface to the Alertmanager, which enables you to manage alerts. This section demonstrates how to use the Alerting UI.
 
 include::modules/monitoring-contents-of-the-alerting-ui.adoc[leveloffset=+1]
 include::modules/monitoring-getting-information-about-alerts-and-alerting-rules.adoc[leveloffset=+1]
@@ -16,5 +16,5 @@ include::modules/monitoring-expiring-silences.adoc[leveloffset=+1]
 
 .Next steps
 
-xref:../../monitoring/cluster-monitoring/prometheus-alertmanager-and-grafana.adoc#prometheus-alertmanager-and-grafana[Access the Prometheus, Alertmanager, and Grafana.]
+xref:../../monitoring/cluster-monitoring/examining-cluster-metrics.adoc#examining-cluster-metrics[Examine cluster metrics.]