Merge pull request #733 from donbourne/last_minute_spec_items

Last minute spec items

spec/src/main/asciidoc/appendix.adoc

@@ -127,35 +127,38 @@ public class MetricRegistryFactory {
 
 === Migration hints
 
-[[migration-hint-to-20]]
-==== To version 2.0
+[[migration-hint-to-50]]
+==== To version 5.0
 
-===== @Counted
+===== SimpleTimer / @SimplyTimed
 
-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:
+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.
 
-* 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)
+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.
 
-This change has also had an impact on the `Counter` interface to basically follow the above change:
+===== ConcurrentGauge / @ConcurrentGauge
 
-* Modify code which uses `Counter.dec()` to use a `Gauge` or `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.
 
-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:
+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.
 
-* thread.count
-* thread.daemon.count
-* classloader.currentLoadedClass.count
-* thread.max.count
+===== Meter / @Metered
 
-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:
+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.
 
-* 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
+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.
 
 
 

spec/src/main/asciidoc/changelog.adoc

@@ -25,14 +25,21 @@
 [[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 `getStdDev()` method
 
 * Updated MetricRegistry class
 ** Removed `register(String name, T metric)` method
@@ -63,10 +70,71 @@
 ** 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
+** Added Snapshot.PercentileValue inner class
+
+=== 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

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: