From 1defdad0c93bfd0f6deca7fc16dd41b4090280af Mon Sep 17 00:00:00 2001 From: Channyboy Date: Tue, 10 Oct 2023 17:17:17 -0400 Subject: [PATCH 01/14] Documentation for the new MP Config properties for MP Metrics 5.1 --- .../pages/microprofile-config-properties.adoc | 113 +++++++++++++++++- .../microservice-observability-metrics.adoc | 17 ++- 2 files changed, 126 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/microprofile-config-properties.adoc b/modules/ROOT/pages/microprofile-config-properties.adoc index 0a66278139..a99a899d4d 100644 --- a/modules/ROOT/pages/microprofile-config-properties.adoc +++ b/modules/ROOT/pages/microprofile-config-properties.adoc @@ -1,4 +1,4 @@ -// Copyright (c) 2022 IBM Corporation and others. +// Copyright (c) 2022, 2023 IBM Corporation and others. // Licensed under Creative Commons Attribution-NoDerivatives // 4.0 International (CC BY-ND 4.0) // https://creativecommons.org/licenses/by-nd/4.0/ @@ -251,10 +251,16 @@ The following MicroProfile Config properties can be specified when MicroProfile |`mp.metrics.appName` |Passes the value of the `_app` tag from the application server to the application. This property is used to avoid metric name collisions when multiple applications are deployed to the runtime. It is defined through a `microprofile-config.properties` file in the `META-INF` directory of the application. The value of this tag is appended to the output of each metric that originates from that application. -In MicroProfile 5.0, the `_app` tag that was defined in prior releases by the `mp.metrics.appName` MicroProfile Config property is designated as `mp_app`. +In MicroProfile Metrics 5.0, the `_app` tag that was defined in prior releases by the `mp.metrics.appName` MicroProfile Config property is designated as `mp_app`. When running in an MicroProfile Metrics 5.x environment, if the `mp.metrics.appName` property is defined, the `mp.metrics.defaultAppName` property must be defined as well. |This value is read and evaluated during run time. |`mp.metrics.appName=myApp` +|`mp.metrics.defaultAppName` +|This MP config value is defined on the server level and is used in conjunction with the `mp.metrics.appName` config value when running under a MicroProfile Metrics 5.x environment. The value of `mp.metrics.defaultAppName` passes the value of the `mp_app` tag to metrics created on the server level. There exists vendor metrics (i.e., servlet metrics) that can be created both under the server and application context. Due to restriction introduced in MicroProfile Metrics 5.0 where the set of tag names must be the same, it is important to use the `mp.metrics.defaultAppName` with `mp.metrics.appName` name to avoid any registration exceptions. + +|Server startup +|`mp.metrics.defaultAppName=serverContext` + |`mp.metrics..enabled` |When this property is set to true, it enables a user-provided Micrometer registry implementation, where `` is the name of the Micrometer registry. For more information, see xref:micrometer-metrics.adoc[Choose your own monitoring tools with MicroProfile Metrics]. This property is available starting in MicroProfile Metrics 5.0 . |Server startup @@ -282,6 +288,109 @@ This property is available starting in MicroProfile Metrics 5.0 . |Server startup |`mp.metrics.tags=app=shop,tier=integration,special=deli\=ver\,y` +|`mp.metrics.distribution.percentiles` +a|Specifies a custom set of percentiles for matching Histogram and Timer metrics to track and output. Can be used to disable percentile output. + +* The property accepts a semi-colon separated set of values that consist of a metric name followed by an equals sign (`=`) and comma separated percentile values. +* The asterisk (`*`) can be used as a wildcard at the end of the metric name. +* The percentile values are float values between 0.0 and 1.0 inclusively. Invalid values will be ignored. +* Setting the property with a metric name but no percentile values disables percentile output for that metric. +* Setting the property without any value disables percentiles for all histogram and timer metrics. +* Values defined later take precedence over values before (i.e., right to left precedence). + +This property is available starting in MicroProfile Metrics 5.1. +|Server startup +|`mp.metrics.distribution.percentiles=test.histogram=0.8,0.86,0.95;test.timer=0.9,0.99;test.*=0.5,0.6;other.*=` + +|`mp.metrics.distribution.histogram.buckets` +a| Specifies a custom set of histogram buckets for matching Histogram metrics to track and output. + +* The property accepts a semi-colon separated set of values that consist of a metric name followed by an equals sign (`=`) and comma separated bucket values: +* Accepts a comma separated list of float and integer values greater than 0. +* The asterisk (`*`) can be used as a wildcard at the end of the metric name. +* Defining a metric name with no bucket values or invalid values provides no effect. +* Values defined later take precedence over values before (i.e., right to left precedence). + +This property is available starting in MicroProfile Metrics 5.1. +|Server startup +|`mp.metrics.distribution.histogram.buckets=test.alpha.histogram=10.0,50.0,100.0;test.beta.histogram=30.0,50.0,123` + +|`mp.metrics.distribution.timer.buckets` +a| Specifies a custom set of histogram buckets for matching Timer metrics to track and output. + +* The property accepts a semi-colon separated set of values that consist of a metric name followed by an equals sign (`=`) and comma separated bucket values: +* Accepts a comma separated list of integers with an appended time unit (valid time units are `ms` for milliseconds, `s` for seconds, `m` for minutes and `h` for hours). Float values will not be accepted. Values with no time unit default to milliseconds. +* The asterisk (`*`) can be used as a wildcard at the end of the metric name. +* Defining a metric name with no bucket values or invalid values provides no effect. +* Values defined later take precedence over values before (i.e., right to left precedence). + +This property is available starting in MicroProfile Metrics 5.1. +|Server startup +|`mp.metrics.distribution.timer.buckets=test.*=50s,100s;test.alpha.timer=100,500ms,1s` + +|`mp.metrics.distribution.percentiles-histogram.enabled` +a| Specifies whether the the matching Histogram or Timer metric is to provide a default set of histogram buckets. + +* The property accepts a semi-colon separated set of values that consist of a metric name followed by an equals sign (`=`) and either `true` or `false. +* The asterisk (`*`) can be used as a wildcard at the end of the metric name. +* Defining a metric name with no values or invalid values has no effect. +* Values defined later take precedence over values before (i.e., right to left precedence). + +This property is available starting in MicroProfile Metrics 5.1. +|Server startup +| `mp.metrics.distribution.percentiles-histogram.enabled=test.timer=true;test.histogram=false` + +|`mp.metrics.distribution.histogram.min-value` +a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured for a matching Histogram metric to provide a default set of histogram buckets, this MP config property is used to configure a lower bound for the set of buckets for the matching Histogram metric. + +* The property accepts a semi-colon separated set of values that define a metric name followed by an equals sign (`=`) and a value: +* Properties accept float or integer values greater than 0. +* The asterisk (`*`) can be used as a wildcard at the end of the metric name. +* Defining a metric name with no value or an invalid value provides no effect. +* Values defined later take precedence over values before (i.e., right to left precedence). + +This property is available starting in MicroProfile Metrics 5.1. +|Server startup +| `mp.metrics.distribution.histogram.min-value=test.histogram=50` + +|`mp.metrics.distribution.histogram.max-value` +a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured for a matching Histogram metric to provide a default set of histogram buckets, this MP config property is used to configure an upper bound for the set of buckets for the matching Histogram metric. + +* The property accepts a semi-colon separated set of values that define a metric name followed by an equals sign (`=`) and a value: +* Properties accept float or integer values greater than 0. +* The asterisk (`*`) can be used as a wildcard at the end of the metric name. +* Defining a metric name with no value or an invalid value provides no effect. +* Values defined later take precedence over values before (i.e., right to left precedence). + +This property is available starting in MicroProfile Metrics 5.1. +|Server startup +| `mp.metrics.distribution.histogram.max-value=test.histogram=120` + +|`mp.metrics.distribution.timer.min-value` +a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured for a matching Timer metric to provide a default set of histogram buckets, this MP config property is used to configure a lower bound for the set of buckets for the matching Timer metric. + +* The property accepts a semi-colon separated set of values that define a metric name followed by an equals sign (`=`) and a value: +* Properties accept float or integer values greater than 0. +* The asterisk (`*`) can be used as a wildcard at the end of the metric name. +* Defining a metric name with no value or an invalid value provides no effect. +* Values defined later take precedence over values before (i.e., right to left precedence). + +This property is available starting in MicroProfile Metrics 5.1. +|Server startup +| `mp.metrics.distribution.histogram.min-value=test.timer=200` + +|`mp.metrics.distribution.timer.max-value` +a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured for a matching Timer metric to provide a default set of histogram buckets, this MP config property is used to configure an upper bound for the set of buckets for the matching Timer metric. + +* The property accepts a semi-colon separated set of values that define a metric name followed by an equals sign (`=`) and a value: +* Properties accept float or integer values greater than 0. +* The asterisk (`*`) can be used as a wildcard at the end of the metric name. +* Defining a metric name with no value or an invalid value provides no effect. +* Values defined later take precedence over values before (i.e., right to left precedence). + +This property is available starting in MicroProfile Metrics 5.1. +|Server startup +| `mp.metrics.distribution.histogram.max-value=test.timer=5s` |=== diff --git a/modules/ROOT/pages/microservice-observability-metrics.adoc b/modules/ROOT/pages/microservice-observability-metrics.adoc index d7e6f3a30d..f309d1edc3 100644 --- a/modules/ROOT/pages/microservice-observability-metrics.adoc +++ b/modules/ROOT/pages/microservice-observability-metrics.adoc @@ -137,7 +137,13 @@ public String donateAmountViaCreditCard(@FormParam("amount") Long amount, @FormP } ---- -Starting in MicroProfile Metrics 5.0, you can adjust the percentile precision of the `Timer` metrics by using the `mp.metrics.smallrye.timer.precision` MicroProfile Config property. The property accepts a value from 1 to 5 and is defaulted to 3 if no value is specified. A greater value results in more exact percentile calculations, but at a greater memory cost. For more information, see xref:microprofile-config-properties.adoc#metrics[MicroProfile Config properties: MicroProfile Metrics]. +==== Fine-Tuning with MicroProfile Config properties + +Starting in MicroProfile Metrics 5.0, you can adjust the percentile precision of the `Timer` metrics by using the `mp.metrics.smallrye.timer.precision` MicroProfile Config property. The property accepts a value from 1 to 5 and is defaulted to 3 if no value is specified. A greater value results in more exact percentile calculations, but at a greater memory cost. + +Starting in MicroProfile Metrics 5.1, you can customize the set of percentiles tracked and reported using the `mp.metrics.distribution.percentiles` MicroProfile config property. Additionally, using the `mp.metrics.distribution.timer.buckets` property you can enable a customized set of histogram buckets to be tracked and reported. Alternatively you can use the `mp.metrics.distribution.percentiles-histogram.enabled` to enable a default set of histogram buckets to be tracked and outputted by the Timer metric. + +For more information, see xref:microprofile-config-properties.adoc#metrics[MicroProfile Config properties: MicroProfile Metrics]. [#histogram] @@ -189,7 +195,14 @@ donationDistribution_Dollars_sum{mp_scope="application",tier="integration",} 918 # TYPE donationDistribution_Dollars_max gauge donationDistribution_Dollars_max{mp_scope="application",tier="integration",} 1000.0 ---- -Starting in MicroProfile Metrics 5.0, you can adjust the percentile precision of the `Histogram` metrics by using the `mp.metrics.smallrye.histogram.precision` MicroProfile Config property. The property accepts a value from 1 to 5 and is defaulted to 3 if no value is specified. A greater value results in more exact percentile calculations, but at a greater memory cost. For more information, see xref:microprofile-config-properties.adoc#metrics[MicroProfile Config properties: MicroProfile Metrics]. + +==== Fine-Tuning with MicroProfile Config properties + +Starting in MicroProfile Metrics 5.0, you can adjust the percentile precision of the `Histogram` metrics by using the `mp.metrics.smallrye.histogram.precision` MicroProfile Config property. The property accepts a value from 1 to 5 and is defaulted to 3 if no value is specified. A greater value results in more exact percentile calculations, but at a greater memory cost. + +Starting in MicroProfile Metrics 5.1, you can customize the set of percentiles tracked and reported using the `mp.metrics.distribution.percentiles` MicroProfile config property. Additionally, using the `mp.metrics.distribution.histogram.buckets` property you can enable a customized set of histogram buckets to be tracked and reported. Alternatively you can use the `mp.metrics.distribution.percentiles-histogram.enabled` to enable a default set of histogram buckets to be tracked and outputted by the Histogram metric. + +For more information, see xref:microprofile-config-properties.adoc#metrics[MicroProfile Config properties: MicroProfile Metrics]. In MicroProfile 4.0 and earlier, the following JSON response is also available from the REST endpoints: From 9c73c275cd15d1b762d4cac9da163d32e27ee62c Mon Sep 17 00:00:00 2001 From: David Chan Date: Wed, 11 Oct 2023 16:39:02 -0400 Subject: [PATCH 02/14] Apply suggestions from code review Co-authored-by: David Mueller <48686014+dmuelle@users.noreply.github.com> --- .../pages/microprofile-config-properties.adoc | 58 +++++++++---------- .../microservice-observability-metrics.adoc | 4 +- 2 files changed, 31 insertions(+), 31 deletions(-) diff --git a/modules/ROOT/pages/microprofile-config-properties.adoc b/modules/ROOT/pages/microprofile-config-properties.adoc index a99a899d4d..07dfebee44 100644 --- a/modules/ROOT/pages/microprofile-config-properties.adoc +++ b/modules/ROOT/pages/microprofile-config-properties.adoc @@ -291,12 +291,12 @@ This property is available starting in MicroProfile Metrics 5.0 . |`mp.metrics.distribution.percentiles` a|Specifies a custom set of percentiles for matching Histogram and Timer metrics to track and output. Can be used to disable percentile output. -* The property accepts a semi-colon separated set of values that consist of a metric name followed by an equals sign (`=`) and comma separated percentile values. +* The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and comma-separated percentile values. * The asterisk (`*`) can be used as a wildcard at the end of the metric name. -* The percentile values are float values between 0.0 and 1.0 inclusively. Invalid values will be ignored. +* The percentile values are float values between 0.0 and 1.0, inclusively. Invalid values are ignored. * Setting the property with a metric name but no percentile values disables percentile output for that metric. * Setting the property without any value disables percentiles for all histogram and timer metrics. -* Values defined later take precedence over values before (i.e., right to left precedence). +* Value precedence is right-to-left, so that values that are specified later in the property definition take precedence over previously-specified values. This property is available starting in MicroProfile Metrics 5.1. |Server startup @@ -305,11 +305,11 @@ This property is available starting in MicroProfile Metrics 5.1. |`mp.metrics.distribution.histogram.buckets` a| Specifies a custom set of histogram buckets for matching Histogram metrics to track and output. -* The property accepts a semi-colon separated set of values that consist of a metric name followed by an equals sign (`=`) and comma separated bucket values: -* Accepts a comma separated list of float and integer values greater than 0. +* The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and comma-separated bucket values. +* Accepts a comma-separated list of float and integer values greater than 0. * The asterisk (`*`) can be used as a wildcard at the end of the metric name. -* Defining a metric name with no bucket values or invalid values provides no effect. -* Values defined later take precedence over values before (i.e., right to left precedence). +* Defining a metric name with no bucket values or invalid values has no effect. +Value precedence is right-to-left, so that values that are specified later in the property definition take precedence over previously-specified values. This property is available starting in MicroProfile Metrics 5.1. |Server startup @@ -318,20 +318,20 @@ This property is available starting in MicroProfile Metrics 5.1. |`mp.metrics.distribution.timer.buckets` a| Specifies a custom set of histogram buckets for matching Timer metrics to track and output. -* The property accepts a semi-colon separated set of values that consist of a metric name followed by an equals sign (`=`) and comma separated bucket values: -* Accepts a comma separated list of integers with an appended time unit (valid time units are `ms` for milliseconds, `s` for seconds, `m` for minutes and `h` for hours). Float values will not be accepted. Values with no time unit default to milliseconds. +* The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and comma-separated bucket values. +* The property accepts a comma-separated list of integers with an appended time unit (valid time units are `ms` for milliseconds, `s` for seconds, `m` for minutes and `h` for hours). Float values will not be accepted. Values with no time unit default to milliseconds. * The asterisk (`*`) can be used as a wildcard at the end of the metric name. -* Defining a metric name with no bucket values or invalid values provides no effect. -* Values defined later take precedence over values before (i.e., right to left precedence). +* Defining a metric name with no bucket values or invalid values has no effect. +* Value precedence is right-to-left, so that values that are specified later in the property definition take precedence over previously-specified values. This property is available starting in MicroProfile Metrics 5.1. |Server startup |`mp.metrics.distribution.timer.buckets=test.*=50s,100s;test.alpha.timer=100,500ms,1s` |`mp.metrics.distribution.percentiles-histogram.enabled` -a| Specifies whether the the matching Histogram or Timer metric is to provide a default set of histogram buckets. +a| Specifies whether the the matching histogram or timer metric provides a default set of histogram buckets. -* The property accepts a semi-colon separated set of values that consist of a metric name followed by an equals sign (`=`) and either `true` or `false. +* The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and either `true` or `false. * The asterisk (`*`) can be used as a wildcard at the end of the metric name. * Defining a metric name with no values or invalid values has no effect. * Values defined later take precedence over values before (i.e., right to left precedence). @@ -341,52 +341,52 @@ This property is available starting in MicroProfile Metrics 5.1. | `mp.metrics.distribution.percentiles-histogram.enabled=test.timer=true;test.histogram=false` |`mp.metrics.distribution.histogram.min-value` -a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured for a matching Histogram metric to provide a default set of histogram buckets, this MP config property is used to configure a lower bound for the set of buckets for the matching Histogram metric. +a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a matching histogram metric , this property configures a lower bound for that default set of histogram buckets. -* The property accepts a semi-colon separated set of values that define a metric name followed by an equals sign (`=`) and a value: +* The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and a value. * Properties accept float or integer values greater than 0. * The asterisk (`*`) can be used as a wildcard at the end of the metric name. -* Defining a metric name with no value or an invalid value provides no effect. -* Values defined later take precedence over values before (i.e., right to left precedence). +* Defining a metric name with no value or an invalid value has no effect. +* Value precedence is right-to-left, so that values that are specified later in the property definition take precedence over previously-specified values. This property is available starting in MicroProfile Metrics 5.1. |Server startup | `mp.metrics.distribution.histogram.min-value=test.histogram=50` |`mp.metrics.distribution.histogram.max-value` -a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured for a matching Histogram metric to provide a default set of histogram buckets, this MP config property is used to configure an upper bound for the set of buckets for the matching Histogram metric. +a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a matching histogram metric , this property configures a upper bound for that default set of histogram buckets. -* The property accepts a semi-colon separated set of values that define a metric name followed by an equals sign (`=`) and a value: +* The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and a value: * Properties accept float or integer values greater than 0. * The asterisk (`*`) can be used as a wildcard at the end of the metric name. -* Defining a metric name with no value or an invalid value provides no effect. -* Values defined later take precedence over values before (i.e., right to left precedence). +* Defining a metric name with no value or an invalid value has no effect. +* Value precedence is right-to-left, so that values that are defined later in the property definition take precedence over earlier values. This property is available starting in MicroProfile Metrics 5.1. |Server startup | `mp.metrics.distribution.histogram.max-value=test.histogram=120` |`mp.metrics.distribution.timer.min-value` -a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured for a matching Timer metric to provide a default set of histogram buckets, this MP config property is used to configure a lower bound for the set of buckets for the matching Timer metric. +a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a matching Timer metric , this property configures a lower bound for that default set of histogram buckets. -* The property accepts a semi-colon separated set of values that define a metric name followed by an equals sign (`=`) and a value: +* The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and a value: * Properties accept float or integer values greater than 0. * The asterisk (`*`) can be used as a wildcard at the end of the metric name. -* Defining a metric name with no value or an invalid value provides no effect. -* Values defined later take precedence over values before (i.e., right to left precedence). +* Defining a metric name with no value or an invalid value has no effect. +* Value precedence is right-to-left, so that values that are specified later in the property definition take precedence over previously-specified values. This property is available starting in MicroProfile Metrics 5.1. |Server startup | `mp.metrics.distribution.histogram.min-value=test.timer=200` |`mp.metrics.distribution.timer.max-value` -a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured for a matching Timer metric to provide a default set of histogram buckets, this MP config property is used to configure an upper bound for the set of buckets for the matching Timer metric. +a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a matching Timer metric , this property configures an upper bound for that default set of histogram buckets. -* The property accepts a semi-colon separated set of values that define a metric name followed by an equals sign (`=`) and a value: +* The property accepts a semicolon-separated set of values that define a metric name followed by an equals sign (`=`) and a value: * Properties accept float or integer values greater than 0. * The asterisk (`*`) can be used as a wildcard at the end of the metric name. -* Defining a metric name with no value or an invalid value provides no effect. -* Values defined later take precedence over values before (i.e., right to left precedence). +* Defining a metric name with no value or an invalid value has no effect. +* Value precedence is right-to-left, so that values that are specified later in the property definition take precedence over previously-specified values. This property is available starting in MicroProfile Metrics 5.1. |Server startup diff --git a/modules/ROOT/pages/microservice-observability-metrics.adoc b/modules/ROOT/pages/microservice-observability-metrics.adoc index f309d1edc3..2d2f03ed82 100644 --- a/modules/ROOT/pages/microservice-observability-metrics.adoc +++ b/modules/ROOT/pages/microservice-observability-metrics.adoc @@ -141,7 +141,7 @@ public String donateAmountViaCreditCard(@FormParam("amount") Long amount, @FormP Starting in MicroProfile Metrics 5.0, you can adjust the percentile precision of the `Timer` metrics by using the `mp.metrics.smallrye.timer.precision` MicroProfile Config property. The property accepts a value from 1 to 5 and is defaulted to 3 if no value is specified. A greater value results in more exact percentile calculations, but at a greater memory cost. -Starting in MicroProfile Metrics 5.1, you can customize the set of percentiles tracked and reported using the `mp.metrics.distribution.percentiles` MicroProfile config property. Additionally, using the `mp.metrics.distribution.timer.buckets` property you can enable a customized set of histogram buckets to be tracked and reported. Alternatively you can use the `mp.metrics.distribution.percentiles-histogram.enabled` to enable a default set of histogram buckets to be tracked and outputted by the Timer metric. +Starting in MicroProfile Metrics 5.1, you can customize the set of percentiles that are tracked and reported by using the `mp.metrics.distribution.percentiles` MicroProfile config property. You can also usie the `mp.metrics.distribution.timer.buckets` property to enable a customized set of histogram buckets to be tracked and reported. Alternatively, you can use the `mp.metrics.distribution.percentiles-histogram.enabled` property to enable the timer metric to output and track a default set of histogram buckets. For more information, see xref:microprofile-config-properties.adoc#metrics[MicroProfile Config properties: MicroProfile Metrics]. @@ -200,7 +200,7 @@ donationDistribution_Dollars_max{mp_scope="application",tier="integration",} 100 Starting in MicroProfile Metrics 5.0, you can adjust the percentile precision of the `Histogram` metrics by using the `mp.metrics.smallrye.histogram.precision` MicroProfile Config property. The property accepts a value from 1 to 5 and is defaulted to 3 if no value is specified. A greater value results in more exact percentile calculations, but at a greater memory cost. -Starting in MicroProfile Metrics 5.1, you can customize the set of percentiles tracked and reported using the `mp.metrics.distribution.percentiles` MicroProfile config property. Additionally, using the `mp.metrics.distribution.histogram.buckets` property you can enable a customized set of histogram buckets to be tracked and reported. Alternatively you can use the `mp.metrics.distribution.percentiles-histogram.enabled` to enable a default set of histogram buckets to be tracked and outputted by the Histogram metric. +Starting in MicroProfile Metrics 5.1, you can customize the set of percentiles that are tracked and reported by using the `mp.metrics.distribution.percentiles` MicroProfile config property. You can also usie the `mp.metrics.distribution.histogram.buckets` property to enable a customized set of histogram buckets to be tracked and reported. Alternatively, you can use the `mp.metrics.distribution.percentiles-histogram.enabled` property to enable the histogram metric to output and track a default set of histogram buckets. For more information, see xref:microprofile-config-properties.adoc#metrics[MicroProfile Config properties: MicroProfile Metrics]. From 5b85ad030754b438da2db2419a234b9df37a6fde Mon Sep 17 00:00:00 2001 From: David Chan Date: Mon, 16 Oct 2023 16:02:29 -0400 Subject: [PATCH 03/14] Apply suggestions from code review Co-authored-by: David Mueller <48686014+dmuelle@users.noreply.github.com> --- modules/ROOT/pages/microprofile-config-properties.adoc | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/microprofile-config-properties.adoc b/modules/ROOT/pages/microprofile-config-properties.adoc index 07dfebee44..513c61204c 100644 --- a/modules/ROOT/pages/microprofile-config-properties.adoc +++ b/modules/ROOT/pages/microprofile-config-properties.adoc @@ -251,12 +251,14 @@ The following MicroProfile Config properties can be specified when MicroProfile |`mp.metrics.appName` |Passes the value of the `_app` tag from the application server to the application. This property is used to avoid metric name collisions when multiple applications are deployed to the runtime. It is defined through a `microprofile-config.properties` file in the `META-INF` directory of the application. The value of this tag is appended to the output of each metric that originates from that application. -In MicroProfile Metrics 5.0, the `_app` tag that was defined in prior releases by the `mp.metrics.appName` MicroProfile Config property is designated as `mp_app`. When running in an MicroProfile Metrics 5.x environment, if the `mp.metrics.appName` property is defined, the `mp.metrics.defaultAppName` property must be defined as well. +In MicroProfile Metrics 5.0 and later, the `_app` tag that is defined in prior releases by the `mp.metrics.appName` MicroProfile Config property is designated as `mp_app`. In a MicroProfile Metrics 5.x environment, if the `mp.metrics.appName` property is defined, you must also define the `mp.metrics.defaultAppName` property. See the `mp.metrics.defaultAppName` property description for more information. |This value is read and evaluated during run time. |`mp.metrics.appName=myApp` |`mp.metrics.defaultAppName` -|This MP config value is defined on the server level and is used in conjunction with the `mp.metrics.appName` config value when running under a MicroProfile Metrics 5.x environment. The value of `mp.metrics.defaultAppName` passes the value of the `mp_app` tag to metrics created on the server level. There exists vendor metrics (i.e., servlet metrics) that can be created both under the server and application context. Due to restriction introduced in MicroProfile Metrics 5.0 where the set of tag names must be the same, it is important to use the `mp.metrics.defaultAppName` with `mp.metrics.appName` name to avoid any registration exceptions. +|The value for this property is defined at the server level and is used in conjunction with the `mp.metrics.appName` property when you run in a MicroProfile Metrics 5.x environment. The value of the `mp.metrics.defaultAppName` property passes the value of the `mp_app` tag to metrics that are created on the server level. + +This property is necessary to use with the `mp.metrics.appName` property due to the restriction introduced in MicroProfile Metrics 5 .0 that metrics of the same name must contain the same set of tag names. Certain vendor metrics, such as servlet metrics, can create metrics in both the application and server context. The `mp.metrics.appName` property creates the `mp_app` tag for the servlet metrics that are created in the application context. However, without a similar tag value provided for servlet metrics that are created in the server context, a registration exception is thrown. The `mp.metrics.defaultAppName` property that is defined at the server level provides the necessary `mp_app` tag for metrics that are created at the server level. |Server startup |`mp.metrics.defaultAppName=serverContext` @@ -289,7 +291,7 @@ This property is available starting in MicroProfile Metrics 5.0 . |`mp.metrics.tags=app=shop,tier=integration,special=deli\=ver\,y` |`mp.metrics.distribution.percentiles` -a|Specifies a custom set of percentiles for matching Histogram and Timer metrics to track and output. Can be used to disable percentile output. +a|Specifies a list of metric names that are paired with custom sets of percentiles for the metric to track and output. This property is applicable only to histogram and timer metrics. * The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and comma-separated percentile values. * The asterisk (`*`) can be used as a wildcard at the end of the metric name. @@ -303,7 +305,7 @@ This property is available starting in MicroProfile Metrics 5.1. |`mp.metrics.distribution.percentiles=test.histogram=0.8,0.86,0.95;test.timer=0.9,0.99;test.*=0.5,0.6;other.*=` |`mp.metrics.distribution.histogram.buckets` -a| Specifies a custom set of histogram buckets for matching Histogram metrics to track and output. +a| Specifies a list of metric names that are paired with custom sets of histogram buckets for the metric to track and output. This property is applicable only to histogram metrics. * The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and comma-separated bucket values. * Accepts a comma-separated list of float and integer values greater than 0. From 5318a8c3e614f27f93c56ac0517a6d989092e529 Mon Sep 17 00:00:00 2001 From: Channyboy Date: Mon, 16 Oct 2023 16:13:48 -0400 Subject: [PATCH 04/14] Update text to match batch suggestions --- .../ROOT/pages/microprofile-config-properties.adoc | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/modules/ROOT/pages/microprofile-config-properties.adoc b/modules/ROOT/pages/microprofile-config-properties.adoc index 513c61204c..c1094af6ac 100644 --- a/modules/ROOT/pages/microprofile-config-properties.adoc +++ b/modules/ROOT/pages/microprofile-config-properties.adoc @@ -258,7 +258,7 @@ In MicroProfile Metrics 5.0 and later, the `_app` tag that is defined in prior |`mp.metrics.defaultAppName` |The value for this property is defined at the server level and is used in conjunction with the `mp.metrics.appName` property when you run in a MicroProfile Metrics 5.x environment. The value of the `mp.metrics.defaultAppName` property passes the value of the `mp_app` tag to metrics that are created on the server level. -This property is necessary to use with the `mp.metrics.appName` property due to the restriction introduced in MicroProfile Metrics 5 .0 that metrics of the same name must contain the same set of tag names. Certain vendor metrics, such as servlet metrics, can create metrics in both the application and server context. The `mp.metrics.appName` property creates the `mp_app` tag for the servlet metrics that are created in the application context. However, without a similar tag value provided for servlet metrics that are created in the server context, a registration exception is thrown. The `mp.metrics.defaultAppName` property that is defined at the server level provides the necessary `mp_app` tag for metrics that are created at the server level. +This property is necessary to use with the `mp.metrics.appName` property due to the restriction introduced in MicroProfile Metrics 5.0 that metrics of the same name must contain the same set of tag names. Certain vendor metrics, such as servlet metrics, can create metrics in both the application and server context. The `mp.metrics.appName` property creates the `mp_app` tag for the servlet metrics that are created in the application context. However, without a similar tag value provided for servlet metrics that are created in the server context, a registration exception is thrown. The `mp.metrics.defaultAppName` property that is defined at the server level provides the necessary `mp_app` tag for metrics that are created at the server level. |Server startup |`mp.metrics.defaultAppName=serverContext` @@ -318,7 +318,7 @@ This property is available starting in MicroProfile Metrics 5.1. |`mp.metrics.distribution.histogram.buckets=test.alpha.histogram=10.0,50.0,100.0;test.beta.histogram=30.0,50.0,123` |`mp.metrics.distribution.timer.buckets` -a| Specifies a custom set of histogram buckets for matching Timer metrics to track and output. +a| Specifies a list of metric names that are paired with custom sets of histogram buckets for the metric to track and output. This property is applicable only to timer metrics. * The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and comma-separated bucket values. * The property accepts a comma-separated list of integers with an appended time unit (valid time units are `ms` for milliseconds, `s` for seconds, `m` for minutes and `h` for hours). Float values will not be accepted. Values with no time unit default to milliseconds. @@ -331,7 +331,7 @@ This property is available starting in MicroProfile Metrics 5.1. |`mp.metrics.distribution.timer.buckets=test.*=50s,100s;test.alpha.timer=100,500ms,1s` |`mp.metrics.distribution.percentiles-histogram.enabled` -a| Specifies whether the the matching histogram or timer metric provides a default set of histogram buckets. +a| Specifies a list of metric names that are paired with a true or false value. This property is applicable only to histogram and timer metrics. If set to true, then the metric will output a default set of histogram buckets. * The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and either `true` or `false. * The asterisk (`*`) can be used as a wildcard at the end of the metric name. @@ -343,7 +343,7 @@ This property is available starting in MicroProfile Metrics 5.1. | `mp.metrics.distribution.percentiles-histogram.enabled=test.timer=true;test.histogram=false` |`mp.metrics.distribution.histogram.min-value` -a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a matching histogram metric , this property configures a lower bound for that default set of histogram buckets. +a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a histogram metric, this property configures a lower bound for that default set of histogram buckets. * The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and a value. * Properties accept float or integer values greater than 0. @@ -356,7 +356,7 @@ This property is available starting in MicroProfile Metrics 5.1. | `mp.metrics.distribution.histogram.min-value=test.histogram=50` |`mp.metrics.distribution.histogram.max-value` -a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a matching histogram metric , this property configures a upper bound for that default set of histogram buckets. +a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a histogram metric , this property configures a upper bound for that default set of histogram buckets. * The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and a value: * Properties accept float or integer values greater than 0. @@ -369,7 +369,7 @@ This property is available starting in MicroProfile Metrics 5.1. | `mp.metrics.distribution.histogram.max-value=test.histogram=120` |`mp.metrics.distribution.timer.min-value` -a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a matching Timer metric , this property configures a lower bound for that default set of histogram buckets. +a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a timer metric , this property configures a lower bound for that default set of histogram buckets. * The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and a value: * Properties accept float or integer values greater than 0. @@ -382,7 +382,7 @@ This property is available starting in MicroProfile Metrics 5.1. | `mp.metrics.distribution.histogram.min-value=test.timer=200` |`mp.metrics.distribution.timer.max-value` -a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a matching Timer metric , this property configures an upper bound for that default set of histogram buckets. +a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a timer metric , this property configures an upper bound for that default set of histogram buckets. * The property accepts a semicolon-separated set of values that define a metric name followed by an equals sign (`=`) and a value: * Properties accept float or integer values greater than 0. From 7d831ec093e6ac91f5826ad5632797ec7d77a71b Mon Sep 17 00:00:00 2001 From: Channyboy Date: Mon, 16 Oct 2023 16:14:38 -0400 Subject: [PATCH 05/14] Add statement about performance degredation --- modules/ROOT/pages/microservice-observability-metrics.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/microservice-observability-metrics.adoc b/modules/ROOT/pages/microservice-observability-metrics.adoc index 2d2f03ed82..64fa771857 100644 --- a/modules/ROOT/pages/microservice-observability-metrics.adoc +++ b/modules/ROOT/pages/microservice-observability-metrics.adoc @@ -141,7 +141,7 @@ public String donateAmountViaCreditCard(@FormParam("amount") Long amount, @FormP Starting in MicroProfile Metrics 5.0, you can adjust the percentile precision of the `Timer` metrics by using the `mp.metrics.smallrye.timer.precision` MicroProfile Config property. The property accepts a value from 1 to 5 and is defaulted to 3 if no value is specified. A greater value results in more exact percentile calculations, but at a greater memory cost. -Starting in MicroProfile Metrics 5.1, you can customize the set of percentiles that are tracked and reported by using the `mp.metrics.distribution.percentiles` MicroProfile config property. You can also usie the `mp.metrics.distribution.timer.buckets` property to enable a customized set of histogram buckets to be tracked and reported. Alternatively, you can use the `mp.metrics.distribution.percentiles-histogram.enabled` property to enable the timer metric to output and track a default set of histogram buckets. +Starting in MicroProfile Metrics 5.1, you can customize the set of percentiles that are tracked and reported by using the `mp.metrics.distribution.percentiles` MicroProfile config property. You can also use the `mp.metrics.distribution.timer.buckets` property to enable a customized set of histogram buckets to be tracked and reported. Alternatively, you can use the `mp.metrics.distribution.percentiles-histogram.enabled` property to enable the timer metric to output and track a default set of histogram buckets. Note that there may be a performance decrease if a large set of buckets are enabled for numerous histogram and/or timer metrics. For more information, see xref:microprofile-config-properties.adoc#metrics[MicroProfile Config properties: MicroProfile Metrics]. @@ -200,7 +200,7 @@ donationDistribution_Dollars_max{mp_scope="application",tier="integration",} 100 Starting in MicroProfile Metrics 5.0, you can adjust the percentile precision of the `Histogram` metrics by using the `mp.metrics.smallrye.histogram.precision` MicroProfile Config property. The property accepts a value from 1 to 5 and is defaulted to 3 if no value is specified. A greater value results in more exact percentile calculations, but at a greater memory cost. -Starting in MicroProfile Metrics 5.1, you can customize the set of percentiles that are tracked and reported by using the `mp.metrics.distribution.percentiles` MicroProfile config property. You can also usie the `mp.metrics.distribution.histogram.buckets` property to enable a customized set of histogram buckets to be tracked and reported. Alternatively, you can use the `mp.metrics.distribution.percentiles-histogram.enabled` property to enable the histogram metric to output and track a default set of histogram buckets. +Starting in MicroProfile Metrics 5.1, you can customize the set of percentiles that are tracked and reported by using the `mp.metrics.distribution.percentiles` MicroProfile config property. You can also use the `mp.metrics.distribution.histogram.buckets` property to enable a customized set of histogram buckets to be tracked and reported. Alternatively, you can use the `mp.metrics.distribution.percentiles-histogram.enabled` property to enable the histogram metric to output and track a default set of histogram buckets. Note that there may be a performance decrease if a large set of buckets are enabled for numerous histogram and/or timer metrics. For more information, see xref:microprofile-config-properties.adoc#metrics[MicroProfile Config properties: MicroProfile Metrics]. From 69b6bfcccb92566866280dc98f1acae0ba2967b2 Mon Sep 17 00:00:00 2001 From: David Mueller <48686014+dmuelle@users.noreply.github.com> Date: Tue, 17 Oct 2023 13:46:35 -0400 Subject: [PATCH 06/14] Update modules/ROOT/pages/microprofile-config-properties.adoc --- modules/ROOT/pages/microprofile-config-properties.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/microprofile-config-properties.adoc b/modules/ROOT/pages/microprofile-config-properties.adoc index c1094af6ac..4e90c5223d 100644 --- a/modules/ROOT/pages/microprofile-config-properties.adoc +++ b/modules/ROOT/pages/microprofile-config-properties.adoc @@ -331,7 +331,7 @@ This property is available starting in MicroProfile Metrics 5.1. |`mp.metrics.distribution.timer.buckets=test.*=50s,100s;test.alpha.timer=100,500ms,1s` |`mp.metrics.distribution.percentiles-histogram.enabled` -a| Specifies a list of metric names that are paired with a true or false value. This property is applicable only to histogram and timer metrics. If set to true, then the metric will output a default set of histogram buckets. +a| Specifies a list of metric names that are paired with a true or false value. This property is applicable only to histogram and timer metrics. If set to true, the metric outputs a default set of histogram buckets. * The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and either `true` or `false. * The asterisk (`*`) can be used as a wildcard at the end of the metric name. From 9e59cef0f74e8f09532dfa77bdde8a36c5680e44 Mon Sep 17 00:00:00 2001 From: David Mueller <48686014+dmuelle@users.noreply.github.com> Date: Tue, 17 Oct 2023 13:46:43 -0400 Subject: [PATCH 07/14] Update modules/ROOT/pages/microprofile-config-properties.adoc --- modules/ROOT/pages/microprofile-config-properties.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/microprofile-config-properties.adoc b/modules/ROOT/pages/microprofile-config-properties.adoc index 4e90c5223d..ba0d4a0441 100644 --- a/modules/ROOT/pages/microprofile-config-properties.adoc +++ b/modules/ROOT/pages/microprofile-config-properties.adoc @@ -356,7 +356,7 @@ This property is available starting in MicroProfile Metrics 5.1. | `mp.metrics.distribution.histogram.min-value=test.histogram=50` |`mp.metrics.distribution.histogram.max-value` -a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a histogram metric , this property configures a upper bound for that default set of histogram buckets. +a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a histogram metric, this property configures a upper bound for that default set of histogram buckets. * The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and a value: * Properties accept float or integer values greater than 0. From c0d01c9fc888f088d8ea19f6a8b05f7f0de383a4 Mon Sep 17 00:00:00 2001 From: David Mueller <48686014+dmuelle@users.noreply.github.com> Date: Tue, 17 Oct 2023 13:46:50 -0400 Subject: [PATCH 08/14] Update modules/ROOT/pages/microprofile-config-properties.adoc --- modules/ROOT/pages/microprofile-config-properties.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/microprofile-config-properties.adoc b/modules/ROOT/pages/microprofile-config-properties.adoc index ba0d4a0441..527f53161f 100644 --- a/modules/ROOT/pages/microprofile-config-properties.adoc +++ b/modules/ROOT/pages/microprofile-config-properties.adoc @@ -369,7 +369,7 @@ This property is available starting in MicroProfile Metrics 5.1. | `mp.metrics.distribution.histogram.max-value=test.histogram=120` |`mp.metrics.distribution.timer.min-value` -a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a timer metric , this property configures a lower bound for that default set of histogram buckets. +a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a timer metric, this property configures a lower bound for that default set of histogram buckets. * The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and a value: * Properties accept float or integer values greater than 0. From 0d22c2b1d730c3452f27988bb861c81bf0aaa827 Mon Sep 17 00:00:00 2001 From: David Mueller <48686014+dmuelle@users.noreply.github.com> Date: Tue, 17 Oct 2023 13:46:57 -0400 Subject: [PATCH 09/14] Update modules/ROOT/pages/microprofile-config-properties.adoc --- modules/ROOT/pages/microprofile-config-properties.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/microprofile-config-properties.adoc b/modules/ROOT/pages/microprofile-config-properties.adoc index 527f53161f..ca8921944a 100644 --- a/modules/ROOT/pages/microprofile-config-properties.adoc +++ b/modules/ROOT/pages/microprofile-config-properties.adoc @@ -382,7 +382,7 @@ This property is available starting in MicroProfile Metrics 5.1. | `mp.metrics.distribution.histogram.min-value=test.timer=200` |`mp.metrics.distribution.timer.max-value` -a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a timer metric , this property configures an upper bound for that default set of histogram buckets. +a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a timer metric, this property configures an upper bound for that default set of histogram buckets. * The property accepts a semicolon-separated set of values that define a metric name followed by an equals sign (`=`) and a value: * Properties accept float or integer values greater than 0. From b7468ca9737e2948ed7203cc61eb177c664472d5 Mon Sep 17 00:00:00 2001 From: David Mueller <48686014+dmuelle@users.noreply.github.com> Date: Tue, 17 Oct 2023 13:47:27 -0400 Subject: [PATCH 10/14] Update modules/ROOT/pages/microservice-observability-metrics.adoc --- modules/ROOT/pages/microservice-observability-metrics.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/microservice-observability-metrics.adoc b/modules/ROOT/pages/microservice-observability-metrics.adoc index 64fa771857..ca8973d8b4 100644 --- a/modules/ROOT/pages/microservice-observability-metrics.adoc +++ b/modules/ROOT/pages/microservice-observability-metrics.adoc @@ -141,7 +141,7 @@ public String donateAmountViaCreditCard(@FormParam("amount") Long amount, @FormP Starting in MicroProfile Metrics 5.0, you can adjust the percentile precision of the `Timer` metrics by using the `mp.metrics.smallrye.timer.precision` MicroProfile Config property. The property accepts a value from 1 to 5 and is defaulted to 3 if no value is specified. A greater value results in more exact percentile calculations, but at a greater memory cost. -Starting in MicroProfile Metrics 5.1, you can customize the set of percentiles that are tracked and reported by using the `mp.metrics.distribution.percentiles` MicroProfile config property. You can also use the `mp.metrics.distribution.timer.buckets` property to enable a customized set of histogram buckets to be tracked and reported. Alternatively, you can use the `mp.metrics.distribution.percentiles-histogram.enabled` property to enable the timer metric to output and track a default set of histogram buckets. Note that there may be a performance decrease if a large set of buckets are enabled for numerous histogram and/or timer metrics. +Starting in MicroProfile Metrics 5.1, you can customize the set of percentiles that are tracked and reported by using the `mp.metrics.distribution.percentiles` MicroProfile config property. You can also use the `mp.metrics.distribution.timer.buckets` property to enable a customized set of histogram buckets to be tracked and reported. Alternatively, you can use the `mp.metrics.distribution.percentiles-histogram.enabled` property to enable the timer metric to output and track a default set of histogram buckets. Performance might decrease if a large set of buckets are enabled for numerous histogram or timer metrics. For more information, see xref:microprofile-config-properties.adoc#metrics[MicroProfile Config properties: MicroProfile Metrics]. From 3c4e881bfc55a962a2e2b59d9babc5bd5dd47af7 Mon Sep 17 00:00:00 2001 From: David Mueller <48686014+dmuelle@users.noreply.github.com> Date: Tue, 17 Oct 2023 13:47:54 -0400 Subject: [PATCH 11/14] Update modules/ROOT/pages/microservice-observability-metrics.adoc --- modules/ROOT/pages/microservice-observability-metrics.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/microservice-observability-metrics.adoc b/modules/ROOT/pages/microservice-observability-metrics.adoc index ca8973d8b4..391658238c 100644 --- a/modules/ROOT/pages/microservice-observability-metrics.adoc +++ b/modules/ROOT/pages/microservice-observability-metrics.adoc @@ -200,7 +200,7 @@ donationDistribution_Dollars_max{mp_scope="application",tier="integration",} 100 Starting in MicroProfile Metrics 5.0, you can adjust the percentile precision of the `Histogram` metrics by using the `mp.metrics.smallrye.histogram.precision` MicroProfile Config property. The property accepts a value from 1 to 5 and is defaulted to 3 if no value is specified. A greater value results in more exact percentile calculations, but at a greater memory cost. -Starting in MicroProfile Metrics 5.1, you can customize the set of percentiles that are tracked and reported by using the `mp.metrics.distribution.percentiles` MicroProfile config property. You can also use the `mp.metrics.distribution.histogram.buckets` property to enable a customized set of histogram buckets to be tracked and reported. Alternatively, you can use the `mp.metrics.distribution.percentiles-histogram.enabled` property to enable the histogram metric to output and track a default set of histogram buckets. Note that there may be a performance decrease if a large set of buckets are enabled for numerous histogram and/or timer metrics. +Starting in MicroProfile Metrics 5.1, you can customize the set of percentiles that are tracked and reported by using the `mp.metrics.distribution.percentiles` MicroProfile config property. You can also use the `mp.metrics.distribution.histogram.buckets` property to enable a customized set of histogram buckets to be tracked and reported. Alternatively, you can use the `mp.metrics.distribution.percentiles-histogram.enabled` property to enable the histogram metric to output and track a default set of histogram buckets. Performance might decrease if a large set of buckets are enabled for numerous histogram or timer metrics. For more information, see xref:microprofile-config-properties.adoc#metrics[MicroProfile Config properties: MicroProfile Metrics]. From 431ec050ccbf74081fb1b1bb4d0bacc919034fb9 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Tue, 28 Nov 2023 09:26:04 -0500 Subject: [PATCH 12/14] alphabetize table entries #6792 --- .../pages/microprofile-config-properties.adoc | 132 +++++++++--------- 1 file changed, 66 insertions(+), 66 deletions(-) diff --git a/modules/ROOT/pages/microprofile-config-properties.adoc b/modules/ROOT/pages/microprofile-config-properties.adoc index ca8921944a..816150b288 100644 --- a/modules/ROOT/pages/microprofile-config-properties.adoc +++ b/modules/ROOT/pages/microprofile-config-properties.adoc @@ -256,79 +256,65 @@ In MicroProfile Metrics 5.0 and later, the `_app` tag that is defined in prior |`mp.metrics.appName=myApp` |`mp.metrics.defaultAppName` -|The value for this property is defined at the server level and is used in conjunction with the `mp.metrics.appName` property when you run in a MicroProfile Metrics 5.x environment. The value of the `mp.metrics.defaultAppName` property passes the value of the `mp_app` tag to metrics that are created on the server level. +|The value for this property is defined at the server level and is used in conjunction with the `mp.metrics.appName` property when you run in a MicroProfile Metrics 5.x environment. The value of the `mp.metrics.defaultAppName` property passes the value of the `mp_app` tag to metrics that are created on the server level. -This property is necessary to use with the `mp.metrics.appName` property due to the restriction introduced in MicroProfile Metrics 5.0 that metrics of the same name must contain the same set of tag names. Certain vendor metrics, such as servlet metrics, can create metrics in both the application and server context. The `mp.metrics.appName` property creates the `mp_app` tag for the servlet metrics that are created in the application context. However, without a similar tag value provided for servlet metrics that are created in the server context, a registration exception is thrown. The `mp.metrics.defaultAppName` property that is defined at the server level provides the necessary `mp_app` tag for metrics that are created at the server level. +This property is necessary to use with the `mp.metrics.appName` property due to the restriction introduced in MicroProfile Metrics 5.0 that metrics of the same name must contain the same set of tag names. Certain vendor metrics, such as servlet metrics, can create metrics in both the application and server context. The `mp.metrics.appName` property creates the `mp_app` tag for the servlet metrics that are created in the application context. However, without a similar tag value provided for servlet metrics that are created in the server context, a registration exception is thrown. The `mp.metrics.defaultAppName` property that is defined at the server level provides the necessary `mp_app` tag for metrics that are created at the server level. |Server startup |`mp.metrics.defaultAppName=serverContext` -|`mp.metrics..enabled` -|When this property is set to true, it enables a user-provided Micrometer registry implementation, where `` is the name of the Micrometer registry. For more information, see xref:micrometer-metrics.adoc[Choose your own monitoring tools with MicroProfile Metrics]. This property is available starting in MicroProfile Metrics 5.0 . -|Server startup -|`mp.metrics.elastic.enabled=true` - -|`mp.metrics..` -|Specifies property values to configure for a Micrometer-implemented monitoring system. `` is the Micrometer registry value for the monitoring system, and ``is the name of the property in that system that you want to specify a value for. For more information, see xref:micrometer-metrics.adoc[Choose your own monitoring tools with MicroProfile Metrics]. This property is available starting in MicroProfile Metrics 5.0 . -|Server startup -|`mp.metrics.elastic.index=micrometer-metrics` - -|`mp.metrics.smallrye.histogram.precision` -|Specifies the percentile precision of the histogram metrics. The property accepts a value from 1 to 5 and is defaulted to 3 if no value is specified. A greater value results in more exact percentile calculations, but at a greater memory cost. -This property is available starting in MicroProfile Metrics 5.0 . -|Server startup -|`mp.metrics.smallrye.histogram.precision=4` +|`mp.metrics.distribution.histogram.buckets` +a| Specifies a list of metric names that are paired with custom sets of histogram buckets for the metric to track and output. This property is applicable only to histogram metrics. -|`mp.metrics.smallrye.timer.precision` -|Specifies the percentile precision of the timer metrics. The property accepts a value from 1 to 5 and is defaulted to 3 if no value is specified. A greater value results in more exact percentile calculations, but at a greater memory cost. -This property is available starting in MicroProfile Metrics 5.0 . -|Server startup -|`mp.metrics.smallrye.timer.precision=4` +* The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and comma-separated bucket values. +* Accepts a comma-separated list of float and integer values greater than 0. +* The asterisk (`*`) can be used as a wildcard at the end of the metric name. +* Defining a metric name with no bucket values or invalid values has no effect. +Value precedence is right-to-left, so that values that are specified later in the property definition take precedence over previously-specified values. -|`mp.metrics.tags` -|Specifies tags for a metric. Tag values that are set through this property must escape equal signs (`=`) and commas (`,`) with a backslash (`\`). The values of these tags are appended to the output of each metric. +This property is available starting in MicroProfile Metrics 5.1. |Server startup -|`mp.metrics.tags=app=shop,tier=integration,special=deli\=ver\,y` +|`mp.metrics.distribution.histogram.buckets=test.alpha.histogram=10.0,50.0,100.0;test.beta.histogram=30.0,50.0,123` -|`mp.metrics.distribution.percentiles` -a|Specifies a list of metric names that are paired with custom sets of percentiles for the metric to track and output. This property is applicable only to histogram and timer metrics. +|`mp.metrics.distribution.histogram.max-value` +a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a histogram metric, this property configures a upper bound for that default set of histogram buckets. -* The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and comma-separated percentile values. +* The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and a value: +* Properties accept float or integer values greater than 0. * The asterisk (`*`) can be used as a wildcard at the end of the metric name. -* The percentile values are float values between 0.0 and 1.0, inclusively. Invalid values are ignored. -* Setting the property with a metric name but no percentile values disables percentile output for that metric. -* Setting the property without any value disables percentiles for all histogram and timer metrics. -* Value precedence is right-to-left, so that values that are specified later in the property definition take precedence over previously-specified values. +* Defining a metric name with no value or an invalid value has no effect. +* Value precedence is right-to-left, so that values that are defined later in the property definition take precedence over earlier values. This property is available starting in MicroProfile Metrics 5.1. |Server startup -|`mp.metrics.distribution.percentiles=test.histogram=0.8,0.86,0.95;test.timer=0.9,0.99;test.*=0.5,0.6;other.*=` +| `mp.metrics.distribution.histogram.max-value=test.histogram=120` -|`mp.metrics.distribution.histogram.buckets` -a| Specifies a list of metric names that are paired with custom sets of histogram buckets for the metric to track and output. This property is applicable only to histogram metrics. +|`mp.metrics.distribution.histogram.min-value` +a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a histogram metric, this property configures a lower bound for that default set of histogram buckets. -* The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and comma-separated bucket values. -* Accepts a comma-separated list of float and integer values greater than 0. +* The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and a value. +* Properties accept float or integer values greater than 0. * The asterisk (`*`) can be used as a wildcard at the end of the metric name. -* Defining a metric name with no bucket values or invalid values has no effect. -Value precedence is right-to-left, so that values that are specified later in the property definition take precedence over previously-specified values. +* Defining a metric name with no value or an invalid value has no effect. +* Value precedence is right-to-left, so that values that are specified later in the property definition take precedence over previously-specified values. This property is available starting in MicroProfile Metrics 5.1. |Server startup -|`mp.metrics.distribution.histogram.buckets=test.alpha.histogram=10.0,50.0,100.0;test.beta.histogram=30.0,50.0,123` +| `mp.metrics.distribution.histogram.min-value=test.histogram=50` -|`mp.metrics.distribution.timer.buckets` -a| Specifies a list of metric names that are paired with custom sets of histogram buckets for the metric to track and output. This property is applicable only to timer metrics. +|`mp.metrics.distribution.percentiles` +a|Specifies a list of metric names that are paired with custom sets of percentiles for the metric to track and output. This property is applicable only to histogram and timer metrics. -* The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and comma-separated bucket values. -* The property accepts a comma-separated list of integers with an appended time unit (valid time units are `ms` for milliseconds, `s` for seconds, `m` for minutes and `h` for hours). Float values will not be accepted. Values with no time unit default to milliseconds. +* The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and comma-separated percentile values. * The asterisk (`*`) can be used as a wildcard at the end of the metric name. -* Defining a metric name with no bucket values or invalid values has no effect. +* The percentile values are float values between 0.0 and 1.0, inclusively. Invalid values are ignored. +* Setting the property with a metric name but no percentile values disables percentile output for that metric. +* Setting the property without any value disables percentiles for all histogram and timer metrics. * Value precedence is right-to-left, so that values that are specified later in the property definition take precedence over previously-specified values. This property is available starting in MicroProfile Metrics 5.1. |Server startup -|`mp.metrics.distribution.timer.buckets=test.*=50s,100s;test.alpha.timer=100,500ms,1s` +|`mp.metrics.distribution.percentiles=test.histogram=0.8,0.86,0.95;test.timer=0.9,0.99;test.*=0.5,0.6;other.*=` |`mp.metrics.distribution.percentiles-histogram.enabled` a| Specifies a list of metric names that are paired with a true or false value. This property is applicable only to histogram and timer metrics. If set to true, the metric outputs a default set of histogram buckets. @@ -342,31 +328,31 @@ This property is available starting in MicroProfile Metrics 5.1. |Server startup | `mp.metrics.distribution.percentiles-histogram.enabled=test.timer=true;test.histogram=false` -|`mp.metrics.distribution.histogram.min-value` -a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a histogram metric, this property configures a lower bound for that default set of histogram buckets. +|`mp.metrics.distribution.timer.buckets` +a| Specifies a list of metric names that are paired with custom sets of histogram buckets for the metric to track and output. This property is applicable only to timer metrics. -* The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and a value. -* Properties accept float or integer values greater than 0. +* The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and comma-separated bucket values. +* The property accepts a comma-separated list of integers with an appended time unit (valid time units are `ms` for milliseconds, `s` for seconds, `m` for minutes and `h` for hours). Float values will not be accepted. Values with no time unit default to milliseconds. * The asterisk (`*`) can be used as a wildcard at the end of the metric name. -* Defining a metric name with no value or an invalid value has no effect. +* Defining a metric name with no bucket values or invalid values has no effect. * Value precedence is right-to-left, so that values that are specified later in the property definition take precedence over previously-specified values. This property is available starting in MicroProfile Metrics 5.1. |Server startup -| `mp.metrics.distribution.histogram.min-value=test.histogram=50` +|`mp.metrics.distribution.timer.buckets=test.*=50s,100s;test.alpha.timer=100,500ms,1s` -|`mp.metrics.distribution.histogram.max-value` -a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a histogram metric, this property configures a upper bound for that default set of histogram buckets. +|`mp.metrics.distribution.timer.max-value` +a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a timer metric, this property configures an upper bound for that default set of histogram buckets. -* The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and a value: +* The property accepts a semicolon-separated set of values that define a metric name followed by an equals sign (`=`) and a value: * Properties accept float or integer values greater than 0. * The asterisk (`*`) can be used as a wildcard at the end of the metric name. * Defining a metric name with no value or an invalid value has no effect. -* Value precedence is right-to-left, so that values that are defined later in the property definition take precedence over earlier values. +* Value precedence is right-to-left, so that values that are specified later in the property definition take precedence over previously-specified values. This property is available starting in MicroProfile Metrics 5.1. |Server startup -| `mp.metrics.distribution.histogram.max-value=test.histogram=120` +| `mp.metrics.distribution.histogram.max-value=test.timer=5s` |`mp.metrics.distribution.timer.min-value` a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a timer metric, this property configures a lower bound for that default set of histogram buckets. @@ -381,18 +367,32 @@ This property is available starting in MicroProfile Metrics 5.1. |Server startup | `mp.metrics.distribution.histogram.min-value=test.timer=200` -|`mp.metrics.distribution.timer.max-value` -a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a timer metric, this property configures an upper bound for that default set of histogram buckets. +|`mp.metrics..enabled` +|When this property is set to true, it enables a user-provided Micrometer registry implementation, where `` is the name of the Micrometer registry. For more information, see xref:micrometer-metrics.adoc[Choose your own monitoring tools with MicroProfile Metrics]. This property is available starting in MicroProfile Metrics 5.0 . +|Server startup +|`mp.metrics.elastic.enabled=true` -* The property accepts a semicolon-separated set of values that define a metric name followed by an equals sign (`=`) and a value: -* Properties accept float or integer values greater than 0. -* The asterisk (`*`) can be used as a wildcard at the end of the metric name. -* Defining a metric name with no value or an invalid value has no effect. -* Value precedence is right-to-left, so that values that are specified later in the property definition take precedence over previously-specified values. +|`mp.metrics..` +|Specifies property values to configure for a Micrometer-implemented monitoring system. `` is the Micrometer registry value for the monitoring system, and ``is the name of the property in that system that you want to specify a value for. For more information, see xref:micrometer-metrics.adoc[Choose your own monitoring tools with MicroProfile Metrics]. This property is available starting in MicroProfile Metrics 5.0 . +|Server startup +|`mp.metrics.elastic.index=micrometer-metrics` -This property is available starting in MicroProfile Metrics 5.1. +|`mp.metrics.smallrye.histogram.precision` +|Specifies the percentile precision of the histogram metrics. The property accepts a value from 1 to 5 and is defaulted to 3 if no value is specified. A greater value results in more exact percentile calculations, but at a greater memory cost. +This property is available starting in MicroProfile Metrics 5.0 . |Server startup -| `mp.metrics.distribution.histogram.max-value=test.timer=5s` +|`mp.metrics.smallrye.histogram.precision=4` + +|`mp.metrics.smallrye.timer.precision` +|Specifies the percentile precision of the timer metrics. The property accepts a value from 1 to 5 and is defaulted to 3 if no value is specified. A greater value results in more exact percentile calculations, but at a greater memory cost. +This property is available starting in MicroProfile Metrics 5.0 . +|Server startup +|`mp.metrics.smallrye.timer.precision=4` + +|`mp.metrics.tags` +|Specifies tags for a metric. Tag values that are set through this property must escape equal signs (`=`) and commas (`,`) with a backslash (`\`). The values of these tags are appended to the output of each metric. +|Server startup +|`mp.metrics.tags=app=shop,tier=integration,special=deli\=ver\,y` |=== From 8b7add494818959bc4d0cf58e5565aee2895cda0 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Tue, 28 Nov 2023 11:09:23 -0500 Subject: [PATCH 13/14] Update microservice-observability-metrics.adoc #6792 --- .../microservice-observability-metrics.adoc | 39 +++++++++---------- 1 file changed, 18 insertions(+), 21 deletions(-) diff --git a/modules/ROOT/pages/microservice-observability-metrics.adoc b/modules/ROOT/pages/microservice-observability-metrics.adoc index 391658238c..8ff1f177bf 100644 --- a/modules/ROOT/pages/microservice-observability-metrics.adoc +++ b/modules/ROOT/pages/microservice-observability-metrics.adoc @@ -16,9 +16,9 @@ Open Liberty uses MicroProfile Metrics to provide metrics that describe the internal state of many Open Liberty components. MicroProfile Metrics provides a `/metrics` endpoint from which you can access all metrics that are emitted by an Open Liberty runtime and deployed applications. -When MicroProfile Metrics is enabled and an application is running, you can view metric data from any browser by accessing the `/metrics` endpoint. An example of this endpoint is `\https://localhost:9443/metrics`, where `9443` is the port number for your application. +When MicroProfile Metrics is enabled and an application is running, you can view metric data from any browser by accessing the `/metrics` endpoint. An example of this endpoint is `\https://localhost:9443/metrics`, where `9443` is the port number for your application. -You can narrow the scope of the metrics by using the `scope` query parameter with the `/metrics` endpoint to specify the metric registry scope. For example, to view the metric data for the `base` metric registry, use the `/metrics?scope=base` endpoint. This pattern is used to access all runtime-provided scopes (`base`, `application`, and `vendor`) and any <>. +You can narrow the scope of the metrics by using the `scope` query parameter with the `/metrics` endpoint to specify the metric registry scope. For example, to view the metric data for the `base` metric registry, use the `/metrics?scope=base` endpoint. This pattern is used to access all runtime-provided scopes (`base`, `application`, and `vendor`) and any <>. For feature:mpMetrics-4.0[display=MicroProfile Metrics 4.0] and earlier, only runtime-provided scopes are available and path parameters are used to narrow the scope of metric data. The endpoints are `/metrics/base`, `/metrics/application`, and `/metrics/vendor`. @@ -62,7 +62,7 @@ MetricRegistry customMetricRegistry; === Metric Tags -With MicroProfile metrics, you can logically group metrics that track similar statistics by instrumenting the metrics with tags. Tags consist of a name and a value. You can group multiple metrics of the same type together by instrumenting them with tags of the same name but different values to group them together. +With MicroProfile metrics, you can logically group metrics that track similar statistics by instrumenting the metrics with tags. Tags consist of a name and a value. You can group multiple metrics of the same type together by instrumenting them with tags of the same name but different values to group them together. For example, when you use counters, you can create multiple counters that are named `methodCounter` that return the count of the method that is identified by the tag. @@ -106,14 +106,14 @@ The following sections describe metric types that are available and how their co * <> * <> -* <> -* <> +* <> +* <> * <> (MicroProfile Metrics 1.0-4.0 only) * <> (MicroProfile Metrics 2.0-4.0 only) * <> (MicroProfile Metrics 2.3-4.0 only) [#timer] -=== Timer +=== Timer A timer metric aggregates timing durations in nanoseconds and provides duration statistics. Use the `@Timed` annotation to mark a constructor or method as a timer. @@ -147,7 +147,7 @@ For more information, see xref:microprofile-config-properties.adoc#metrics[Micro [#histogram] -=== Histogram +=== Histogram A histogram is a metric that calculates the distribution of a value. It provides the following information: - Maximum, median, and mean values @@ -196,15 +196,6 @@ donationDistribution_Dollars_sum{mp_scope="application",tier="integration",} 918 donationDistribution_Dollars_max{mp_scope="application",tier="integration",} 1000.0 ---- -==== Fine-Tuning with MicroProfile Config properties - -Starting in MicroProfile Metrics 5.0, you can adjust the percentile precision of the `Histogram` metrics by using the `mp.metrics.smallrye.histogram.precision` MicroProfile Config property. The property accepts a value from 1 to 5 and is defaulted to 3 if no value is specified. A greater value results in more exact percentile calculations, but at a greater memory cost. - -Starting in MicroProfile Metrics 5.1, you can customize the set of percentiles that are tracked and reported by using the `mp.metrics.distribution.percentiles` MicroProfile config property. You can also use the `mp.metrics.distribution.histogram.buckets` property to enable a customized set of histogram buckets to be tracked and reported. Alternatively, you can use the `mp.metrics.distribution.percentiles-histogram.enabled` property to enable the histogram metric to output and track a default set of histogram buckets. Performance might decrease if a large set of buckets are enabled for numerous histogram or timer metrics. - -For more information, see xref:microprofile-config-properties.adoc#metrics[MicroProfile Config properties: MicroProfile Metrics]. - - In MicroProfile 4.0 and earlier, the following JSON response is also available from the REST endpoints: [source,json] @@ -227,8 +218,16 @@ In MicroProfile 4.0 and earlier, the following JSON response is also available f } ---- +==== Fine-Tuning with MicroProfile Config properties + +Starting in MicroProfile Metrics 5.0, you can adjust the percentile precision of the `Histogram` metrics by using the `mp.metrics.smallrye.histogram.precision` MicroProfile Config property. The property accepts a value from 1 to 5 and is defaulted to 3 if no value is specified. A greater value results in more exact percentile calculations, but at a greater memory cost. + +Starting in MicroProfile Metrics 5.1, you can customize the set of percentiles that are tracked and reported by using the `mp.metrics.distribution.percentiles` MicroProfile config property. You can also use the `mp.metrics.distribution.histogram.buckets` property to enable a customized set of histogram buckets to be tracked and reported. Alternatively, you can use the `mp.metrics.distribution.percentiles-histogram.enabled` property to enable the histogram metric to output and track a default set of histogram buckets. Performance might decrease if a large set of buckets are enabled for numerous histogram or timer metrics. + +For more information, see xref:microprofile-config-properties.adoc#metrics[MicroProfile Config properties: MicroProfile Metrics]. + [#counter] -=== Counter +=== Counter A counter metric keeps an incremental count. The initial value of the counter is set to zero, and the metric increments each time that an annotated element is started. @@ -246,7 +245,7 @@ public String noDonation() { ---- [#gauge] -=== Gauge +=== Gauge You implement a gauge metric so that the gauge can be sampled to obtain a particular value. For example, you might use a gauge to measure CPU temperature or disk usage. @@ -313,7 +312,7 @@ A simple timer metric tracks the elapsed timing duration and invocation counts. This type of metric is available link:/blog/2020/04/09/microprofile-3-3-open-liberty-20004.html#mra[beginning in MicroProfile Metrics 2.3]. It is removed starting in MicroProfile Metrics 5.0. The simple timer is a lightweight alternative to the performance-heavy timer metric. Beginning in MicroProfile Metrics 3.0, the simple timer metric also tracks the largest and smallest recorded duration of the previous complete minute. -A complete minute is defined as `00:00:00.000` seconds to `00:00:59.999` seconds. +A complete minute is defined as `00:00:00.000` seconds to `00:00:59.999` seconds. Use the `@SimplyTimed` annotation to mark a method, constructor, or type as a simple timer. The simple timer tracks how frequently the annotated object is started and how long the invocations take to complete: @@ -335,5 +334,3 @@ public JSON getWeatherData() { * Guide: link:/guides/microprofile-metrics.html[Providing metrics from a microservice] * xref:introduction-monitoring-metrics.adoc[Monitoring with metrics] * xref:metrics-list.adoc[Metrics reference list] - - From 346d90095daec2bb706d4359d34f287633a4ea97 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Thu, 7 Dec 2023 11:16:31 -0500 Subject: [PATCH 14/14] edits per peer review #6792 --- .../pages/microprofile-config-properties.adoc | 42 +++++++++---------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/modules/ROOT/pages/microprofile-config-properties.adoc b/modules/ROOT/pages/microprofile-config-properties.adoc index 816150b288..b0a1ee1478 100644 --- a/modules/ROOT/pages/microprofile-config-properties.adoc +++ b/modules/ROOT/pages/microprofile-config-properties.adoc @@ -256,9 +256,9 @@ In MicroProfile Metrics 5.0 and later, the `_app` tag that is defined in prior |`mp.metrics.appName=myApp` |`mp.metrics.defaultAppName` -|The value for this property is defined at the server level and is used in conjunction with the `mp.metrics.appName` property when you run in a MicroProfile Metrics 5.x environment. The value of the `mp.metrics.defaultAppName` property passes the value of the `mp_app` tag to metrics that are created on the server level. +|The value for this property is defined at the server level and is used along with the `mp.metrics.appName` property when you run in a MicroProfile Metrics 5.x environment. The value of the `mp.metrics.defaultAppName` property passes the value of the `mp_app` tag to metrics that are created on the server level. -This property is necessary to use with the `mp.metrics.appName` property due to the restriction introduced in MicroProfile Metrics 5.0 that metrics of the same name must contain the same set of tag names. Certain vendor metrics, such as servlet metrics, can create metrics in both the application and server context. The `mp.metrics.appName` property creates the `mp_app` tag for the servlet metrics that are created in the application context. However, without a similar tag value provided for servlet metrics that are created in the server context, a registration exception is thrown. The `mp.metrics.defaultAppName` property that is defined at the server level provides the necessary `mp_app` tag for metrics that are created at the server level. +This property is necessary to use with the `mp.metrics.appName` property due to the restriction introduced in MicroProfile Metrics 5.0 that metrics of the same name must contain the same set of tag names. Certain vendor metrics, such as servlet metrics, can create metrics in both the application and server context. The `mp.metrics.appName` property creates the `mp_app` tag for the servlet metrics that are created in the application context. However, without a similar tag value that is provided for servlet metrics that are created in the server context, a registration exception is thrown. The `mp.metrics.defaultAppName` property that is defined at the server level provides the necessary `mp_app` tag for metrics that are created at the server level. |Server startup |`mp.metrics.defaultAppName=serverContext` @@ -270,33 +270,33 @@ a| Specifies a list of metric names that are paired with custom sets of histogra * Accepts a comma-separated list of float and integer values greater than 0. * The asterisk (`*`) can be used as a wildcard at the end of the metric name. * Defining a metric name with no bucket values or invalid values has no effect. -Value precedence is right-to-left, so that values that are specified later in the property definition take precedence over previously-specified values. +Value precedence is right to left so values that are specified later in the property definition take precedence over previously specified values. This property is available starting in MicroProfile Metrics 5.1. |Server startup |`mp.metrics.distribution.histogram.buckets=test.alpha.histogram=10.0,50.0,100.0;test.beta.histogram=30.0,50.0,123` |`mp.metrics.distribution.histogram.max-value` -a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a histogram metric, this property configures a upper bound for that default set of histogram buckets. +a| When the `mp.metrics.distribution.percentiles-histogram.enabled` property is configured to provide a default set of histogram buckets for a histogram metric, this property configures a upper bound for that default set of histogram buckets. * The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and a value: * Properties accept float or integer values greater than 0. * The asterisk (`*`) can be used as a wildcard at the end of the metric name. * Defining a metric name with no value or an invalid value has no effect. -* Value precedence is right-to-left, so that values that are defined later in the property definition take precedence over earlier values. +* Value precedence is right to left so values that are defined later in the property definition take precedence over earlier values. This property is available starting in MicroProfile Metrics 5.1. |Server startup | `mp.metrics.distribution.histogram.max-value=test.histogram=120` |`mp.metrics.distribution.histogram.min-value` -a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a histogram metric, this property configures a lower bound for that default set of histogram buckets. +a| When the `mp.metrics.distribution.percentiles-histogram.enabled` property is configured to provide a default set of histogram buckets for a histogram metric, this property configures a lower bound for that default set of histogram buckets. * The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and a value. * Properties accept float or integer values greater than 0. * The asterisk (`*`) can be used as a wildcard at the end of the metric name. * Defining a metric name with no value or an invalid value has no effect. -* Value precedence is right-to-left, so that values that are specified later in the property definition take precedence over previously-specified values. +* Value precedence is right to left so values that are specified later in the property definition take precedence over previously specified values. This property is available starting in MicroProfile Metrics 5.1. |Server startup @@ -310,7 +310,7 @@ a|Specifies a list of metric names that are paired with custom sets of percentil * The percentile values are float values between 0.0 and 1.0, inclusively. Invalid values are ignored. * Setting the property with a metric name but no percentile values disables percentile output for that metric. * Setting the property without any value disables percentiles for all histogram and timer metrics. -* Value precedence is right-to-left, so that values that are specified later in the property definition take precedence over previously-specified values. +* Value precedence is right to left so values that are specified later in the property definition take precedence over previously specified values. This property is available starting in MicroProfile Metrics 5.1. |Server startup @@ -322,7 +322,7 @@ a| Specifies a list of metric names that are paired with a true or false value. * The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and either `true` or `false. * The asterisk (`*`) can be used as a wildcard at the end of the metric name. * Defining a metric name with no values or invalid values has no effect. -* Values defined later take precedence over values before (i.e., right to left precedence). +* Values defined later take precedence over values before. Precedence is right to left. This property is available starting in MicroProfile Metrics 5.1. |Server startup @@ -332,60 +332,60 @@ This property is available starting in MicroProfile Metrics 5.1. a| Specifies a list of metric names that are paired with custom sets of histogram buckets for the metric to track and output. This property is applicable only to timer metrics. * The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and comma-separated bucket values. -* The property accepts a comma-separated list of integers with an appended time unit (valid time units are `ms` for milliseconds, `s` for seconds, `m` for minutes and `h` for hours). Float values will not be accepted. Values with no time unit default to milliseconds. +* The property accepts a comma-separated list of integers with an appended time unit (valid time units are `ms` for milliseconds, `s` for seconds, `m` for minutes and `h` for hours). Float values are not accepted. Values with no time unit default to milliseconds. * The asterisk (`*`) can be used as a wildcard at the end of the metric name. * Defining a metric name with no bucket values or invalid values has no effect. -* Value precedence is right-to-left, so that values that are specified later in the property definition take precedence over previously-specified values. +* Value precedence is right to left so values that are specified later in the property definition take precedence over previously specified values. This property is available starting in MicroProfile Metrics 5.1. |Server startup |`mp.metrics.distribution.timer.buckets=test.*=50s,100s;test.alpha.timer=100,500ms,1s` |`mp.metrics.distribution.timer.max-value` -a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a timer metric, this property configures an upper bound for that default set of histogram buckets. +a| When the `mp.metrics.distribution.percentiles-histogram.enabled` property is configured to provide a default set of histogram buckets for a timer metric, this property configures an upper bound for that default set of histogram buckets. * The property accepts a semicolon-separated set of values that define a metric name followed by an equals sign (`=`) and a value: * Properties accept float or integer values greater than 0. * The asterisk (`*`) can be used as a wildcard at the end of the metric name. * Defining a metric name with no value or an invalid value has no effect. -* Value precedence is right-to-left, so that values that are specified later in the property definition take precedence over previously-specified values. +* Value precedence is right to left so values that are specified later in the property definition take precedence over previously specified values. This property is available starting in MicroProfile Metrics 5.1. |Server startup | `mp.metrics.distribution.histogram.max-value=test.timer=5s` |`mp.metrics.distribution.timer.min-value` -a| When the `mp.metrics.distribution.percentiles-histogram.enabled` is configured to provide a default set of histogram buckets for a timer metric, this property configures a lower bound for that default set of histogram buckets. +a| When the `mp.metrics.distribution.percentiles-histogram.enabled` property is configured to provide a default set of histogram buckets for a timer metric, this property configures a lower bound for that default set of histogram buckets. * The property accepts a semicolon-separated set of values that consist of a metric name followed by an equals sign (`=`) and a value: * Properties accept float or integer values greater than 0. * The asterisk (`*`) can be used as a wildcard at the end of the metric name. * Defining a metric name with no value or an invalid value has no effect. -* Value precedence is right-to-left, so that values that are specified later in the property definition take precedence over previously-specified values. +* Value precedence is right to left so values that are specified later in the property definition take precedence over previously specified values. This property is available starting in MicroProfile Metrics 5.1. |Server startup | `mp.metrics.distribution.histogram.min-value=test.timer=200` |`mp.metrics..enabled` -|When this property is set to true, it enables a user-provided Micrometer registry implementation, where `` is the name of the Micrometer registry. For more information, see xref:micrometer-metrics.adoc[Choose your own monitoring tools with MicroProfile Metrics]. This property is available starting in MicroProfile Metrics 5.0 . +|When this property is set to true, it enables a user-provided Micrometer registry implementation, where `` is the name of the Micrometer registry. For more information, see xref:micrometer-metrics.adoc[Choose your own monitoring tools with MicroProfile Metrics]. This property is available starting in MicroProfile Metrics 5.0. |Server startup |`mp.metrics.elastic.enabled=true` |`mp.metrics..` -|Specifies property values to configure for a Micrometer-implemented monitoring system. `` is the Micrometer registry value for the monitoring system, and ``is the name of the property in that system that you want to specify a value for. For more information, see xref:micrometer-metrics.adoc[Choose your own monitoring tools with MicroProfile Metrics]. This property is available starting in MicroProfile Metrics 5.0 . +|Specifies property values to configure for a Micrometer-implemented monitoring system. `` is the Micrometer registry value for the monitoring system, and ``is the name of the property in that system that you want to specify a value for. For more information, see xref:micrometer-metrics.adoc[Choose your own monitoring tools with MicroProfile Metrics]. This property is available starting in MicroProfile Metrics 5.0. |Server startup |`mp.metrics.elastic.index=micrometer-metrics` |`mp.metrics.smallrye.histogram.precision` -|Specifies the percentile precision of the histogram metrics. The property accepts a value from 1 to 5 and is defaulted to 3 if no value is specified. A greater value results in more exact percentile calculations, but at a greater memory cost. -This property is available starting in MicroProfile Metrics 5.0 . +|Specifies the percentile precision of the histogram metrics. The property accepts a value from 1 to 5 and defaults to `3` if no value is specified. A greater value results in more exact percentile calculations, but at a greater memory cost. +This property is available starting in MicroProfile Metrics 5.0. |Server startup |`mp.metrics.smallrye.histogram.precision=4` |`mp.metrics.smallrye.timer.precision` -|Specifies the percentile precision of the timer metrics. The property accepts a value from 1 to 5 and is defaulted to 3 if no value is specified. A greater value results in more exact percentile calculations, but at a greater memory cost. -This property is available starting in MicroProfile Metrics 5.0 . +|Specifies the percentile precision of the timer metrics. The property accepts a value from 1 to 5 and defaults to `3` if no value is specified. A greater value results in more exact percentile calculations, but at a greater memory cost. +This property is available starting in MicroProfile Metrics 5.0. |Server startup |`mp.metrics.smallrye.timer.precision=4`