Add the "Examining cluster metrics" section #16752

rh-max · 2019-09-19T01:30:55Z

@jboxman Let's use this PR (opened against master). Feel free to ignore the original #16495 . Upon merging, it is to be cherrypicked to enterprise-4.2.

Once you finish the review, please indicate it somehow (say, with a comment).

To address your comments in the original PR:

"I'd put the period after the link instead of as part of it." A valid suggestion, but I'm thinking of this as a possible list item (if there was more than one next step), and for list items, it's better to enclose them whole inside link tags. But, I've applied this feedback in a different place.
"per our OpenShift docs contributing guidelines, we're wrapping text at 80 columns" That's something I'm strongly opposed to, because it causes loads of problems (messes up git changes, hopples grep, impairs general editing) for the wrong reasons (wrapping is a question of presentation, not of content; in other words, it's up to the editor to visually wrap lines for the writer, it's not up to the newline characters in the middle of a paragraph). There are exceptions, but not in case of our docs, IMO. If need be, I'm ready to discuss it with folks who are promoting this.

Several fixes and improvements Add a note on running demanding queries

jboxman · 2019-09-20T01:44:25Z

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

+
+The *Metrics* page is located in *Monitoring* -> *Metrics* of the {product-title} web console.
+
+image::../images/metrics-screen.png[]


Does it make sense to disambiguate this filename? Some (but not all) of the images, such as for ossm and olm, use a prefix for the filename.

Good idea, implemented across all monitoring images.

jboxman · 2019-09-20T01:50:28Z

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

+. 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.


I'd say: You can access the old Prometheus interface by clicking the Prometheus UI link at the top of the page.

Would someone know it's the old interface? Or is it just an alternate interface?

The perspective of this whole section is "what do we have in this interface", that's why for all items I just call them out and say what they are for. You suggestion is valid for a procedure module.
It's not the best word, true. We are using old to imply that people should move away from that and into the new interface developed by the OCP team. "Alternate" interface doesn't have that implication. As to whether someone would know: maybe not, and that's why we'd better tell them.

jboxman · 2019-09-20T01:54:35Z

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

+
+This section shows and explains the contents of the Metrics UI, a Web interface to Prometheus.
+
+The *Metrics* page is located in *Monitoring* -> *Metrics* of the {product-title} web console.


I haven't written any UI docs, so I don't know what we're calling these things.

Is it the Monitoring -> Metrics section? Pane? Panel? Page?

The Metrics page is located in Monitoring -> Metrics section of the {product-title} web console.

A valid suggestion from the POV of English. However, I just went through all occurrences of this and specifying this everywhere would add too much noise to the text. When a user reads this, they'll know to just click something saying Monitoring and then something saying Metrics and they won't care what it's called.
Besides, Monitoring -> Metrics here is really a navigation instruction that leads to the Metrics page.

Read your later comment and reconsidered. Implemented this across the whole of monitoring docs. Thanks!

jboxman · 2019-09-20T01:57:17Z

modules/monitoring-exploring-the-visualized-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.


I'd probably italicize X and Y, as first usage. From contributing guidelines: https://github.com/openshift/openshift-docs/blob/enterprise-4.1/contributing_to_docs/doc_guidelines.adoc#quick-markup-reference

It's not a term though. It just refers to something on the plot and says what it represents.
And it's also one of the many things I'm describing here, and not particularly important in any way. So I don't see a need to emphasize this. Besides, by that logic, I'd want to italicize "the interactive plot" and "colored graph". I think all that is unnecessary.
It's also used only once, so it's first and only usage.

jboxman · 2019-09-20T02:01:51Z

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

+.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 the action button of the query and click "Hide all series".


Based on our guidelines, I'd bold button names, such as action button.

You are right, implemented everywhere.

jboxman · 2019-09-20T02:02:41Z

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

+* Use the menu in the left upper corner to select the time range.
+--
+
+To reset the time range, click "Reset Zoom".


s/"Reset Zoom"/Reset Zoom/

Implemented.

jboxman · 2019-09-20T02:05:16Z

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

+--
+
+To reset the time range, click "Reset Zoom".
+. To see outputs of all queries at a specific point in time, hold the mouse cursor on the plot at that point. Query outputs will appear in a popup box.


s/see/display/

That's much better, implemented.

jboxman · 2019-09-20T02:06:12Z

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

+--
+
+To reset the time range, click "Reset Zoom".
+. To see outputs of all queries at a specific point in time, hold the mouse cursor on the plot at that point. Query outputs will appear in a popup box.


s/Query/The query/

Implemented.

jboxman · 2019-09-20T02:09:53Z

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

+--
+
+To reset the time range, click "Reset Zoom".
+. To see outputs of all queries at a specific point in time, hold the mouse cursor on the plot at that point. Query outputs will appear in a popup box.


I wonder about box vs window, but I don't think we have any codified style for referring to the UI elements in the Web UI yet.

Calling that small popup rectange a window would be confusing. It think this will be commonly understood much better as a "popup box".

jboxman · 2019-09-20T02:10:11Z

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

+
+To reset the time range, click "Reset Zoom".
+. To see outputs of all queries at a specific point in time, hold the mouse cursor on the plot at that point. Query outputs will appear in a popup box.
+. For more detailed information about metrics of a specific query, expand the table of that query. Every metric is shown with its current value.


How do I expand the query?

Specified: "using the dropdown button".

I asked around, and w're using drop-down instead of dropdown. No one's heard of a drop-down button before though.

jboxman · 2019-09-20T02:10:53Z

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

+To reset the time range, click "Reset Zoom".
+. To see outputs of all queries at a specific point in time, hold the mouse cursor on the plot at that point. Query outputs will appear in a popup box.
+. For more detailed information about metrics of a specific query, expand the table of that query. Every metric is shown with its current value.
+. To hide the plot, use the "Hide Graph" button.


s/use the "Hide Graph" button./click Hide Graph./

Implemented.

modules/monitoring-running-metrics-queries.adoc

jboxman · 2019-09-20T02:15:27Z

modules/monitoring-running-metrics-queries.adoc

+
+.Procedure
+
+. Open the OpenShift Container Platform web console and navigate to *Monitoring* -> *Metrics*.


{product-title}

Implemented here and in another place.

jboxman · 2019-09-20T02:18:36Z

@openshift/team-documentation

So having not done much with UI, I wonder about several things, but particularly when navigating:

navigate to Monitoring -> Metrics.

Do you navigate to parts of the UI? And what is that part? Is it navigate to the Monitoring > Metrics page/section/pane/panel/area? Or is to Monitoring > Metrics enough without any qualification of what exactly it is?

It looks like we have this in our contributor guidelines:

Navigate to the Operators -> Catalog Sources page.

jboxman · 2019-09-20T02:19:52Z

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

+
+toc::[]
+
+{product-title} 4 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 provides an extensive overview of the cluster state and enables you to troubleshoot problems.


Does it make sense to use {product-version} here?

Yep, implemented.

jboxman · 2019-09-20T02:20:48Z

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

+
+toc::[]
+
+{product-title} 4 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 provides an extensive overview of the cluster state and enables you to troubleshoot problems.


This what? The plot? PromQL? Prometheus?

Specified ("This functionality").

jboxman · 2019-09-20T02:24:46Z

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

+
+.Next steps
+
+xref:../../monitoring/cluster-monitoring/prometheus-alertmanager-and-grafana.adoc#prometheus-alertmanager-and-grafana[Access the Prometheus, Alertmanager, and Grafana.]


Access the Prometheus, Alertmanager, and Grafana. interfaces? pages? Besides being grouped together, I'm not sure what the relationship is between these?

I was asked (twice) to leave "interfaces" out of this wording due to some technicality (frankly I don't remember what technicality).
These three things is why have the monitoring stack at all. They are how you actually use the stack once you've configured it.

jboxman · 2019-09-20T02:26:14Z

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

+
+toc::[]
+
+{product-title} 4 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 provides an extensive overview of the cluster state and enables you to troubleshoot problems.


Per IBM:

web adj, n
Write as shown - lowercase “w.”

Implemented everywhere.

jboxman · 2019-09-20T02:29:16Z

modules/monitoring-running-metrics-queries.adoc

+
+[NOTE]
+====
+Queries that operate on large amounts of data might timeout or overload the browser when drawing timeseries graphs. To avoid this, you might prefer to 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.


s/you might prefer to hide/hide/

Implemented.

jboxman · 2019-09-20T02:30:58Z

modules/monitoring-running-metrics-queries.adoc

+. Open the OpenShift Container Platform web console and navigate to *Monitoring* -> *Metrics*.
+
+. In the query field, enter your PromQL query.
+* To show all available metrics and PromQL functions, use the "Insert Metric at Cursor" button.


s/use the "Insert Metric at Cursor" button/click Insert Metric at Cursor/

Implemented.

jboxman · 2019-09-20T02:31:23Z

modules/monitoring-running-metrics-queries.adoc

+
+. In the query field, enter your PromQL query.
+* To show all available metrics and PromQL functions, use the "Insert Metric at Cursor" button.
+. For multiple queries, use the "Add Query" button.


s/use the "Add Query" button./click Add Query./

Implemented.

jboxman · 2019-09-20T02:43:04Z

modules/monitoring-running-metrics-queries.adoc

+. In the query field, enter your PromQL query.
+* To show all available metrics and PromQL functions, use the "Insert Metric at Cursor" button.
+. For multiple queries, use the "Add Query" button.
+. For deleting queries, click the action button for the query and select "Delete query".


Is 12 earlier the action button? We had some discussion about how to describe the ... button.

We actually have an attribute for it:

:kebab: image:kebab.png[title="Options menu"]

So you could replace instances of these with:

click {kebab} for the query, and then select Delete query.

s/"Delete query"/Delete query/

Nice! I never liked my wording. Implemented for both occurrences.

jboxman · 2019-09-20T02:44:26Z

modules/monitoring-running-metrics-queries.adoc

+* To show all available metrics and PromQL functions, use the "Insert Metric at Cursor" button.
+. For multiple queries, use the "Add Query" button.
+. For deleting queries, click the action button for the query and select "Delete query".
+. For keeping but not running a query, click the "Disable query" button.


s/the "Disable query" button/Disable query/

Implemented.

jboxman · 2019-09-20T02:45:05Z

modules/monitoring-running-metrics-queries.adoc

+. For multiple queries, use the "Add Query" button.
+. For deleting queries, click the action button for the query and 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.


s/click the "Run Queries" button/click Run Queries/

Implemented.

jboxman · 2019-09-20T02:45:46Z

@rh-max, I completed the review.

openshift-docs-preview-bot · 2019-09-20T10:08:48Z

The preview will be available shortly at:

https://monitoring-metrics-ui--ocpdocs.netlify.com/

rh-max · 2019-09-20T11:35:43Z

@openshift/team-documentation

So having not done much with UI, I wonder about several things, but particularly when navigating:

navigate to Monitoring -> Metrics.

Do you navigate to parts of the UI? And what is that part? Is it navigate to the Monitoring > Metrics page/section/pane/panel/area? Or is to Monitoring > Metrics enough without any qualification of what exactly it is?

It looks like we have this in our contributor guidelines:

Navigate to the Operators -> Catalog Sources page.

Implemented everywhere in monitoring docs.

rh-max · 2019-09-20T13:56:26Z

@rh-max, I completed the review.

Thanks, very thorough! I've implemented much of the feedback. If you are fine with the current state, please merge this and cherrypick to enterprise-4.2. Thank you.

jboxman · 2019-09-20T19:17:51Z

/cherrypick enterprise-4.2

openshift-cherrypick-robot · 2019-09-20T19:18:04Z

@jboxman: new pull request created: #16778

Details

In response to this:

/cherrypick enterprise-4.2

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

juzhao · 2019-09-23T05:18:53Z

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

+
+. Actions.
+* Add query.
+* Expand all query tables.


If one result table is collapse, the menu is "Collapse all query tables", if all tables are collapsed, the menu is "Expand all query tables"
I think
Expand/Collapse all query tables(Based on the result table is collapsed or expanded) is better.

I changed to "Expand or collapse", but didn't use "(Based on the result table is collapsed or expanded)", it is too long and unnecessary.
Implemented in #16978.

juzhao · 2019-09-23T05:28:32Z

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

+. Clear query.
+. Disable query.
+. Actions for a specific query.
+* Disable query.


if the query is disabled, the menu is "Enable query",
if the query is enabled, the menu is "Disable query"
I think
Enable /Disable query(Based on the query is disabled or enabled ) is better.

It is the same for "Hide all series"

I changed to "Enable or disable", but didn't use "(Based on the query is disabled or enabled )", it is too long and unnecessary.
Implemented in #16978.

juzhao · 2019-09-23T06:20:34Z

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

+--
+
+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.


hold the mouse cursor on the plot at that point
what about changing to "move the mouse cursor over the line"?

It's enough to just be on the right point in the X axis (time), you can be anywhere in the Y axis (metric value). It's good if the users know that, that's why I used the wording "on the plot at that point [in time]". You don't need to put cursor directly over the graph ("the line").
Not implemented.

juzhao · 2019-09-23T06:28:23Z

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

+= 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.


Prometheus, Alerting UI, and Grafana web UIs
=>
Prometheus, Alerting, and Grafana web UIs

Implemented in #16978.

juzhao · 2019-09-23T06:51:56Z

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

+. 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.


Navigate to the Catalog -> Developer Catalog page
It is better change to
Navigate to the Operators -> Installed Operators page

reason: there is not link in the left navigation area links to /catalog page

Implemented in #16978.

juzhao · 2019-09-23T07:53:38Z

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

 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.


The Alerts page is accessible by clicking Monitoring -> Alerting -> Alerts

Implemented in #16978.

juzhao · 2019-09-23T07:53:54Z

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

 . 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.


The Silences page is accessible by clicking Monitoring -> Alerting -> Silences

Implemented in #16978.

juzhao · 2019-09-23T07:58:41Z

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

-. 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.


Filter alerts by name
=>
Filter Alerts by name

Implemented in #16978.

openshift-ci-robot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Sep 19, 2019

rh-max mentioned this pull request Sep 19, 2019

Enterprise 4.2 monitoring metrics ui #16495

Closed

Add the "Examining cluster metrics" section

537db2d

Several fixes and improvements Add a note on running demanding queries

rh-max force-pushed the monitoring-metrics-ui branch from c74d125 to 537db2d Compare September 19, 2019 01:47

jboxman added the branch/enterprise-4.2 label Sep 20, 2019

jboxman added this to the Next Release milestone Sep 20, 2019

jboxman reviewed Sep 20, 2019

View reviewed changes

modules/monitoring-running-metrics-queries.adoc Show resolved Hide resolved

jboxman reviewed Sep 20, 2019

View reviewed changes

jboxman added the peer-review-done Signifies that the peer review team has reviewed this PR label Sep 20, 2019

Add prefix to all images used in monitoring

e2f55ea

rh-max added 2 commits September 20, 2019 12:37

Fix markup for button names

86f61b0

Fix instructions & wording for UI navigation; other small fixes

c2b29f9

Various wording fixes

f4ca1e7

Miniscule stylistic fixes

5ffc634

jboxman merged commit dfa03cd into openshift:master Sep 20, 2019

openshift-cherrypick-robot mentioned this pull request Sep 20, 2019

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

Merged

juzhao reviewed Sep 23, 2019

View reviewed changes

rh-max mentioned this pull request Oct 1, 2019

Implement QE feedback for 4.2 #16978

Merged


		The Metrics page is located in Monitoring -> Metrics of the {product-title} web console.

		image::../images/metrics-screen.png[]


		This section shows and explains the contents of the Metrics UI, a Web interface to Prometheus.

		The Metrics page is located in Monitoring -> Metrics of the {product-title} web console.


		.Procedure

		. Open the OpenShift Container Platform web console and navigate to Monitoring -> Metrics.


		toc::[]

		{product-title} 4 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 provides an extensive overview of the cluster state and enables you to troubleshoot problems.


		.Next steps

		xref:../../monitoring/cluster-monitoring/prometheus-alertmanager-and-grafana.adoc#prometheus-alertmanager-and-grafana[Access the Prometheus, Alertmanager, and Grafana.]

Add the "Examining cluster metrics" section #16752

Add the "Examining cluster metrics" section #16752

Uh oh!

Conversation

rh-max commented Sep 19, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jboxman Sep 20, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jboxman Sep 20, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jboxman commented Sep 20, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

rh-max commented Sep 19, 2019 •

edited

Loading

jboxman Sep 20, 2019 •

edited

Loading

jboxman Sep 20, 2019 •

edited

Loading

jboxman commented Sep 20, 2019 •

edited

Loading