Skip to content

Latest commit

 

History

History
377 lines (317 loc) · 27.5 KB

changelog.adoc

File metadata and controls

377 lines (317 loc) · 27.5 KB
Raw

Release Notes

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

  • Updated Timer 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

    • Removed register(Metadata metadata, T metric, Tag…​ tags) method

    • Removed concurrentGauge(String name) method

    • Removed concurrentGauge(String name, Tag…​ tags) method

    • Removed concurrentGauge(MetricID metricID) method

    • Removed concurrentGauge(Metadata metadata) method

    • Removed concurrentGauge(Metadata metadata, Tag…​ tags) method

    • Removed meter(String name) method

    • Removed meter(String name, Tag…​ tags) method

    • Removed meter(MetricID metricID) method

    • Removed meter(Metadata metadata) method

    • Removed meter(Metadata metadata, Tag…​ tags) method

    • Removed simpleTimer(String name) method

    • Removed simpleTimer(String name, Tag…​ tags) method

    • Removed simpleTimer(MetricID metricID) method

    • Removed simpleTimer(Metadata metadata) method

    • Removed simpleTimer(Metadata metadata, Tag…​ tags) method

    • Removed getConcurrentGauge(MetricID metricID) method

    • Removed getConcurrentGauges() method

    • Removed getConcurrentGauges(MetricFilter filter) method

    • Removed getMeter(MetricID metricID) method

    • Removed getMeters() method

    • Removed getMeters(MetricFilter filter) method

    • Removed getSimpleTimer(MetricID metricID) method

    • 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 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 (677)

    • added tagging of all metrics with mp_scope=value

    • changed /metrics/base to /metrics?scope=base (692)

    • changed /metrics/vendor to /metrics?scope=vendor (692)

    • changed /metrics/application to /metrics?scope=application (692)

    • added /metrics?scope=myScope for custom scoped metrics (677)

    • added ability for applications to add metrics to a custom scope (677)

    • added ability to use custom scope names with @RegistryScope annotation (677)

    • replaced @RegistryType with @RegistryScope (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. (678)

    • removed JSON format for /metrics output (685)

    • added restriction to block apps from adding metric IDs with the reserved mp_scope and mp_app tag names (700)

    • changed _app tag name to mp_app (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 (721)

    • changed REST.request metric from SimpleTimer to Timer type

    • changed the base metrics to be optional (680)

Changes in 4.0

Incompatible Changes

  • This release aligns with Jakarta EE 9.1, so it won’t work with earlier versions of Jakarta or Java EE (#639)

Changes in 3.0

Breaking changes

  • Removed everything related to reusability from the API code. All metrics are now considered reusable.

  • CDI producers annotated with @Metric no longer trigger metric registration. If these metrics should be registered, it must be done differently (for example using the MetricRegistry methods)

  • MetricRegistry changed from abstract class to interface

  • Changed Timer.update(long duration, java.util.concurrent.TimeUnit) to Timer.update(java.time.Duration duration)

  • Removed MetadataBuilder.withOptional* methods, the remaining with* methods do accept null value (considered not present) except withName which does not accept null or ""

  • Changed Metadata.getDescription() and Metadata.getUnit() to return String instead of Optional<String> and added Metadata.description() and Metadata.unit() that return Optional<String>

API/SPI Changes

  • Updated dependencies scopes and versions to align with Jakarta EE 8

  • MetricRegistry changed from abstract class to interface

  • Added the MetricRegistry.getType() method

  • Added the MetricRegistry.counter(MetricID) method

  • Added the MetricRegistry.concurrentGauge(MetricID) method

  • Added the MetricRegistry.gauge(String, Object, Function, Tag[]) method

  • Added the MetricRegistry.gauge(MetricID, Object, Function) method

  • Added the MetricRegistry.gauge(Metadata, Object, Function, Tag[]) method

  • Added the MetricRegistry.gauge(String, Supplier, Tag[]) method

  • Added the MetricRegistry.gauge(MetricID, Supplier) method

  • Added the MetricRegistry.gauge(Metadata), Supplier, Tag[]) method

  • Added the MetricRegistry.histogram(MetricID) method

  • Added the MetricRegistry.meter(MetricID) method

  • Added the MetricRegistry.timer(MetricID) method

  • Added the MetricRegistry.simpleTimer(MetricID) method

  • Added the MetricRegistry.getMetric(MetricID) method

  • Added the MetricRegistry.getMetric(MetricID metricID, Class) method

  • Added the MetricRegistry.getCounter(MetricID) method

  • Added the MetricRegistry.getConcurrentGauge(MetricID) method

  • Added the MetricRegistry.getGauge(MetricID) method

  • Added the MetricRegistry.getHistogram(MetricID) method

  • Added the MetricRegistry.getMeter(MetricID) method

  • Added the MetricRegistry.getTimer(MetricID) method

  • Added the MetricRegistry.getSimpleTimer(MetricID) method

  • Added the MetricRegistry.getMetadata(String) method

  • Added the MetricRegistry.getMetrics(MetricFilter) method

  • Added the MetricRegistry.getMetrics(Class, MetricFilter) method

  • Added SimpleTimer.getMinTimeDuration() and SimpleTimer.getMaxTimeDuration() methods which return a java.time.Duration object (#523)

  • Timer class updated (#524)

    • Changed Timer.update(long duration, java.util.concurrent.TimeUnit) to Timer.update(java.time.Duration duration)

    • Added Timer.getElapsedTime() which returns java.time.Duration

  • Removed MetadataBuilder.withOptional* methods

  • Global tags and _app tag are no longer handled automatically by the MetricID class, the implementation is expected to add them by itself, for example during metric export

  • Added the Histogram.getSum() which returns long (#597)

Functional Changes

  • Simple Timer metrics now track the highest and lowest recorded timing duration of the previous completed minute (#523)

  • Timer now exposes total elapsed time duration as a metric value. (#524)

  • Clarified that the existing REST metric REST.request will not monitor and track a REST request to a REST endpoint if an unmapped exception occurs.

  • Introduced a new base REST metric REST.request.unmappedException.total that counts the occurrences of unmapped exceptions for each REST endpoint (#533)

  • Histogram now exposes the total sum of recorded values as a sum value (#597)

    • In JSON format it is exposed as a sum value

    • In OpenMetrics format it is exposed as a sum value under the summary type

  • Timer now exposes the elapsedTime metric value as sum under the summary type in OpenMetrics format (#597)

Specification Changes

  • Removed the concept of reusability

  • CDI producers annotated with @Metric no longer trigger metric registration

  • Clarified how the implementation must handle metrics applied via CDI stereotypes

  • The implementation is required to sanitize Metadata passed by the application in cases when it does not contain an explicit type, but the type is implied by the name of the registration method that is being called.

  • Clarified that the existing REST metric REST.request will not monitor and track a REST request to a REST endpoint if an unmapped exception occurs

  • Introduced a new base REST metric REST.request.unmappedException.total that counts the occurrences of unmapped exceptions for each REST endpoint (#533)

  • Histogram now exposes the total sum of recorded values as a sum value (#597)

    • In JSON format it is exposed as a sum value

    • In OpenMetrics format it is exposed as a sum value under the summary type

  • Timer now exposes the elapsedTime metric value as sum under the summary type in OpenMetrics format (#597)

TCK enhancement

  • Improved TCK - Use newly introduced MetricRegistry methods to retrieve single metrics and avoid use of the getMetrics() and getMetadata() methods

Changes in 2.3

A full list of changes may be found on the MicroProfile Metrics 2.3 Milestone

API/SPI Changes

  • Introduced the simple timer (@SimplyTimed) metric. (#496)

  • Added withOptional* methods to the MetadataBuilder, they don’t fail when null values are passed to them (#464)

  • Added the MetricID.getTagsAsArray() method to the API. (#457)

  • Added the method MetricType.fromClassName (#455)

Functional Changes

  • Introduced a new base metric derived from RESTful stats into the base scope.

    • REST.request : Tracks the total count of requests and total elapsed time spent at the REST endpoint

  • Introduced the simple timer (@SimplyTimed) metric. (#496)

  • The API code no longer requires a correctly configured MP Config implementation to be available at runtime, so it is possible to slim down deployments if MP Config is not necessary (#466)

Specification Changes

  • Introduced a new base metric derived from RESTful stats into the base scope.

    • REST.request : Tracks the total count of requests and total elapsed time spent at the REST endpoint

  • Introduced the simple timer (@SimplyTimed) metric. (#496)

  • Added ProcessCpuTime as a new optional base metric. (#442)

TCK enhancement

  • Improved TCK - Use WebArchive for deployment

Changes in 2.2

A full list of changes may be found on the MicroProfile Metrics 2.2.1 Milestone

API/SPI Changes

  • Reverted a problematic change from 2.1 where Gauges were required to return subclasses of java.lang.Number

Functional Changes

  • Reverted a problematic change from 2.1 where Gauges were required to return subclasses of java.lang.Number

  • (2.2.1) Added ProcessCpuTime as a new optional base metric. (#480)

Specification Changes

  • (2.2.1) Added ProcessCpuTime as a new optional base metric. (#480)

Changes in 2.1

A full list of changes may be found on the MicroProfile Metrics 2.1 Milestone and MicroProfile Metrics 2.1.1 Milestone

API/SPI Changes

  • Clarified in the API code that Gauges must return values that extend java.lang.Number. [NOTE: this caused issues with backward compatibility and was reverted in 2.2] (#304)

  • Added the reusable(boolean) method for MetadataBuilder (#407)

Functional Changes

  • (2.1.1) Added ProcessCpuTime as a new optional base metric. (#454)

  • Clarified in the API code that Gauges must return values that extend java.lang.Number. [NOTE: this caused issues with backward compatibility and was reverted in 2.2] (#304)

  • Clarified that implementations can, for JSON export of scopes containing no metrics, omit them, or that they can be present with an empty value. (#416)

  • Clarified that metrics should not be created for private methods when a class is annotated (the TCK asserted this in 2.0 anyway) (#416)

  • Added the reusable(boolean) method for MetadataBuilder (#407)

Specification Changes

  • (2.1.1) Added ProcessCpuTime as a new optional base metric. (#454)

  • Clarified that metric registry implementations are required to be thread-safe. (#300)

  • Clarified that implementations can, for JSON export of scopes containing no metrics, omit them, or that they can be present with an empty value. (#416)

  • Clarified that metrics should not be created for private methods when a class is annotated (the TCK asserted this in 2.0 anyway) (#416)

  • Added some text to the specification about programmatic creation of metrics (without annotations) (#399)

TCK enhancement

  • TCKs are updated to use RestAssured 4.0

Miscellaneous

  • Explicitly excluded the transitive dependency on jakarta.el-api from the build of the specification. It wasn’t actually used anywhere in the build so there should be no impact. Implementations can still support the Expression Language if they choose to. (#417)

Changes in 2.0

Changes marked with [bolt] are breaking changes relative to previous versions of the spec.

API/SPI Changes

  • [bolt] Refactoring of Counters, as the old @Counted was misleading in practice. (#290)

    • Counters via @Counted are now always monotonic, the monotonic attribute is gone. The Counted interface lost the dec() methods.

    • Former non-monotonic counters are now @ConcurrentGauge and also in the output reported as gauges. (#290)

    • See Migration hints about migration of applications using MicroProfile Metrics. (#290)

  • Removed unnecessary @InterceptorBinding annotation from org.eclipse.microprofile.metrics.annotation.Metric. (#188)

  • [bolt] Removed deprecated org.eclipse.microprofile.metrics.MetricRegistry.register(String name, Metric, Metadata) (#268)

  • [bolt] Metadata is now immutable and built via a MetadataBuilder. (#228)

  • Introduced a Tag object which represents a singular tag key/value pair. (#238)

  • MetricFilter modified to filter with MetricID instead of name. (#238)

Functional Changes

  • (2.0.3) Added ProcessCpuTime as a new optional base metric. (#454)

  • [bolt] Metadata is now immutable and built via a MetadataBuilder. (#228)

  • [bolt] Metrics are now uniquely identified by a MetricID (combination of the metric’s name and tags). (#238)

  • MetricFilter modified to filter with MetricID instead of name. (#238)

  • The 'Metadata' is mapped to a unique metric name in the MetricRegistry and this relationship is immutable. (#238)

  • Tag key names for labels are restricted to match the regex [a-zA-Z_][a-zA-Z0-9_]*. (#238)

  • Tag values defined through MP_METRICS_TAGS must escape equal signs = and commas , with a backslash \. (#238)

  • [bolt] JSON output format for GET requests now appends tags along with the metric in metricName;tag=value;tag=value format. JSON format for OPTIONS requests have been modified such that the 'tags' attribute is a list of nested lists which holds tags from different metrics that are associated with the metadata. (#381)

  • OpenMetrics format - formerly called Prometheus format

    • Reserved characters in OpenMetrics format must be escaped. (#238)

    • [bolt] In OpenMetrics output format, the separator between scope and metric name is now a _ instead of a :. (#279)

    • [bolt] Metric names with camelCase are no longer converted to snake_case for OpenMetrics output. (#357)

  • [bolt] The default value of the reusable attribute for metric objects created programmatically (not via annotations) is now true (#328)

  • [bolt] Some base metrics' names have changed to follow the convention of ending the name of accumulating counters with total. (#375)

  • [bolt] Some base metrics' types have changed from Counter to Gauge since Counters must now count monotonically. (#375)

  • [bolt] Some base metrics' names have changed because they now use tags to distinguish metrics for multiple JVM objects. For example, each existing garbage collector now has its own gc.total metric with the name of the garbage collector being in a tag. Names of some base metrics in the OpenMetrics output are also affected by the removal of conversion from camelCase to snake_case. (#375)

Specification Changes

  • (2.0.3) Added ProcessCpuTime as a new optional base metric. (#454)

  • [bolt] Refactoring of Counters, as the old @Counted was misleading in practice. (#290)

    • Counters via @Counted are now always monotonic, the monotonic attribute is gone. The Counted interface lost the dec() methods.

    • Former non-monotonic counters are now @ConcurrentGauge and also in the output reported as gauges. (#290)

    • See Migration hints about migration of applications using MicroProfile Metrics. (#290)

  • [bolt] Metrics are now uniquely identified by a MetricID (combination of the metric’s name and tags). (#238)

  • The 'Metadata' is mapped to a unique metric name in the MetricRegistry and this relationship is immutable. (#238)

  • Tag key names for labels are restricted to match the regex [a-zA-Z_][a-zA-Z0-9_]*. (#238)

  • Tag values defined through MP_METRICS_TAGS must escape equal signs = and commas , with a backslash \. (#238)

  • OpenMetrics format - formerly called Prometheus format

    • Reserved characters in OpenMetrics format must be escaped. (#238)

    • [bolt] In OpenMetrics output format, the separator between scope and metric name is now a _ instead of a :. (#279)

    • [bolt] Metric names with camelCase are no longer converted to snake_case for OpenMetrics output. (#357)

  • [bolt] The default value of the reusable attribute for metric objects created programmatically (not via annotations) is now true (#328)

  • [bolt] Some base metrics' names have changed to follow the convention of ending the name of accumulating counters with total. (#375)

  • [bolt] Some base metrics' types have changed from Counter to Gauge since Counters must now count monotonically. (#375)

  • [bolt] Some base metrics' names have changed because they now use tags to distinguish metrics for multiple JVM objects. For example, each existing garbage collector now has its own gc.total metric with the name of the garbage collector being in a tag. Names of some base metrics in the OpenMetrics output are also affected by the removal of conversion from camelCase to snake_case. (#375)

  • Added a set of recommendations how application servers with multiple deployed applications should behave if they support MP Metrics. (#240)

Changes in 1.1

A full list of changes may be found on the MicroProfile Metrics 1.1 Milestone

API/SPI Changes

  • org.eclipse.microprofile.metrics.MetricRegistry.register(String name, Metric, Metadata) is deprecated. Use org.eclipse.microprofile.metrics.MetricRegistry.register(Metadata, Metric) instead, where Metadata already has a field for the name.

Functional Changes

  • org.eclipse.microprofile.metrics.MetricRegistry.register(String name, Metric, Metadata) is deprecated. Use org.eclipse.microprofile.metrics.MetricRegistry.register(Metadata, Metric) instead, where Metadata already has a field for the name.

  • Global tags are now supplied via the means of MicroProfile Config (the env variable is still valid). (#165)

Specification Changes

  • Annotations and Metadata can now have a flag reusable that indicates that the metric name can be registered more than once. Default is false as in Metrics 1.0. See architecture.adoc.

TCK enhancement

  • Improved TCK