Merge pull request #7129 from OpenLiberty/6792-mpMetrics51

6792 mp metrics51

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,29 +251,141 @@ 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 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`
+|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 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`
+
+|`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.
+
+* 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 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` 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 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` 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 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.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 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 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 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.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.
+
+* 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. Precedence is right to left.
+
+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.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 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 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 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` 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 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` 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 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.<registry>.enabled`
-|When this property is set to true, it enables a user-provided Micrometer registry implementation, where `<registry>` 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 `<registry>` 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.<registry>.<property>`
-|Specifies property values to configure for a Micrometer-implemented monitoring system. `<registry>` is the Micrometer registry value for the monitoring system, and `<property>`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. `<registry>` is the Micrometer registry value for the monitoring system, and `<property>`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`
 
@@ -282,7 +394,6 @@ This property is available starting in MicroProfile Metrics 5.0 .
 |Server startup
 |`mp.metrics.tags=app=shop,tier=integration,special=deli\=ver\,y`
 
-
 |===
 
 [#openapi]