From 1c0347237a225c48ee23c3652fef1aafe8cfa511 Mon Sep 17 00:00:00 2001 From: Don Bourne Date: Tue, 23 Aug 2022 13:25:31 -0400 Subject: [PATCH 1/5] updated list of changes and migration tips Signed-off-by: Don Bourne --- spec/src/main/asciidoc/appendix.adoc | 34 ++++++++ spec/src/main/asciidoc/changelog.adoc | 86 +++++++++++++++++-- .../microprofile-metrics-spec.asciidoc | 3 +- 3 files changed, 116 insertions(+), 7 deletions(-) diff --git a/spec/src/main/asciidoc/appendix.adoc b/spec/src/main/asciidoc/appendix.adoc index 49789ed7..0b83bc6e 100644 --- a/spec/src/main/asciidoc/appendix.adoc +++ b/spec/src/main/asciidoc/appendix.adoc @@ -127,6 +127,40 @@ public class MetricRegistryFactory { === Migration hints +[[migration-hint-to-50]] +==== To version 5.0 + +===== SimpleTimer / @SimplyTimed + +The `SimpleTimer` class and `@SimplyTimed` annotation have been removed. This change was made to make it possible to implement the spec using commonly used metrics libraries that lack a similar metric type. + +Use `Timer` class or `@Timer` annotation instead. Alternatively, you can create your own `Gauge` to track the total time and your own `Counter` to track the total number of hits of something you want to time. + +===== ConcurrentGauge / @ConcurrentGauge + +The `ConcurrentGauge` class and `@ConcurrentGauge` annotation have been removed. This change was made to make it possible to implement the spec using commonly used metrics libraries that lack a similar metric type. + +Use `Gauge` class or `@Gauge` annotation instead. A `Gauge` allows you to track a value that may go up or down over time. If you need to track the recent maximum or minimum with precision (as was handled by a `ConcurrentGauge`), create a separate `Gauge` for each of those statistics, in addition to the `Gauge` to track the current value of what you are observing. + +===== Meter / @Metered + +The `Meter` class and `@Metered` annotation have been removed. This change was made to make it possible to implement the spec using commonly used metrics libraries that lack a similar metric type. + +Use `Counter` class or `@Counted` annotation instead. Tools, such as Prometheus, are able to compute the rate of increase of an observed metric over a specified period of time. + +===== Snapshot + +The `Snapshot` class has been modified to avoid restricting the list of percentiles to a fixed set of percentile values. This change was made in anticipation of making the list of percentiles be configurable in the future. As in prior releases, the `Timer` and `Histogram` classes still track the 50th, 75th, 95th, 98th, 99th, and 99.9th percentiles in the corresponding `Snapshot`. + +Use `snapshot.percentileValues()` method, then iterate over the returned array of `PercentileValue` objects to find the value at the specific percentile you're interested in. + +===== Metric names + +The `base_`, `vendor_` and `application_` prefixes for metric names that were used in prior releases have been replaced by a tag named `mp_scope` with value `base`, `vendor`, or `application` (you can also register metrics with custom scopes). + +When using the Prometheus format output from the `/metrics` endpoint, use `metric_name{mp_scope="scopeValue",...}` instead of `scopeValue_metric_name{...}` where `metric_name` is the Prometheus-formatted name of your metric and `scopeValue` is one of `base`, `vendor`, `application` or a custom value. + + [[migration-hint-to-20]] ==== To version 2.0 diff --git a/spec/src/main/asciidoc/changelog.adoc b/spec/src/main/asciidoc/changelog.adoc index 7004d47b..717ce32e 100644 --- a/spec/src/main/asciidoc/changelog.adoc +++ b/spec/src/main/asciidoc/changelog.adoc @@ -25,14 +25,30 @@ [[release_notes_5_0]] == Changes in 5.0 +=== Incompatible Changes +** This release aligns with Jakarta EE 10, so it won’t work with earlier versions of Jakarta or Java EE + === Breaking changes +* Removed SimpleTimer class and SimplyTimed annotation +* Removed ConcurrentGauge class and ConcurrentGauge annotation +* Removed Meter class and Metered annotation +* Removed Metered interface -=== API/SPI Changes * Updated Timer class ** Removed `getFifteenMinuteRate()` method ** Removed `getFiveMinuteRate()` method -** Removed `getMeanMinuteRate()` method +** Removed `getMeanRate()` method +** Removed `getOneMinuteRate()` method +** Removed `getMean()` method +** Removed `getStdDev()` method + +* Updated Histogram class +** Removed `getFifteenMinuteRate()` method +** Removed `getFiveMinuteRate()` method +** Removed `getMeanRate()` method ** Removed `getOneMinuteRate()` method +** Removed `getMean()` method +** Removed `getStdDev()` method * Updated MetricRegistry class ** Removed `register(String name, T metric)` method @@ -63,10 +79,70 @@ ** Removed `getSimpleTimers()` method ** Removed `getSimpleTimers(MetricFilter filter)` method +* Updated DefaultMetadata class +** Removed displayName from constructor +** Removed `getDisplayname()` method +** Removed `displayName()` method + +* Updated Metadata class +** Removed `getDisplayname()` method +** Removed `displayName()` method + +* Updated MetadataBuilder class +** Removed `withDisplayName(String displayName)` method + +* Updated Snapshot class +** Removed `getValue(double quantile)` method +** Removed `getValues()` method +** Removed `get75thPercentile()` method +** Removed `get95thPercentile()` method +** Removed `get98thPercentile()` method +** Removed `get999thPercentile()` method +** Removed `get99thPercentile()` method +** Removed `getMedian()` method +** Removed `getMin()` method +** Removed `getStdDev()` method +** Modified `size()` method to return long +** Modified `getMax()` method to return double + +* Updated Gauge class +** can now only work with types that extend Number + * Updated MetricType class -** Removed `CONCURRENT_GAUGE("concurrent gauge", ConcurrentGauge.class)` enum -** Removed `METERED("meter", Meter.class)` enum -** Removed `SIMPLE_TIMER("simple timer", SimpleTimer.class)` enum +** Removed `CONCURRENT_GAUGE` enum +** Removed `METERED` enum +** Removed `SIMPLE_TIMER` enum + +=== API/SPI Changes +* Updated Snapshot class +** Added `percentileValues()` method + +=== Functional Changes + +* Added concept of custom scopes for metrics (https://github.com/eclipse/microprofile-metrics/issues/677[677]) +** added tagging of all metrics with mp_scope=value +** changed /metrics/base to /metrics?scope=base (https://github.com/eclipse/microprofile-metrics/issues/692[692]) +** changed /metrics/vendor to /metrics?scope=vendor (https://github.com/eclipse/microprofile-metrics/issues/692[692]) +** changed /metrics/application to /metrics?scope=application (https://github.com/eclipse/microprofile-metrics/issues/692[692]) +** added /metrics?scope=myScope for custom scoped metrics (https://github.com/eclipse/microprofile-metrics/issues/677[677]) +** added ability for applications to add metrics to a custom scope (https://github.com/eclipse/microprofile-metrics/issues/677[677]) +** added ability to use custom scope names with @RegistryScope annotation (https://github.com/eclipse/microprofile-metrics/issues/677[677]) +** replaced @RegistryType with @RegistryScope (https://github.com/eclipse/microprofile-metrics/issues/677[677]) + +* Other changes +** removed requirement to convert metrics to base units for Prometheus output +** changed from prepending scope to the metric name to putting the scope in mp_scope tag +** clarified that implementations of /metrics endpoint must support Prometheus text-based exposition format, and may also support OpenMetrics exposition format. (https://github.com/eclipse/microprofile-metrics/issues/678[678]) +** removed JSON format for /metrics output (https://github.com/eclipse/microprofile-metrics/issues/685[685]) +** added restriction to block apps from adding metric IDs with the reserved mp_scope and mp_app tag names (https://github.com/eclipse/microprofile-metrics/issues/700[700]) +** changed _app tag name to mp_app (https://github.com/eclipse/microprofile-metrics/issues/705[705]) +** added mp_scope tag to indicate metric scope +** added configuration recommendations for vendors implementing the API with Micrometer libraries +** added rule that metrics of the same name must all contain the same label set (https://github.com/eclipse/microprofile-metrics/issues/721[721]) +** changed REST.request metric from SimpleTimer to Timer type +** changed the base metrics to be optional (https://github.com/eclipse/microprofile-metrics/issues/680[680]) + + [[release_notes_4_0]] == Changes in 4.0 diff --git a/spec/src/main/asciidoc/microprofile-metrics-spec.asciidoc b/spec/src/main/asciidoc/microprofile-metrics-spec.asciidoc index f73832d9..5a9dfc95 100644 --- a/spec/src/main/asciidoc/microprofile-metrics-spec.asciidoc +++ b/spec/src/main/asciidoc/microprofile-metrics-spec.asciidoc @@ -23,8 +23,7 @@ :doctype: book :license: Apache License v2.0 :source-highlighter: coderay -:authors: Heiko W. Rupp, Raymond Lam, David Chan, Don Bourne, Antonin Stefanutti, Brennan Nichyporuk, Mike Croft, Werner Keil, Jan Martiska -:email: hrupp@redhat.com, lamr@ca.ibm.com, chdavid@ca.ibm.com, dbourne@ca.ibm.com, antonin@stefanutti.fr, brennan.nichyporuk@gmail.com, mike.croft@payara.fish, werner@catmedia.us, jmartisk@redhat.com +:author: The MicroProfile community and its contributors :doctype: book ifdef::backend-pdf[] :pagenums: From b42bbf8e41205ae96763d8e2d53bd46558136505 Mon Sep 17 00:00:00 2001 From: Don Bourne Date: Tue, 23 Aug 2022 13:34:12 -0400 Subject: [PATCH 2/5] corrected change to changelog Signed-off-by: Don Bourne --- spec/src/main/asciidoc/changelog.adoc | 2 -- 1 file changed, 2 deletions(-) diff --git a/spec/src/main/asciidoc/changelog.adoc b/spec/src/main/asciidoc/changelog.adoc index 717ce32e..a39b2c5d 100644 --- a/spec/src/main/asciidoc/changelog.adoc +++ b/spec/src/main/asciidoc/changelog.adoc @@ -39,7 +39,6 @@ ** Removed `getFiveMinuteRate()` method ** Removed `getMeanRate()` method ** Removed `getOneMinuteRate()` method -** Removed `getMean()` method ** Removed `getStdDev()` method * Updated Histogram class @@ -47,7 +46,6 @@ ** Removed `getFiveMinuteRate()` method ** Removed `getMeanRate()` method ** Removed `getOneMinuteRate()` method -** Removed `getMean()` method ** Removed `getStdDev()` method * Updated MetricRegistry class From 93a24cb96bfa35213a8746ed018a07cee51bcc2d Mon Sep 17 00:00:00 2001 From: Don Bourne Date: Tue, 23 Aug 2022 17:35:34 -0400 Subject: [PATCH 3/5] update histogram change list Signed-off-by: Don Bourne --- spec/src/main/asciidoc/changelog.adoc | 7 ------- 1 file changed, 7 deletions(-) diff --git a/spec/src/main/asciidoc/changelog.adoc b/spec/src/main/asciidoc/changelog.adoc index a39b2c5d..6c407ed5 100644 --- a/spec/src/main/asciidoc/changelog.adoc +++ b/spec/src/main/asciidoc/changelog.adoc @@ -41,13 +41,6 @@ ** Removed `getOneMinuteRate()` method ** Removed `getStdDev()` method -* Updated Histogram class -** Removed `getFifteenMinuteRate()` method -** Removed `getFiveMinuteRate()` method -** Removed `getMeanRate()` method -** Removed `getOneMinuteRate()` method -** Removed `getStdDev()` method - * Updated MetricRegistry class ** Removed `register(String name, T metric)` method ** Removed `register(Metadata metadata, T metric)` method From 6c24cb5d17239655ffd52c64dfddec342ec08313 Mon Sep 17 00:00:00 2001 From: Don Bourne Date: Wed, 24 Aug 2022 09:13:24 -0400 Subject: [PATCH 4/5] Removed section on migrating to 2.0, fixed typo Signed-off-by: Don Bourne --- spec/src/main/asciidoc/appendix.adoc | 33 +--------------------------- 1 file changed, 1 insertion(+), 32 deletions(-) diff --git a/spec/src/main/asciidoc/appendix.adoc b/spec/src/main/asciidoc/appendix.adoc index 0b83bc6e..f44460db 100644 --- a/spec/src/main/asciidoc/appendix.adoc +++ b/spec/src/main/asciidoc/appendix.adoc @@ -134,7 +134,7 @@ public class MetricRegistryFactory { The `SimpleTimer` class and `@SimplyTimed` annotation have been removed. This change was made to make it possible to implement the spec using commonly used metrics libraries that lack a similar metric type. -Use `Timer` class or `@Timer` annotation instead. Alternatively, you can create your own `Gauge` to track the total time and your own `Counter` to track the total number of hits of something you want to time. +Use `Timer` class or `@Timed` annotation instead. Alternatively, you can create your own `Gauge` to track the total time and your own `Counter` to track the total number of hits of something you want to time. ===== ConcurrentGauge / @ConcurrentGauge @@ -161,35 +161,4 @@ The `base_`, `vendor_` and `application_` prefixes for metric names that were us When using the Prometheus format output from the `/metrics` endpoint, use `metric_name{mp_scope="scopeValue",...}` instead of `scopeValue_metric_name{...}` where `metric_name` is the Prometheus-formatted name of your metric and `scopeValue` is one of `base`, `vendor`, `application` or a custom value. -[[migration-hint-to-20]] -==== To version 2.0 - -===== @Counted - -The `@Counted` annotation has changed. Users of the previous `@Counted` annotation were surprised to learn that by default counters were not monotonic. Also, the OpenMetrics format expects all counters to be monotonic. -To migrate: - -* Replace `@Counted()` or `@Counted(monotonic=false)` with `@ConcurrentGauge`. -A set of gauges will be created in the OpenMetrics output for each `@ConcurrentGauge`. -* Replace `@Counted(monotonic=true)` with `@Counted` (monotonic flag is gone) - -This change has also had an impact on the `Counter` interface to basically follow the above change: - -* Modify code which uses `Counter.dec()` to use a `Gauge` or `ConcurrentGauge`. - -Some base metrics' types have changed from `Counter` to `Gauge` since counters must now count monotonically. Update code or dashboards that use the following metrics: - -* thread.count -* thread.daemon.count -* classloader.currentLoadedClass.count -* thread.max.count - -Some base metrics' names have changed to follow the convention of ending the name of accumulating counters with `total`. Update code or dashboards that use the following metrics: - -* gc.count -> gc.total -* classloader.currentLoadedClass.count -> classloader.loadedClasses.count (changed to stay consistent with other classloader metric names) -* classloader.totalLoadedClass.count -> classloader.loadedClasses.total -* classloader.totalUnloadedClass.count -> classloader.unloadedClasses.total - - From f4eeb33ce2b4a1fc15bb111a7d417253754d35c5 Mon Sep 17 00:00:00 2001 From: Don Bourne Date: Wed, 24 Aug 2022 14:42:08 -0400 Subject: [PATCH 5/5] added PercentileValue to changelog Signed-off-by: Don Bourne --- spec/src/main/asciidoc/changelog.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/spec/src/main/asciidoc/changelog.adoc b/spec/src/main/asciidoc/changelog.adoc index 6c407ed5..8fcfa5df 100644 --- a/spec/src/main/asciidoc/changelog.adoc +++ b/spec/src/main/asciidoc/changelog.adoc @@ -107,6 +107,7 @@ === API/SPI Changes * Updated Snapshot class ** Added `percentileValues()` method +** Added Snapshot.PercentileValue inner class === Functional Changes