Introduction topic to metrics with OL

[Charlotte-Holt]

We need a new concept topic that talks about the two kinds of metrics you can use with OL - MicroProfile Metrics and JMX metrics. We already have reference lists for both of these metric types. We also have a dev-focused topic about annotations with MP Metrics. This topic should introduce both types and answer the following questions:

• What are the two types of metrics we have for OL?
• What are the benefits of each?
• Why would you use each?

I previously wrote a short blurb about JMX metrics that didn't fit into any existing metrics topics but is probably high-level enough to be included in this topic, so you can see if it works:

== JMX metrics
In addition to accessing metrics from a `/metrics` endpoint, you can also access Java Management Extensions (JMX) metrics by enabling the link:/docs/ref/feature/#monitor-1.0.html[Performance Monitoring feature].
While the link:/docs/ref/feature/#mpMetrics.html[MicroProfile Metrics feature] provides a `/metrics` REST endpoint that you can use with Prometheus or other web-based tools, the Performance Monitoring feature provides JMX MXBeans that you can use with JConsole or other JMX-based tools.

If you use the Performance Monitoring feature with the MicroProfile Metrics feature, then you get both JMX metrics and `/metrics` endpoint metrics, and the JMX metrics are included in the `/metrics` output.
The MicroProfile Metrics 2.3 feature and later automatically enables the Performance Monitoring feature.
For a list of all JMX metrics that are available for Open Liberty, see the link:/docs/ref/general/#jmx-metrics-list.html[JMX metrics reference list].

=== Enable JMX metrics
You can enable JMX metrics by adding the Performance Monitoring feature to your `server.xml` file.
After you add this feature to your server configuration, monitoring of JMX metrics automatically starts.

After you enable monitoring for Open Liberty, you can use JConsole to connect to the JVM and view performance data by clicking each attribute of the MXBeans.
JConsole is a JVM tool used for viewing monitoring and performance data.
If you prefer, you can choose to use other products that consume JMX metrics to view your metrics information.

[Charlotte-Holt]

@donbourne I know I slacked you, but just wanted to note it here :) This topic is ready for your review: https://draft-openlibertyio.mybluemix.net/docs/20.0.0.9/introduction-monitoring-metrics.html.

Like we talked about:

1. Need to answer the questions "What are the benefits of each?" and "Why would you use each?" in the intro paragraph.
2. Update the table to split out JSON and Prometheus.

[Charlotte-Holt]

@donbourne I updated the topic and fixed the table to only include the metrics that are available by GET request: https://draft-openlibertyio.mybluemix.net/docs/20.0.0.9/introduction-monitoring-metrics.html.

[donbourne]

@Charlotte-Holt , here are my comments...

---

This part needs to also talk about the server component's metrics:

MicroProfile Metrics provides an API for developers to add metrics to their applications. Metrics come in a variety of forms, including counters, gauges, timers, histograms, and meters. You can access MicroProfile Metrics by enabling the MicroProfile Metrics feature. The MicroProfile Metrics feature provides a /metrics REST interface that conforms to the MicroProfile Metrics specification. Real-time values of all metrics are available from a call to the /metrics endpoint. For more information about adding these metrics to your applications, see Microservice observability with metrics. For a list of all REST endpoint-style metrics that are available for Open Liberty, see the Metrics reference list.

suggest:

The MicroProfile Metrics feature provides a /metrics REST interface that conforms to the MicroProfile Metrics specification. Open Liberty uses MicroProfile Metrics to expose metrics describing the internal state of many of its components. Developers can use the MicroProfile Metrics API to expose metrics from their applications as well.

Metrics come in a variety of forms, including counters, gauges, timers, histograms, and meters. You can access MicroProfile Metrics by enabling the MicroProfile Metrics feature. Real-time values of all metrics are available from a call to the /metrics endpoint. For more information about adding these metrics to your applications, see Microservice observability with metrics. For a list of all REST endpoint-style metrics that are available for Open Liberty, see the Metrics reference list.

---

While the MicroProfile Metrics feature provides a /metrics REST endpoint that you can use with Prometheus or other web-based tools

• wondering if this should be removed as it may be clearer not to mention the /metrics endpoint anywhere where we're explaining JMX (to avoid confusion).

---

provides JMX MXBeans that you can use with JConsole. -> provides JMX MXBeans that you can use with monitoring tools that use JMX, such as JConsole.

---

This part feels a bit loose:

If you enable the MicroProfile Metrics feature with the Performance Monitoring feature, then you get both REST endpoint-style metrics and JMX metrics, and the JMX metrics are included in the /metrics output. The MicroProfile Metrics feature version 2.3 and later automatically enables the Performance Monitoring feature.

suggest:

If you enable both the MicroProfile Metrics and Performance Monitoring features, then the JMX MXBeans for monitoring and the /metrics REST endpoint will be activated. In this case, metrics for Open Liberty server components are exposed though both interfaces. The MicroProfile Metrics feature version 2.3 and later automatically enables the Performance Monitoring feature.

---

somehow this topic needs to convey that mp metrics provides basic metrics about the JVM and metrics added to applications using the MP Metrics API, but mp metrics doesn't provide metrics about OL server components unless mp metrics is used in conjunction with Performance Monitoring feature. Perhaps that could be at the start of the "Using both types of metrics" section.

---

intro:

With Open Liberty, you can use two types of metrics to monitor your applications, REST endpoint-style metrics provided by MicroProfile Metrics and JMX metrics.

MicroProfile Metrics can be accessed by monitoring tools such as Prometheus and by any client capable of making REST requests.

JMX metrics are suitable for use by Java-based monitoring tools that can communicate with JMX servers, or by custom JMX clients.

[Charlotte-Holt]

@donbourne Thanks! I've addressed your feedback in the updated draft.

[donbourne]

looks good!

[Charlotte-Holt]

@lauracowen Can you review https://draft-openlibertyio.mybluemix.net/docs/20.0.0.10/introduction-monitoring-metrics.html?

[lauracowen]

Some style things but I'll sign it off:

• [x] Maybe append to the "MicroProfile Metrics" heading "...and the /metrics endpoint"? To be more explicit about what this section is about?
• [x] A more general style question - in the JMX metrics section, it says "...by enabling the Performance Monitoring feature." and I wonder whether it should have "(monitor-1.0)" after the full name? That would tell/remind the reader that they need to enable that feature without them having to go to that topic. I'm not sure that's always relevant to do (eg it probably wouldn't make as much sense in the "Using both types of metrics" section when you are just talking about the features) but in the context of "you need to enable x feature" maybe that would be useful (like Alasdair mentioned in the SPNEGO topic the other day)?
• [x] Don't need "Table 1. " in the caption. I can see value in caption text itself being good for a quick glance to see what they are in online stuff, but don't need to number the figures/tables etc - that's a just hangover from printed documents in which it's not possible for the author to know where the figure will be typeset on the eventually published/printed page. Whereas in online articles, you control exactly where the figure/table goes in the flow of content on the page. (I noticed that the KC has figure/table numbers but on another IBM product, I'm almost certain we stopped doing because it didn't add any value to the pages - esp as topics are relatively short and there's often only one on a page anyway.)
• [x] I wondered whether the title of the topic should start "Introduction to" as many of these topics are intros too and we don't do that?

[donbourne]

...that's a just hangover from printed documents in which it's not possible for the author to know where the figure will be typeset on the eventually published/printed page. Whereas in online articles, you control exactly where the figure/table goes in the flow of content on the page.

... cool history lesson, thanks! :-)

[Charlotte-Holt]

@lauracowen Thx for the review! Updated: https://draft-openlibertyio.mybluemix.net/docs/20.0.0.12/introduction-monitoring-metrics.html. Do you still think the file name is okay (introduction-monitoring-metrics)? Maybe we can talk on Friday about using the code feature name in parentheses in certain contexts - could be an update for the style guide.

[Charlotte-Holt]

Requesting a peer review from @Rwalls1

[Rwalls1]

Peer review

The topic looks good, I just have a few comments:

• I think you should change "Metrics come in various forms, including" to "Metrics come in various forms that include,” in order to use a more active voice by avoiding the gerund
• I think you change “The format that is used for each response depends on the HTTP accept header of the corresponding request.” to use a more active voice by rephrasing as something like “Each response uses a format that depends on the HTTP accept header of the corresponding request.”
• Also to use a more active voice, you can change "Prometheus format is a representation of the metrics” to “Prometheus format represents the metrics"
• I think you should add a noun after “JMX MXBEANS” and “MXBEANS" to avoid possible confusion about its meaning.
• I think you should be more consistent with the naming conventions for the section title, I think they should be either all gerunds or noun phrases
• Also I think, the last section title, “Using both types of metrics” could be more effective and highlight the purpose of using both types of metrics rather than stating the action. So, I think maybe focusing the title on what that action activates would be more effective.
• I think you should remove the phrase "If you prefer," as it seems a bit conversational and instead reword that sentence to state something like "You can also choose...", which is also more concise.

[Charlotte-Holt]

@Rwalls1 Thanks for the review. Feedback addressed:

• [x] I think you should change "Metrics come in various forms, including" to "Metrics come in various forms that include,” in order to use a more active voice by avoiding the gerund
• [x] I think you change “The format that is used for each response depends on the HTTP accept header of the corresponding request.” to use a more active voice by rephrasing as something like “Each response uses a format that depends on the HTTP accept header of the corresponding request.”
• Also to use a more active voice, you can change "Prometheus format is a representation of the metrics” to “Prometheus format represents the metrics" - I think I prefer this sentence as it is, so I'm going to leave it.
• I think you should add a noun after “JMX MXBEANS” and “MXBEANS" to avoid possible confusion about its meaning. - MXBeans is a noun, as I understand it, so leaving this as it is. http://actimem.com/java/jmx/
• [x] I think you should be more consistent with the naming conventions for the section title, I think they should be either all gerunds or noun phrases
• [x] Also I think, the last section title, “Using both types of metrics” could be more effective and highlight the purpose of using both types of metrics rather than stating the action. So, I think maybe focusing the title on what that action activates would be more effective.
• [x] I think you should remove the phrase "If you prefer," as it seems a bit conversational and instead reword that sentence to state something like "You can also choose...", which is also more concise.

[lauracowen]

I just saw this and one thing I'd say about "If you prefer" is that it potentially provides a reason as to why you might also choose something - if that choice literally just comes down to preference. It may not make a difference in this particular situation but conversational is not necessarily a bad thing in the Open Liberty docs - we need to avoid them coming across as really dry and sterile - they need to be appealing to the reader, not just be functional in providing information. There are many reasons you might make a "choice"; a "preference" can be one of those reasons.

I think the comment is probably referring to "If you prefer, you can choose to use other products"? If so, that could be shortened to "If you prefer, you can use other products...." or similar to make it more concise. I'm not saying one is better than the other here - I'll leave the choice to Charlotte. But, in general, there's value in the writing being a little conversational as long as it's not super-wordy or super-colloquial (I agree the docs need to be concise in how things are described etc though).

[Charlotte-Holt]

@chirp1 Updated link: https://draft-openlibertyio.mybluemix.net/docs/20.0.0.12/introduction-monitoring-metrics.html

[Charlotte-Holt]

@chirp1 I'd went through focused on updates relating to the chapters on clarity and concreteness. Some specific updates I made:

• " Open Liberty uses MicroProfile Metrics to expose metrics that describe the internal state of many of its components." --> "Open Liberty uses MicroProfile Metrics to expose metrics that describe the internal state of many Open Liberty components." - DQTI, Chapter 6, Clarity, Use pronouns correctly
• "Real-time values of all metrics are available from a call to the /metrics endpoint." --> "Real-time values of all metrics are available by calling the /metrics endpoint." - DQTI, Chapter 6, Clarity, Eliminate wordiness

[donbourne]

would like to reference this topic to address a customer question at https://groups.io/g/openliberty/topic/78185136 . Can this please be published?

[chirp1]

Hi Charlotte, The topic looks nice! I have a few comments:

• For (mpMetrics-2.3), and other features listed in the topic , although the style guide says to put the feature and number in monospace and in parentheses on first metion, we're not consistent on this point across docs. Also, I think that not having the feature in parentheses would be better. Additional versions can be released for the feature. So, (mpMetrics-2.3) would be incorrect if if tis indicating the latest feature number for the feature.
• Add table numbers. Check the IBM quality guide about tables, and then go to the IBM Style guide that it references in it's table discussion. See the discussion among you, me, and David in slack.
• For respective scope", mentioned twice, I think you mean a different word. Typically, we say "specified" to refer to the term in the first column.
• Change "monitoring tool that’s used to monitor " to "monitoring tool that you can use to monitor ".
• Change "You can also choose to use other products " to "You can also use other products " to reduce wordiness.
• Use terms consistently. The MXBean term seems a little inconsistent.
• For "are exposed though both interfaces ", I think you mean a different word than "though".
• I see "Java Management Extensions (JMX) metrics" twice in the topic, but needs to be there just on first occurrence.

[Charlotte-Holt]

@chirp1 Thanks for the review! I addressed all your feedback as follows:

• [x] For (mpMetrics-2.3), and other features listed in the topic , although the style guide says to put the feature and number in monospace and in parentheses on first mention, we're not consistent on this point across docs. Also, I think that not having the feature in parentheses would be better. Additional versions can be released for the feature. So, (mpMetrics-2.3) would be incorrect if if tis indicating the latest feature number for the feature.
• [ ] Add table numbers. Check the IBM quality guide about tables, and then go to the IBM Style guide that it references in it's table discussion. See the discussion among you, me, and David in slack. - If we decide to do this, I think it should be automatic, rather than manual, so I didn't make this update yet.
• [x] For respective scope", mentioned twice, I think you mean a different word. Typically, we say "specified" to refer to the term in the first column.
• [x] Change "monitoring tool that’s used to monitor " to "monitoring tool that you can use to monitor ".
• [x] Change "You can also choose to use other products " to "You can also use other products " to reduce wordiness.
• [x] Use terms consistently. The MXBean term seems a little inconsistent.
• [x] For "are exposed though both interfaces ", I think you mean a different word than "though".
• [x] I see "Java Management Extensions (JMX) metrics" twice in the topic, but needs to be there just on first occurrence.

[chirp1]

Hi Charlotte, The updates look good and the topic looks nice! As we discussed over slack with David, we don't need "Table 1" on a topic with a single table. I added the "editorial reviewed" label to this issue and am moving the issue to the Ready to Publish column.

[Charlotte-Holt]

Merged to vNext with Karen's edits in #3262