Update mpMetrics guide for mpMetrics-2.0

[donbourne]

Once we have mpMetrics-2.0 support in OL, we need to update the OL guide for metrics to leverage that feature. mpMetrics-2.0 adds multi-dimensional metrics, which is quite transformational in the way people can use metrics, and should be covered in the guide.

[yeekangc]

There is also the need to update the guide to cover new metrics that have since been made available:

• Update the guide for new metrics in 18.0.0.3  guide-microprofile-metrics#50
• Update appropriate guide to show MP Metrics for Fault Tolerance 1.1 #190

As well as what @andymc12 and team will be enabling for JAX-RS.

[evelinec]

After studying the new features/changes in mpMetrics-2.0, the following proposals can be considered for the relevant guides:

1. Apply changes and updates on the existing metrics guide. These are needed if the guide is using the mpMetrics-2.0 feature, otherwise the descriptions/usages are out of date.

• Update the @Timed annotation to track the durations of the annotated method
• Add the @Metered annotation to track the frequency of the annotated method
• May add an explanation on the @Counted annotation about it's only monotonic (counting increments)
• Other things may be good to have:
  • Add vender metric provided by Liberty at /metrics/vender URL (Ref issue Update the guide for new metrics in 18.0.0.3  guide-microprofile-metrics#50 mentioned above)
  • Change the statements of "system metrics" to "base metrics" to match with the /metrics/base URL and actual metrics data

2. The multi-dimensional metrics behaviour using metric tags can be a new guide.

3. The @ConcurrentGauge annotation needs a new scenario to demonstrate its usage, thus also suggest to be shown in a new guide. Can be combined with 2 above.

4. Metrics for Fault Tolerance topic is good to be on a new guide. But it's possible to be added to existing @Fallback guide.

[donbourne]

@evelinec , will people learning mpMetrics be expected to use the existing guide and the new guide? Also, will the existing guide be modified so that it's clear what has changed since mpMetrics-1.x?

[yeekangc]

I believe these would largely be updates to the existing guide, @donbourne. We will show the latest and what we recommend.

For new guide(s), we can look and discuss focus and scope first before we proceed further. +1 that if we have new guides, they need to work together with existing one(s) or build on top of one another.

If information on what's changed/different between 1.x and 2.0, that can go into documentation. https://github.com/OpenLiberty/docs/

We would be open to PRs and suggestions from the team. Tagging @Channyboy too.

[evelinec]

The existing metrics guide is an introductory to MP metrics guide. It uses the @Timed, @Counted and @Gauged annotations since the mpMetrics 1.1. As the new mpMetrics 2.x had changes in some of these annotations, we need to update this guide with those, thus I proposed point number 1.

The other new features in mpMetrics 2.x, ie, multi-dimensional metrics behaviour, and the @ConcurrentGauge annotation, require redesign of the scenario in the current guide. IMO, they may be good for new guide topics. @donbourne @Channyboy Let us know what you think.

Like @yeekangc said, if we have new guides, they will work together with existing one(s) or build on top of one another.

[donbourne]

It's key that if we have a new guide that we update the old one as well to call out cases where things are different between 1.x and 2.x. As long as we keep that in mind, I'm not too opinionated on whether the new content should go in a new guide or whether the old guide should just be reworked to include all of this content.

[yeekangc]

I think we are on the same page on whether it should be updates to existing guide and/or if a new guide should be introduced for more advanced capabilities.

As for the differences between 1.x and 2.x, they should be captured in documentation for Open Liberty if it is needed. I think https://openliberty.io/docs/ref/general/#metrics-catalog.html does this already? And, the team can expand on that if necessary?

The guides do not take the place of what we need to capture in documentation. And, they aren't meant to cover every single detail. Calling out the differences between spec versions shouldn't be a focus for the guides. Moreover, it can make the guides confusing and the learning experience less than ideal particularly for new users.

If the team would like to contribute a guide on moving from 1.x to 2.x for MP Metrics, that is a different story and can be further discussed.

Tagging @lauracowen since we mentioned documentation too.

[lauracowen]

As well as the Metrics catalog (which gives both versions of names), we have https://openliberty.io/blog/2019/07/24/microprofile-metrics-migration.html

[evelinec]

• PR was created with most of the changes (detail description to be added later)
• still deciding on the mutil-dimension tags
• metrics is added to the FT guide, PR was created, pending review

[lauracowen]

I should've added - can the metrics guide link (where appropriate) to the two metrics docs topics?

[gkwan-ibm]

• FT guide is ready to review
• working on the metrics guide

[evelinec]

Summary of actual changes:

Updates on the Metrics guide:

• added Liberty vendor metrics
• updated @Countered annotation description to be counting monotonically upwards
• updated metric outputs where the formats are different, ie, @gauged, @counted and some base metric outputs
• added tags for the @Timed annotation to demonstrate multi-dimension metrics
• PR: Mp metrics2x guide-microprofile-metrics#84

Updates on the Fallback guide:

• added viewing metrics for the fallback methods and showed the outputs
• PR: Add metrics to FT guide guide-microprofile-fallback#97

[gkwan-ibm]

• Danny will do the peer review

[yeekangc]

Did we add the links to the metrics docs as Laura suggested?

Looking at https://github.com/OpenLiberty/guide-microprofile-metrics/tree/mpMetrics2x, I see a link to a KC article on vendor metrics. We should link to what's on openliberty.io.

We can double check with Don and team on what's best. I see https://openliberty.io/docs/ref/general/#microservice_observability_metrics.html and https://openliberty.io/docs/ref/general/#metrics-catalog.html on the site today.

Thank you.

[gkwan-ibm]

• peer review in progress

[evelinec]

Updated the annotation more info link to point to the Java doc link: OpenLiberty/guide-microprofile-metrics@ae33b34.

The link to the KC was added for the Liberty vendor metrics. Perhaps this doc is not available on ol.io yet?

If you have suggestions on where to add the 2 doc links, https://openliberty.io/docs/ref/general/#microservice_observability_metrics.html and https://openliberty.io/docs/ref/general/#metrics-catalog.html, let us know.

[evelinec]

As noted earlier, the PR for this task is OpenLiberty/guide-microprofile-metrics#84. @Channyboy and @donbourne can you help SME review? Thank you.

[gkwan-ibm]

• SME review in progress

[Charlotte-Holt]

Hi, @evelinec - Wanted to add a little input because I worked on some of the metrics topics in OL. I added suggestions to link out to https://openliberty.io/docs/ref/general/#metrics-catalog.html on OpenLiberty/guide-microprofile-metrics#84 and OpenLiberty/guide-microprofile-fallback#97. Let me know if you have any questions!!

[evelinec]

@Charlotte-Holt Thank you for the suggestions. I responded on the PRs. Can you take a look? Thank you.

[Charlotte-Holt]

@evelinec - Thanks! Understood and no issue with your comment in the FT guide PR. I'll see if @donbourne thinks we should update the Metrics reference list for use in the Metrics guide.

[donbourne]

@Charlotte-Holt / @evelinec , what's missing in the metrics reference list that we need to make it suitable for use from the metrics guide?

[yeekangc]

Providing early signoff assuming no further/major issues.

[evelinec]

The PR for this update is completed, reviewed and tested. It cannot be merged yet due to an UI bug: OpenLiberty/guide-microprofile-metrics#91.

[gkwan-ibm]

The guide was published with a workaround. When OpenLiberty/guide-microprofile-metrics#91 is fixed, the workaround will be restored.