diff --git a/modules/ROOT/pages/microprofile-config-properties.adoc b/modules/ROOT/pages/microprofile-config-properties.adoc index 0a66278139..b0a1ee1478 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,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..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` @@ -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] diff --git a/modules/ROOT/pages/microservice-observability-metrics.adoc b/modules/ROOT/pages/microservice-observability-metrics.adoc index d7e6f3a30d..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. @@ -137,11 +137,17 @@ 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 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]. [#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 @@ -189,8 +195,6 @@ 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]. - In MicroProfile 4.0 and earlier, the following JSON response is also available from the REST endpoints: @@ -214,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. @@ -233,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. @@ -300,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: @@ -322,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] - -