From 1defdad0c93bfd0f6deca7fc16dd41b4090280af Mon Sep 17 00:00:00 2001 From: Channyboy Date: Tue, 10 Oct 2023 17:17:17 -0400 Subject: [PATCH 01/58] 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/58] 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/58] 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/58] 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/58] 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/58] 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/58] 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/58] 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/58] 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/58] 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/58] 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 da391834f2c69a0596c2fbf7b5d5b1a44c0bf846 Mon Sep 17 00:00:00 2001 From: Anjum Fatima Date: Thu, 9 Nov 2023 14:00:19 -0600 Subject: [PATCH 12/58] Documenting behavior of config inside the application when no default value is set before checkpoint --- modules/ROOT/pages/instanton-limitations.adoc | 69 ++++++++++++++++++- 1 file changed, 68 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/instanton-limitations.adoc b/modules/ROOT/pages/instanton-limitations.adoc index 1566497449..661767bb4d 100644 --- a/modules/ROOT/pages/instanton-limitations.adoc +++ b/modules/ROOT/pages/instanton-limitations.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/ @@ -23,6 +23,7 @@ The following sections describe the limitations and known issues with using Open - <<#trans-before, Jakarta Transaction before checkpoint>> - <<#mp-config, Accessing MicroProfile Configuration too early>> - <<#datasource, Injecting a DataSource too early>> +- <<#mp-config-no-default, Accessing microprofile config with no default value at Checkpoint>> - <<#features, Using product extensions, user features, or features that are not supported by InstantOn>> - <<#boot,Updating configuration with a bootstrap.properties file>> - <<#securitymanager, Java SecurityManager is not supported>> @@ -161,6 +162,72 @@ This configuration uses placeholder values for things like the database name, ho If an application is injected with a `DataSource` before the checkpoint and the configuration of the `DataSource` changes, the application is restarted when the InstantOn application container image is run with the updated configuration. You can avoid this scenario by using the `beforeAppStart` option or by modifying the component not to be early startup code. In this example, that modification is to remove the `loadOnStartup = 1` attribute. +[#mp-config-no-default] +== Accessing microprofile config with no default value at Checkpoint +The configuration property can be introduced inside the application either statically through `` or `Optional`, or dynamically using a `Provider`. The following example shows ways to inject static, static-optional, dynamic and dynamic-optional config property. +[source,java] +---- + @Inject + @ConfigProperty(name = "static_config") + String staticConfig; + + @Inject + @ConfigProperty(name = "static_optional_config") + Optional staticOptionalConfig; + + @Inject + @ConfigProperty(name = "dynamic_config") + Provider dynamicConfig; + + @Inject + @ConfigProperty(name = "dynamic_optional_config") + Provider> dynamicOptionalConfig; +---- +The injected `static_config` will cause an error like the following example if there is no value found in an existing config source during checkpoint. + +[source,sh] +---- +SRCFG02000: Failed to Inject @ConfigProperty for key static_config into io.example.Example.staticConfig since the config property could not be found in any config source. +---- + +This error can be avoided by providing a default value for the configuration key in one of the following ways: + +Specify the default value on the @ConfigProperty annotation like the following: +[source,java] +---- + @Inject + @ConfigProperty(name = "static_config", defaultValue = "defaultValue") + String staticConfig; +---- + +Specify the default value in the application `META-INF/microprofile-config.properties` resource. +[source,sh] +---- + static_config=defaultValue +---- + +Specify a default value in a server.xml variable. +[source,xml] +---- + +---- + +The `defaultValue` can then be overridden on restore by configuring the value with an environment variable or values from the variable source directory. + +However, if no default value is set, we can still avoid the above error by injecting config using `static_optional_config`, `dynamic_config`, `dynamic_optional_config`. But caution is needed for CDI beans that are `@ApplicationScoped` which are created during application startup when using the afterAppStart checkpoint option. Trying to access the `dynamic_config` early during the application startup at checkpoint can cause the following error: +[source,sh] +---- +java.util.NoSuchElementException: SRCFG00014: The config property dynamic_config is required but it could not be found in any config source. +---- +While accessing the `static_optional_config` and `dynamic_optional_config` can cause the following error: +[source,sh] +---- +java.util.NoSuchElementException: No value present +---- + +Therefore, it is advisable to have a default value set for injected config properties in order to avoid the above mentioned errors. Furthermore, if the @ConfigProperty injection site is not using dynamic config then any default value injected into the application scoped bean before checkpoint will not be updated on restore. This is already mentioned in the docs at xref:#mp-config[Accessing MicroProfile Config too early] + + [#features] == Using product extensions, user features, or features that are not supported by InstantOn InstantOn supports only a subset of Open Liberty features, as described in xref:instanton.adoc#supported-features[Open Liberty InstantOn supported features]. Any public features that are enabled outside of the supported set of features for InstantOn cause checkpoint to fail with an error message like the following example: From f450dca07f15360227637fd042e0699719232e8b Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Thu, 16 Nov 2023 15:03:54 +0530 Subject: [PATCH 13/58] Update for 7047 done-1 Update for 7047 done-1 #7047 --- modules/ROOT/pages/admin-center.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/modules/ROOT/pages/admin-center.adoc b/modules/ROOT/pages/admin-center.adoc index 1f4547d72d..394fec7c2d 100644 --- a/modules/ROOT/pages/admin-center.adoc +++ b/modules/ROOT/pages/admin-center.adoc @@ -67,6 +67,8 @@ For example, if your browser is running on the same computer as your server and `https://localhost:9443/adminCenter` +Access to Admin Center is supported only when the access comes directly from a browser. Access through an HTTP proxy server is not supported. + If your browser prompts you to confirm that the connection is trusted, specify an exception or otherwise enable the connection to continue to Admin Center. To log in to Admin Center, specify the username and password from your management role configuration. For example, if you use the previously provided example `server.xml` configuration, specify `admin` as the username and `adminpwd` as the password. From 34d01281e70df84f47646562333d21eb87d4940c Mon Sep 17 00:00:00 2001 From: yasmin-aumeeruddy Date: Fri, 17 Nov 2023 15:50:29 +0000 Subject: [PATCH 14/58] Add MP 6.1 differences documentation --- .../reference/pages/diff/mp-60-61-diff.adoc | 37 +++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 modules/reference/pages/diff/mp-60-61-diff.adoc diff --git a/modules/reference/pages/diff/mp-60-61-diff.adoc b/modules/reference/pages/diff/mp-60-61-diff.adoc new file mode 100644 index 0000000000..034ee11295 --- /dev/null +++ b/modules/reference/pages/diff/mp-60-61-diff.adoc @@ -0,0 +1,37 @@ +// Copyright (c) 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/ +// +// +// Contributors: +// IBM Corporation +// +// +// +// +:page-description: MicroProfile 6.1 is a minor release. If you are updating your application from using MicroProfile 6.0 features to using MicroProfile 6.1 features, changes in API behavior might require you to update your application code. +:projectName: Open Liberty +:page-layout: general-reference +:page-type: general += Differences between MicroProfile 6.1 and 6.0 + +MicroProfile 6.1 is a minor release. It includes Jakarta EE 10 Core Profile and replaces MicroProfile OpenTracing with MicroProfile Telemetry. + +Therefore, MicroProfile OpenTracing moves out of the umbrella release and becomes a stand-alone specification. For more information about Jakarta EE 10 Core Profile, see the link:https://jakarta.ee/specifications/coreprofile/10/[Core Profile specification]. + +If you are updating your application from using MicroProfile 6.0 features to using link:https://github.com/eclipse/microprofile/releases/tag/6.1[MicroProfile 6.1] features, changes in API behavior might require you to update your application code. The following sections provide details about migrating your applications from MicroProfile 6.0 to 6.1: + +- <<#metrics, Differences between MicroProfile Metrics 5.0 and 5.1>> +- <<#telemetry, Differences between MicroProfile Telemetry 1.0 and 1.1>> + +[#metrics] +== Differences between MicroProfile Metrics 5.0 and 5.1 + +The MicroProfile Metrics 5.1 release introduces many changes to the specification and programming model that impact users who are migrating from MicroProfile Metrics 5.0. + +[#telemetry] +== Differences between MicroProfile Telemetry 1.0 and 1.1 + +MicroProfile Telemetry 1.1 provides developers with the latest Open Telemetry technology; the feature now consumes OpenTelemetry-1.29.0, updated from 1.19.0. Consequently, a lot of the dependencies are now stable. The feature is compatible with Java EE 7 with MicroProfile 1.4, Java EE 8 with MicroProfile 4.1, Jakarta EE 9 with MicroProfile 5.0 and Jakarta EE 10 with MicroProfile 6.1. + From c8a7fb5423cb8595d94ea8f96adf60c2ae906604 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Fri, 17 Nov 2023 12:01:06 -0500 Subject: [PATCH 15/58] Minor edits fix typos and clarify executor config per #7061 and #7049 --- modules/ROOT/pages/thread-pool-tuning.adoc | 9 ++++++--- .../reference/pages/feature/xmlWS-3.0/description.adoc | 1 + .../reference/pages/feature/xmlWS-4.0/description.adoc | 2 +- .../reference/pages/feature/xmlWS-5.0/description.adoc | 1 - 4 files changed, 8 insertions(+), 5 deletions(-) create mode 100644 modules/reference/pages/feature/xmlWS-3.0/description.adoc delete mode 100644 modules/reference/pages/feature/xmlWS-5.0/description.adoc diff --git a/modules/ROOT/pages/thread-pool-tuning.adoc b/modules/ROOT/pages/thread-pool-tuning.adoc index ccf0a04d5b..1e578a6e0e 100644 --- a/modules/ROOT/pages/thread-pool-tuning.adoc +++ b/modules/ROOT/pages/thread-pool-tuning.adoc @@ -6,7 +6,7 @@ // Contributors: // IBM Corporation // -// This doc is hosted in the Red Hat Runtimes documentation. Any changes made to this doc also need to be made to the version that's located in the PurpleLiberty GitHub repo (https://github.com/PurpleLiberty/docs). +// This doc is hosted in the Red Hat Runtimes documentation. Any changes made to this doc also need to be made to the version that's located in the PurpleLiberty GitHub repo (https://github.com/PurpleLiberty/docs). // :page-description: Open Liberty provides a self-tuning algorithm that controls the size of its thread pool. For most applications that run on Open Liberty, it is not necessary to tune the size of the thread pool. :page-layout: general-reference @@ -17,7 +17,7 @@ = Thread pool tuning Open Liberty provides a self-tuning algorithm that controls the size of its thread pool. -Although you do not need to manually tune the thread pool for most applications, in some cases you might need to adjust the `coreThreads` and `maxThreads` attributes. +Although you do not need to manually tune the thread pool for most applications, in rare cases you might need to configure thread pool settings in your `server.xml` file. All the application code in Open Liberty runs in a single thread pool that is called the default executor. The size of this pool is set by a self-tuning controller, which can manage a wide range of workloads. @@ -71,7 +71,8 @@ The controller cycle returns to its normal duration, and pool size is adjusted b In most environments, configurations, and workloads, the Open Liberty thread pool does not require manual configuration or tuning. The thread pool self-tunes to determine how many threads are needed to provide optimal server throughput. The thread pool controller continually adjusts the number of threads in the pool within the defined bounds for the `coreThreads` and `maxThreads` attributes. -However, in some situations, setting the `coreThreads` or `maxThreads` attributes might be necessary. +However, in rare cases, you might need to explicitly configure an `executor` element and adjust the `coreThreads` and `maxThreads` attributes to particular values in your server.xml file. + The following sections describe these attributes and provide examples of conditions under which they might need to be manually tuned. * `coreThreads` + @@ -91,6 +92,8 @@ Some environments set a hard limit on the number of threads that a process can c Currently, Open Liberty has no way to know whether such a cap applies, or what the value is. If Open Liberty is running in a thread-limited environment, the operator can configure the `maxThreads` attribute to an acceptable value. + + The Open Liberty thread pool controller is designed to handle a wide range of workloads and configurations. In some edge cases, you might need to adjust the `coreThreads` and `maxThreads` attributes. However, try the default behavior first to make sure you need to make adjustments. == See also diff --git a/modules/reference/pages/feature/xmlWS-3.0/description.adoc b/modules/reference/pages/feature/xmlWS-3.0/description.adoc new file mode 100644 index 0000000000..b3150026f8 --- /dev/null +++ b/modules/reference/pages/feature/xmlWS-3.0/description.adoc @@ -0,0 +1 @@ +If you are updating your application from using the `xmlWS-3.0` feature to using the `xmlWS-4.0` feature, changes in API behavior might require you to update your application code. For more information, see xref:diff/jakarta-ee10-diff.adoc#xml[Differences between Jakarta XML Web Services 4.0 and 3.0]. diff --git a/modules/reference/pages/feature/xmlWS-4.0/description.adoc b/modules/reference/pages/feature/xmlWS-4.0/description.adoc index d9891a7221..b3150026f8 100644 --- a/modules/reference/pages/feature/xmlWS-4.0/description.adoc +++ b/modules/reference/pages/feature/xmlWS-4.0/description.adoc @@ -1 +1 @@ -If you are updating your application from using the `xmlWS-3.0` feature to using the `xmlWSg-4.0` feature, changes in API behavior might require you to update your application code. For more information, see xref:diff/jakarta-ee10-diff.adoc#xml[Differences between Jakarta XML Web Services 4.0 and 3.0]. +If you are updating your application from using the `xmlWS-3.0` feature to using the `xmlWS-4.0` feature, changes in API behavior might require you to update your application code. For more information, see xref:diff/jakarta-ee10-diff.adoc#xml[Differences between Jakarta XML Web Services 4.0 and 3.0]. diff --git a/modules/reference/pages/feature/xmlWS-5.0/description.adoc b/modules/reference/pages/feature/xmlWS-5.0/description.adoc deleted file mode 100644 index d9891a7221..0000000000 --- a/modules/reference/pages/feature/xmlWS-5.0/description.adoc +++ /dev/null @@ -1 +0,0 @@ -If you are updating your application from using the `xmlWS-3.0` feature to using the `xmlWSg-4.0` feature, changes in API behavior might require you to update your application code. For more information, see xref:diff/jakarta-ee10-diff.adoc#xml[Differences between Jakarta XML Web Services 4.0 and 3.0]. From 577c3619a704394261d5b6fd935d1a4379aaf818 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Mon, 20 Nov 2023 16:34:42 +0530 Subject: [PATCH 16/58] 7031-configdropins info to server config overview-1 7031-configdropins info to server config overview-1 #7031 --- .../config/server-configuration-overview.adoc | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/modules/reference/pages/config/server-configuration-overview.adoc b/modules/reference/pages/config/server-configuration-overview.adoc index 141bd6b882..b66a33f140 100644 --- a/modules/reference/pages/config/server-configuration-overview.adoc +++ b/modules/reference/pages/config/server-configuration-overview.adoc @@ -43,6 +43,7 @@ The following sections provide more details on configuring a server. * <<#variable-substitution,Variable substitution precedence>> * <<#configuration-merging,Configuration merging>> * <<#include-processing,Include processing>> +* <<#configDropins-directory,Using the configuration dropins folder to specify server sonfiguration>> * <<#configuration-references,Configuration references>> * <<#dynamic-updates,Dynamic updates>> * <<#log-messages,Log messages>> @@ -514,6 +515,32 @@ Functionally, this configuration is the same as including each file separately w ---- +[#configDropins-directory] +== Using the configuration dropins folder to specify server configuration + +In Open Liberty, the `configDropins` directory is a convenient method for adding or modifying server configuration without directly altering the `server.xml` file. This directory is located under `usr/servers/server_name`. + +=== Types of subdirectories within configDropins + +* Overrides (`usr/servers/server_name/configDropins/overrides`): This directory is used to override configurations in the `server.xml` file. For example, to change port configurations defined in `server.xml`, place the relevant configuration files in this directory. + +* Defaults (`usr/servers/server_name/configDropins/defaults`): This directory is for setting defaults for configuration elements that are not specified in `server.xml`. It allows the `server.xml` file to remain the primary configuration source, with additional default settings provided through this directory. + +Configuration files placed in either the `configDropins/overrides` or `configDropins/defaults` directories are dynamically monitored. Changes, including additions, removals, or updates, are reflected in the runtime configuration automatically. + +=== Conflict Resolution and Precedence + +* Configurations in the `configDropins/overrides` directory take precedence over the configurations in the `server.xml` file. + +* Configurations in the `server.xml` file take precedence over the configurations in the `configDropins/defaults` directory. + +* Both `configDropins/defaults` and `configDropins/overrides` configurations supersede any default settings that are specified by a feature. + +* The configuration files in these directories are processed in alphabetical order. + +To ensure consistency across different platforms, file names are converted to lowercase before sorting alphabetically. If two files have the same name with case variations (like `extraConfig.xml` and `ExtraConfig.xml`), the order of processing might be unpredictable. + + [#configuration-references] == Configuration references Most configuration in Open Liberty is self-contained, but it is often useful to share configuration. From 7770a4266b50cf1fee8f1f2752a921bf6ed8d8ca Mon Sep 17 00:00:00 2001 From: David Mueller Date: Mon, 20 Nov 2023 09:01:31 -0500 Subject: [PATCH 17/58] test From b97084e58d13d2641c598eb6aaa27c36253fc13e Mon Sep 17 00:00:00 2001 From: David Mueller Date: Mon, 20 Nov 2023 15:28:00 -0500 Subject: [PATCH 18/58] add new example #7023 --- .../feature/openidConnectClient/examples.adoc | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/modules/reference/pages/feature/openidConnectClient/examples.adoc b/modules/reference/pages/feature/openidConnectClient/examples.adoc index 54953cb4cf..1ab1525f74 100644 --- a/modules/reference/pages/feature/openidConnectClient/examples.adoc +++ b/modules/reference/pages/feature/openidConnectClient/examples.adoc @@ -13,7 +13,7 @@ The following examples demonstrate configuration options for the OpenID Connect - <<#oauth,Accept an OAuth 2.0 bearer access token without redirecting to an OpenID Connect provider>> - <<#context,Modify the context root>> - <<#params,Pass request parameters to OpenID Connect>> - +- <<#access-token,Check the access token for user group information>> [#minimal] === Minimal configuration for Open Liberty to act as an OpenID Connect client @@ -360,3 +360,15 @@ To provide extra authorization parameters to the OP, configure `authzParameter` ---- To configure parameters for the token endpoint, use the `tokenParameter` element. + +[#access-token] +=== Check the access token for user group information + +If a user's group information is not found in the ID token, you can configure Open Liberty to also check for this information in the Access token and `userinfo`. Set the `tokensOrderToFetchCallerClaims` attribute to `AccessToken IDToken Userinfo`, as shown in the following example. + +[source,xml] +---- + +---- + +In this example, Open Liberty checks the Access Token first, then the ID token, and lastly, `userinfo`. If no group information is found in these locations, an unauthorized response code is returned. From eada11103cdcae0ca1f24bba975450c9c78a619d Mon Sep 17 00:00:00 2001 From: David Mueller Date: Mon, 20 Nov 2023 15:51:20 -0500 Subject: [PATCH 19/58] Update examples.adoc --- .../pages/feature/openidConnectClient/examples.adoc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/modules/reference/pages/feature/openidConnectClient/examples.adoc b/modules/reference/pages/feature/openidConnectClient/examples.adoc index 1ab1525f74..072dc1be29 100644 --- a/modules/reference/pages/feature/openidConnectClient/examples.adoc +++ b/modules/reference/pages/feature/openidConnectClient/examples.adoc @@ -364,11 +364,13 @@ To configure parameters for the token endpoint, use the `tokenParameter` element [#access-token] === Check the access token for user group information -If a user's group information is not found in the ID token, you can configure Open Liberty to also check for this information in the Access token and `userinfo`. Set the `tokensOrderToFetchCallerClaims` attribute to `AccessToken IDToken Userinfo`, as shown in the following example. +If a user's group information is not found in the ID token, you can configure Open Liberty to also check for this information in the Access token and the `UserInfo` endpoint. Set the `tokensOrderToFetchCallerClaims` attribute to `AccessToken IDToken Userinfo`, as shown in the following example. [source,xml] ---- ---- -In this example, Open Liberty checks the Access Token first, then the ID token, and lastly, `userinfo`. If no group information is found in these locations, an unauthorized response code is returned. +In this example, Open Liberty checks the access token first, then the ID token, and lastly, calls the `UserInfo` endpoint. If no group information is found in any of these these locations, an unauthorized response code is returned. + +If the `tokensOrderToFetchCallerClaims` attribute is not specified, the default value is `IDToken` and Open Liberty checks only the ID token for group information. From 5e6df8f522805fbe5759e7b7fc21f33a864f3258 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Tue, 21 Nov 2023 11:41:10 +0530 Subject: [PATCH 20/58] 7031-configdropins info to server config overview-2 7031-configdropins info to server config overview-2 #7031 --- .../config/server-configuration-overview.adoc | 38 ++++++------------- 1 file changed, 12 insertions(+), 26 deletions(-) diff --git a/modules/reference/pages/config/server-configuration-overview.adoc b/modules/reference/pages/config/server-configuration-overview.adoc index b66a33f140..daac0583fb 100644 --- a/modules/reference/pages/config/server-configuration-overview.adoc +++ b/modules/reference/pages/config/server-configuration-overview.adoc @@ -43,7 +43,6 @@ The following sections provide more details on configuring a server. * <<#variable-substitution,Variable substitution precedence>> * <<#configuration-merging,Configuration merging>> * <<#include-processing,Include processing>> -* <<#configDropins-directory,Using the configuration dropins folder to specify server sonfiguration>> * <<#configuration-references,Configuration references>> * <<#dynamic-updates,Dynamic updates>> * <<#log-messages,Log messages>> @@ -218,6 +217,18 @@ The `${server.config.dir}/server.xml` file must be present, but the other files You can flexibly compose configuration by dropping server-formatted XML files into directories. Files are read in alphabetical order in each of the two `configDropins` directories. +The `configDropins` directory offers a convenient method for adding or modifying server configuration without directly altering the `server.xml` file. Located under `usr/servers/server_name`, it includes two types of subdirectories: + +* Overrides (`usr/servers/server_name/configDropins/overrides`): This directory is used to override configurations in the `server.xml` file. For example, to change port configurations defined in `server.xml`, place the relevant configuration files here. + +* Defaults (`usr/servers/server_name/configDropins/defaults`): This directory is for setting defaults for configuration elements that are not specified in `server.xml`. It allows `server.xml` to remain the primary configuration source, with additional default settings provided through this directory. + +Changes to the configuration files placed in either the `configDropins/overrides` or `configDropins/defaults` directories are dynamically monitored. Additions, removals, or updates are reflected in the runtime configuration automatically. + +Configurations in the `configDropins/overrides` directory take precedence over those in the `server.xml` file, which in turn take precedence over configurations in the `configDropins/defaults` directory. Both `configDropins/overrides` and `configDropins/defaults` configurations supersede any default settings that are specified by a feature. + +To ensure consistency across different platforms, file names are converted to lowercase before sorting. If two files have the same name with case variations (like `extraConfig.xml` and `ExtraConfig.xml`), the order of processing might be unpredictable. + [#variable-syntax] == Configuration variable syntax @@ -515,31 +526,6 @@ Functionally, this configuration is the same as including each file separately w ---- -[#configDropins-directory] -== Using the configuration dropins folder to specify server configuration - -In Open Liberty, the `configDropins` directory is a convenient method for adding or modifying server configuration without directly altering the `server.xml` file. This directory is located under `usr/servers/server_name`. - -=== Types of subdirectories within configDropins - -* Overrides (`usr/servers/server_name/configDropins/overrides`): This directory is used to override configurations in the `server.xml` file. For example, to change port configurations defined in `server.xml`, place the relevant configuration files in this directory. - -* Defaults (`usr/servers/server_name/configDropins/defaults`): This directory is for setting defaults for configuration elements that are not specified in `server.xml`. It allows the `server.xml` file to remain the primary configuration source, with additional default settings provided through this directory. - -Configuration files placed in either the `configDropins/overrides` or `configDropins/defaults` directories are dynamically monitored. Changes, including additions, removals, or updates, are reflected in the runtime configuration automatically. - -=== Conflict Resolution and Precedence - -* Configurations in the `configDropins/overrides` directory take precedence over the configurations in the `server.xml` file. - -* Configurations in the `server.xml` file take precedence over the configurations in the `configDropins/defaults` directory. - -* Both `configDropins/defaults` and `configDropins/overrides` configurations supersede any default settings that are specified by a feature. - -* The configuration files in these directories are processed in alphabetical order. - -To ensure consistency across different platforms, file names are converted to lowercase before sorting alphabetically. If two files have the same name with case variations (like `extraConfig.xml` and `ExtraConfig.xml`), the order of processing might be unpredictable. - [#configuration-references] == Configuration references From 4ee1750102a16d83342d9e1512ce87cd74269cac Mon Sep 17 00:00:00 2001 From: David Mueller Date: Tue, 21 Nov 2023 11:58:52 -0500 Subject: [PATCH 21/58] edits per review #7023 --- .../pages/feature/openidConnectClient/examples.adoc | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/modules/reference/pages/feature/openidConnectClient/examples.adoc b/modules/reference/pages/feature/openidConnectClient/examples.adoc index 072dc1be29..88eea01d92 100644 --- a/modules/reference/pages/feature/openidConnectClient/examples.adoc +++ b/modules/reference/pages/feature/openidConnectClient/examples.adoc @@ -13,7 +13,7 @@ The following examples demonstrate configuration options for the OpenID Connect - <<#oauth,Accept an OAuth 2.0 bearer access token without redirecting to an OpenID Connect provider>> - <<#context,Modify the context root>> - <<#params,Pass request parameters to OpenID Connect>> -- <<#access-token,Check the access token for user group information>> +- <<#access-token,Check the access token for user and group information>> [#minimal] === Minimal configuration for Open Liberty to act as an OpenID Connect client @@ -362,15 +362,17 @@ To provide extra authorization parameters to the OP, configure `authzParameter` To configure parameters for the token endpoint, use the `tokenParameter` element. [#access-token] -=== Check the access token for user group information +=== Check the access token for user and group information -If a user's group information is not found in the ID token, you can configure Open Liberty to also check for this information in the Access token and the `UserInfo` endpoint. Set the `tokensOrderToFetchCallerClaims` attribute to `AccessToken IDToken Userinfo`, as shown in the following example. +If `userIdentifier` or `groupIdentifier` values are not found in the ID token, Open Liberty can also check in the access token and the `UserInfo` endpoint. + +Set the `tokensOrderToFetchCallerClaims` attribute to `AccessToken IDToken Userinfo`, as shown in the following example. [source,xml] ---- ---- -In this example, Open Liberty checks the access token first, then the ID token, and lastly, calls the `UserInfo` endpoint. If no group information is found in any of these these locations, an unauthorized response code is returned. +In this example, Open Liberty checks for `userIdentifier` and `groupIdentifier` values first in the access token, then the ID token, and lastly, calls the `UserInfo` endpoint. If the values are not found in any of those locations, an unauthorized response code is returned. -If the `tokensOrderToFetchCallerClaims` attribute is not specified, the default value is `IDToken` and Open Liberty checks only the ID token for group information. +If the `tokensOrderToFetchCallerClaims` attribute is not specified, the default value is `IDToken` and Open Liberty checks only the ID token for user and group information. From 3c93708b9bba374ff8b27d8fc91bd11b475ba4b9 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Thu, 23 Nov 2023 17:13:11 +0530 Subject: [PATCH 22/58] 7031-configdropins info to server config overview-3 7031-configdropins info to server config overview-3 #7031 --- .../pages/config/server-configuration-overview.adoc | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/modules/reference/pages/config/server-configuration-overview.adoc b/modules/reference/pages/config/server-configuration-overview.adoc index daac0583fb..65a168171b 100644 --- a/modules/reference/pages/config/server-configuration-overview.adoc +++ b/modules/reference/pages/config/server-configuration-overview.adoc @@ -225,9 +225,10 @@ The `configDropins` directory offers a convenient method for adding or modifying Changes to the configuration files placed in either the `configDropins/overrides` or `configDropins/defaults` directories are dynamically monitored. Additions, removals, or updates are reflected in the runtime configuration automatically. -Configurations in the `configDropins/overrides` directory take precedence over those in the `server.xml` file, which in turn take precedence over configurations in the `configDropins/defaults` directory. Both `configDropins/overrides` and `configDropins/defaults` configurations supersede any default settings that are specified by a feature. +Configurations in the `configDropins/overrides` directory take precedence over configurations in the `server.xml` file, which in turn take precedence over configurations in the `configDropins/defaults` directory. The configurations in 'configDropins/overrides' and 'configDropins/defaults' supersede any default settings a feature specifies. + +To maintain consistency across different platforms, file names are first converted to lowercase and then sorted. In scenarios where two files share an identical name but differ in case (such as `extraConfig.xml` and `ExtraConfig.xml`), their order of processing can be inconsistent. -To ensure consistency across different platforms, file names are converted to lowercase before sorting. If two files have the same name with case variations (like `extraConfig.xml` and `ExtraConfig.xml`), the order of processing might be unpredictable. [#variable-syntax] From a84b32fc496ad96d16d61f4f2a823c8d0b4b547e Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Fri, 24 Nov 2023 13:02:00 +0530 Subject: [PATCH 23/58] 7031-configdropins info to server config overview-4 7031-configdropins info to server config overview-4 #7031 --- .../pages/config/server-configuration-overview.adoc | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/modules/reference/pages/config/server-configuration-overview.adoc b/modules/reference/pages/config/server-configuration-overview.adoc index 65a168171b..0f1f2175b8 100644 --- a/modules/reference/pages/config/server-configuration-overview.adoc +++ b/modules/reference/pages/config/server-configuration-overview.adoc @@ -6,7 +6,6 @@ // Contributors: // IBM Corporation // -// :page-layout: general-reference :page-type: general = Server configuration overview @@ -487,7 +486,6 @@ When you specify a directory in the `include` location, you must append a slash When you include configuration from a URI for a remote resource, the `location` attribute must point to a single remote resource file and not a directory. For example, `\https://website.com/path/to/server.xml` is supported, but `\https://website.com/path/to/directory` is not. - By default, the include resource must exist. If the resource might not be available, set the `optional` attribute to `true`, as shown in the following example: [source,xml] @@ -545,6 +543,7 @@ The configuration element that makes the reference uses an attribute that always ---- + [#dynamic-updates] == Dynamic updates The server monitors the server XML configuration for updates and dynamically reloads when changes are detected. @@ -564,6 +563,7 @@ To disable file system polling and reload only when an MBean is notified, specif ---- + [#log-messages] == Log messages When the server runs, it might output log messages that reference configuration. @@ -580,3 +580,10 @@ Based on the following server XML configuration example, the `dataStore` element ---- + + + + + + + From ceebc5e380413aae6ff715a7930c9ed81f112c92 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Fri, 24 Nov 2023 16:17:17 +0530 Subject: [PATCH 24/58] 7031-configdropins info to server config overview-5 7031-configdropins info to server config overview-5 #7031 --- .../config/server-configuration-overview.adoc | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/modules/reference/pages/config/server-configuration-overview.adoc b/modules/reference/pages/config/server-configuration-overview.adoc index 0f1f2175b8..37bd081991 100644 --- a/modules/reference/pages/config/server-configuration-overview.adoc +++ b/modules/reference/pages/config/server-configuration-overview.adoc @@ -220,7 +220,7 @@ The `configDropins` directory offers a convenient method for adding or modifying * Overrides (`usr/servers/server_name/configDropins/overrides`): This directory is used to override configurations in the `server.xml` file. For example, to change port configurations defined in `server.xml`, place the relevant configuration files here. -* Defaults (`usr/servers/server_name/configDropins/defaults`): This directory is for setting defaults for configuration elements that are not specified in `server.xml`. It allows `server.xml` to remain the primary configuration source, with additional default settings provided through this directory. +* Defaults (`usr/servers/server_name/configDropins/defaults`): This directory is for setting defaults for configuration elements that are not specified in `server.xml`. It allows `server.xml` to remain the primary configuration source, with other default settings provided through this directory. Changes to the configuration files placed in either the `configDropins/overrides` or `configDropins/defaults` directories are dynamically monitored. Additions, removals, or updates are reflected in the runtime configuration automatically. @@ -229,7 +229,6 @@ Configurations in the `configDropins/overrides` directory take precedence over c To maintain consistency across different platforms, file names are first converted to lowercase and then sorted. In scenarios where two files share an identical name but differ in case (such as `extraConfig.xml` and `ExtraConfig.xml`), their order of processing can be inconsistent. - [#variable-syntax] == Configuration variable syntax @@ -350,6 +349,7 @@ The default is `${wlp.user.dir}/servers/${wlp.server.name}`. * `server.output.dir` - the directory where the server writes the workarea, logs, and other runtime-generated files. The default is `${server.config.dir}`. + [#configuration-merging] == Configuration merging Since the configuration can consist of multiple files, it is possible that two files provide the same configuration. @@ -358,6 +358,7 @@ In Open Liberty, configuration is separated into singleton and factory configura Singleton configuration is used to configure a single element (for example, logging). Factory configuration is used to configure multiple entities, such as an entire application or data source. + [#merging-singleton-configuration] === Merging singleton configuration For singleton configuration elements that are specified more than once, the configuration is merged. @@ -431,6 +432,7 @@ is treated as: ---- + [#merging-factory-configuration] === Merging factory configuration Factory configuration merges use the same rules as singleton configuration except elements are not automatically merged just because the element names match. @@ -453,7 +455,6 @@ The first application is `myapp.war`, which has a context root of `myawesomeapp` [#include-processing] == Include processing - You can include additional configuration resources in your server configuration by using the config:include[] element. When a server configuration file contains an include reference to another resource, the server processes the contents of the referenced resource as if they were included inline in place of the `include` element. @@ -580,10 +581,3 @@ Based on the following server XML configuration example, the `dataStore` element ---- - - - - - - - From b225e55f5a146958918c64cb42914796c8e57747 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Mon, 27 Nov 2023 21:57:09 +0530 Subject: [PATCH 25/58] 7031-configdropins info to server config overview-6 7031-configdropins info to server config overview-6 #7031 --- .../reference/pages/config/server-configuration-overview.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/reference/pages/config/server-configuration-overview.adoc b/modules/reference/pages/config/server-configuration-overview.adoc index 37bd081991..08e2401cbe 100644 --- a/modules/reference/pages/config/server-configuration-overview.adoc +++ b/modules/reference/pages/config/server-configuration-overview.adoc @@ -224,9 +224,9 @@ The `configDropins` directory offers a convenient method for adding or modifying Changes to the configuration files placed in either the `configDropins/overrides` or `configDropins/defaults` directories are dynamically monitored. Additions, removals, or updates are reflected in the runtime configuration automatically. -Configurations in the `configDropins/overrides` directory take precedence over configurations in the `server.xml` file, which in turn take precedence over configurations in the `configDropins/defaults` directory. The configurations in 'configDropins/overrides' and 'configDropins/defaults' supersede any default settings a feature specifies. +Configurations in the `configDropins/overrides` directory take precedence over configurations in the `server.xml` file, which in turn take precedence over configurations in the `configDropins/defaults` directory. The configurations in `configDropins/overrides` and `configDropins/defaults` supersede any default settings a feature specifies. -To maintain consistency across different platforms, file names are first converted to lowercase and then sorted. In scenarios where two files share an identical name but differ in case (such as `extraConfig.xml` and `ExtraConfig.xml`), their order of processing can be inconsistent. +To maintain consistency across different platforms, file names are first converted to lowercase and then sorted. In scenarios where two files share an identical name but differ in case (such as `extraConfig.xml` and `ExtraConfig.xml`), their order of processing might be inconsistent. [#variable-syntax] From 431ec050ccbf74081fb1b1bb4d0bacc919034fb9 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Tue, 28 Nov 2023 09:26:04 -0500 Subject: [PATCH 26/58] 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 5cc31732c480e4814f2907f045b338c397ec1cbd Mon Sep 17 00:00:00 2001 From: David Mueller Date: Tue, 28 Nov 2023 09:41:25 -0500 Subject: [PATCH 27/58] Update microprofile-telemetry.adoc --- .../ROOT/pages/microprofile-telemetry.adoc | 97 ++++++++++++++++++- 1 file changed, 93 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/microprofile-telemetry.adoc b/modules/ROOT/pages/microprofile-telemetry.adoc index d1e5f33a05..0dbf1af13c 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -12,19 +12,65 @@ :page-type: general = Enable distributed tracing with MicroProfile Telemetry +== Introducing OpenTelemetry == + In microservice applications, sources of latency or inaccuracy can be difficult to determine because relationships and dependencies among the constituent services are not always obvious. MicroProfile Telemetry helps you collect data on the paths that application requests take through services. One way to increase observability of an application is by emitting traces. Traces represent requests and consist of multiple spans. A span represents a single operation in a request and contains a name, time-related data, log messages, and metadata to gather data about what occurs during a transaction. link:https://projects.eclipse.org/projects/technology.microprofile/releases/microprofile-telemetry-1.0/plan%E2%80%A8%E2%80%A822.0.0.10-bet[MicroProfile Telemetry] is based on the https://opentelemetry.io/[OpenTelemetry project], which is a collection of open source vendor-agnostic tools, APIs, and SDKs for creating and managing trace data. You can enable MicroProfile Telemetry for Open Liberty by adding the feature:mpTelemetry[display=MicroProfile Telemetry] feature to your `server.xml` file and configuring the feature to connect to your distributed trace service. -MicroProfile Telemetry supports the instrumentation of tracing data in your code in three different ways: <<#auto, automatic instrumentation>>, <<#manual, manual instrumentation>>, or <<#agent, agent instrumentation>>. The data can then be exported to tracing systems like https://www.jaegertracing.io/[Jaeger] or https://zipkin.io/[Zipkin]. - MicroProfile Telemetry replaces MicroProfile OpenTracing. For information about migrating your applications from MicroProfile OpenTracing to MicroProfile Telemetry, see xref:reference:diff/mp-50-60-diff.adoc#telemetry[Differences between MicroProfile Telemetry 1.0 and MicroProfile OpenTracing 3.0]. +== Using OpenTelemetry == + +To enable OpenTelemetry you must add one the following features `mpTelemetry-1.0` or `mpTelemetry-1.1` to your server.xml file. + +By Default OpenTelemetry is disabled. To enable the generation of traces, set the property `otel.sdk.disabled=false`. + +To store the generated traces a OpenTelemetry storage solution such as Jaeger or Zipkin is required. To export the generated traces to these, an exporter definition is required that includes the exporter type and the endpoint to be connected to. For example you can add the following to your `bootstrap.properties` file: + +Configuring OpenTelemetry to use a Jager server: + +[source,properties] +---- +otel.sdk.disabled=false +otel.traces.exporter=otlp +otel.exporter.otlp.endpoint=http://localhost:4317/ +---- + +Configuring OpenTelemetry to use a Zipkin server: + +[source,properties] +---- +otel.sdk.disabled=false +otel.traces.exporter=zipkin +otel.exporter.zipkin.endpoint=http://localhost:9411/api/v2/spans +---- + +Once you have completed these prerequisites you can use one or more of: + +* <<#auto, automatic instrumentation>> - which automatically traces your JAX-RS or RESTful web services. +* <<#manual, manual instrumentation>> - which allows you to start and end telemetry spans manually. +* <<#agent, agent instrumentation>> - which automatically adds telemetry to popular open source libraries. Agent instrumentation imposes additional limitations which are documented in <<#agent, agent instrumentation>>. + +=== Telemetry Versions and Java Enterprise Editions === + +* `mpTelemetry-1.0` is compatible with `jakartaee-10.0` and `microProfile-6.0` +* `mpTelemetry-1.1` is compatible with +** `javaee-7.0` and `microProfile-1.4` +** `jakartaee-8.0` and `microProfile-4.1` +** `jakartaee-9.1` and `microProfile-5.0` +** `jakartaee-10.0` and `microProfile-6.1` + [#auto] == Automatic instrumentation -With automatic instrumentation, you can observe traces without modifying the source code in your Jakarta RESTful web service (formerly JAX-RS) applications. To start emitting traces with automatic instrumentation, enable the feature:mpTelemetry[display=MicroProfile Telemetry] feature in your `server.xml` file. By default, MicroProfile Telemetry tracing is off. To enable tracing, specify the `otel.sdk.disabled=false` MicroProfile Config property and any exporter configuration that your tracing service service requires. + +With automatic instrumentation, you can observe traces without modifying the source code in your JAX-RS or Jakarta RESTful web service applications. + +From Open Liberty version 23.0.0.11 onwards, spans are automatically generated for incoming HTTP requests, including static files, servlets, and JSPs. + +To start emitting traces with automatic instrumentation, enable the feature:mpTelemetry[display=MicroProfile Telemetry] feature in your `server.xml` file by adding `mpTelemetry-1.0` or `mpTelemetry-1.1` to your server.xml file. By default, MicroProfile Telemetry tracing is off. To enable tracing, specify the `otel.sdk.disabled=false` MicroProfile Config property and any exporter configuration that your tracing service service requires. For example, to export traces to a Jaeger server with the OpenTelemetry Protocol (OTLP) enabled, add the following entries to your `bootstrap.properties` file. @@ -44,13 +90,30 @@ otel.traces.exporter=zipkin otel.exporter.zipkin.endpoint=http://localhost:9411/api/v2/spans ---- +If you want to export traces to OpenLiberty's log files use the following properties: + +[source,properties] +---- +otel.sdk.disabled=false +otel.traces.exporter=logging +---- + You can configure how MicroProfile Telemetry collects and exports traces by specifying configuration properties in any of the xref:external-configuration.adoc#default[config sources that are available to MicroProfile Config]. If you set these properties by using environment variables, make the key name uppercase and convert any punctuation to underscores. For example, the `otel.sdk.disabled=false` property is equivalent to the `OTEL_SDK_DISABLED=false` environment variable. For more information about the available properties, see xref:microprofile-config-properties.adoc#telemetry[MicroProfile Config properties: MicroProfile Telemetry]. [#manual] == Manual instrumentation -Automatic instrumentation is available only for Jakarta RESTful web service applications. To create spans for other operations, such as database calls, you can add manual instrumentation to the source code for those operations by using the https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/1.19.0/io/opentelemetry/api/trace/package-summary.html[OpenTelemetry API]. However, before you manually instrument your code, you must complete the following prerequisites. +Automatic instrumentation is available only for JAX-RS and Jakarta RESTful web service applications. To create spans for other operations, such as database calls, you can add manual instrumentation to the source code for those operations by using the https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/1.19.0/io/opentelemetry/api/trace/package-summary.html[OpenTelemetry API]. However, before you manually instrument your code, you must complete the following prerequisites. + +- Enable OpenTelemetry by setting `otel.sdk.disabled=false` and configure an exporter. For example, to export traces to a Jaeger server with the OpenTelemetry Protocol (OTLP) enabled, add the following entries to your `bootstrap.properties` file. As with automatic instrumentation, you can instead set `otel.traces.exporter` to `zipkin` or `logging`. + +[source,properties] +---- +otel.sdk.disabled=false +otel.traces.exporter=otlp +otel.exporter.otlp.endpoint=http://localhost:4317/ +---- - Enable third-party APIs for your application by adding the following code in your `server.xml` file: + @@ -141,6 +204,8 @@ The following important considerations apply to manual instrumentation. - You must call the `.end()` method on any span you create, otherwise the span is not recorded. - The current span is used as the parent for any new spans that are created. Therefore, when you create a span, you usually also want to make it current. However, you must close the `Scope` instance that is returned by the `Span.makeCurrent()` method. You can close a `Scope` instance by specifying a try-with-resources block, as shown in the previous example for creating a subspan. +- Becuase Liberty supports per-application configuration it does not support `GlobalOpenTelemetry`. Using that class will not produce any telemetry data. +- If you set any properties by using environment variables, including the `server.env` file, the keys must be in upper case and all punctuation must be replaced by an underscore. Values must be written normally. For more information, see the https://opentelemetry.io/docs/instrumentation/java/manual[OpenTelemetry manual instrumentation documentation]. However, remember when you use the MicroProfile Telemetry feature in Open Liberty, you must obtain the `OpenTelemetry` and `Tracer` objects by injecting them, not by creating your own. Furthermore, be aware that this documentation includes information for the OpenTelemetry Metrics and Logging APIs, which are not supported by MicroProfile Telemetry. @@ -170,4 +235,28 @@ The OpenTelemetry Java agent is a tool that is provided by the OpenTelemetry pro * The agent is not compatible with https://www.ibm.com/docs/en/was-liberty/base?topic=security-java-2[Java 2 security]. * Open Liberty uses many open source libraries internally. Some of these libraries might be automatically instrumented by the agent. +== Troubleshooting +The following information can help you determine the cause of common problems and error messages. +Previous spans are incorrectly shown as current or parent spans:: + +If the `Scope` instance is not closed correctly, the context and baggage values of previous spans might remain when the next operation executes. Alternatively, the current span might remain and be picked up as the parent of the next operation that executes. + +Always close the `Scope` instance when you exit an operation. This configuration stops the span from being current and makes the previous span current again. Use a `try-with-resources` block, which automatically closes the `Scope` instance at the end of the block, as shown in the following example: + +[source, java] +---- +Span span = tracer.spanBuilder("PerformingOperation").startSpan(); +try (Scope scope = span.makeCurrent()) { + ... +} finally { + span.end(); +} +---- + +You receive the `CWMOT5100I` message that tracing is disabled:: + +If you enable the `mpTelemetry-1.1` or `mpTelemetry-1.0` feature, you must also set the `otel.sdk.disabled=false` property in any of the configuration sources that are accessible through MicroProfile Config to enable tracing. + +You receive the CWMOT5003W message that the application attempted to acquire MicroProfile Telemetry after shut down:: +Review the application to see why it attempted to use MicroProfile Telemetry after it shut down. Actions that might trigger the use of MicroProfile Telemetry include calling a method that is annotated with `@WithSpan`` or making a request with a JAX-RS Client or MP Rest Client. From f0087950d0be1b3e7fd1ac938523535871e28f82 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Tue, 28 Nov 2023 09:46:17 -0500 Subject: [PATCH 28/58] 230012 CVEs #7079 --- modules/ROOT/pages/security-vulnerabilities.adoc | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/modules/ROOT/pages/security-vulnerabilities.adoc b/modules/ROOT/pages/security-vulnerabilities.adoc index bfe082514d..6842b74a59 100644 --- a/modules/ROOT/pages/security-vulnerabilities.adoc +++ b/modules/ROOT/pages/security-vulnerabilities.adoc @@ -28,6 +28,20 @@ The `CWWKF0012I` message uses the word "installed", but it lists features that a |=== |CVE |CVSS score by X-Force® |Vulnerability assessment |Versions affected |Version fixed |Notes +|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-44487[CVE-2023-44487] +|7.5 +|Denial of service +|18.0.0.2 - 23.0.0.11 +|23.0.0.12 +|Affects the feature:servlet-3.1[], feature:servlet-4.0[], feature:servlet-5.0[] and feature:servlet-6.0[] features + +|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-44483[CVE-2023-44483] +|6.5 +|Information disclosure +|17.0.0.3 - 23.0.0.11 +|23.0.0.12 +|Affects the feature:wsSecurity-1.1[], feature:wsSecuritySaml-1.1[] and feature:samlWeb-2.0[] features + |http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-46158[CVE-2023-46158] |4.9 |Weaker security From a51febd5a0977497a9472e4c1be88a5d35c60ff5 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Tue, 28 Nov 2023 10:17:12 -0500 Subject: [PATCH 29/58] Add endpoint example #7068 --- .../pages/feature/mpOpenAPI-3.1/examples.adoc | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc b/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc index 222ae3fed3..1a23a5e27e 100644 --- a/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc +++ b/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc @@ -35,3 +35,16 @@ mp.openapi.extensions.liberty.merged.info= * The `mp.openapi.extensions.liberty.merged.info` property sets the `info` section for the final OpenAPI document, which documents web modules 1, 2, and 4. For more information, see xref:ROOT:documentation-openapi.adoc#multi-module[Multiple application and multi-module application support with MicroProfile OpenAPI] + +=== Configure MicroProfile OpenAPI documentation endpoints + +MicroProfile OpenAPI generates and serves OpenAPI documentation for Jakarta RESTful Services (formerly JAX-RS) applications that are deployed to the Open Liberty runtime. The OpenAPI documentation is served from the `:/openapi` endpoint and a user interface for browsing this documentation is served from the `:/openapi/ui` endpoint. + +In MicroProfile OpenAPI 3.1 and later, you can configure the paths for these endpoints. Specify the `docPath` and `uiPath` attributes for the `mpOpenAPI` element in your `server.xml` file. For example, the following configuration sets the OpenAPI documentation for an `appA` application to `/appA/openapi`, while the UI to browse that documentation is available at `/appA/openapi/docUi`: + +[source:xml] +---- + +---- + +When the `uiPath` attribute is not set, it defaults to the value of the `docPath` attribute with `/ui` appended. From 8b7add494818959bc4d0cf58e5565aee2895cda0 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Tue, 28 Nov 2023 11:09:23 -0500 Subject: [PATCH 30/58] 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 de1375f9930d7ef4416d52d19c88b7fa7e1f6e4c Mon Sep 17 00:00:00 2001 From: David Mueller Date: Tue, 28 Nov 2023 16:08:05 -0500 Subject: [PATCH 31/58] Update microprofile-telemetry.adoc --- .../ROOT/pages/microprofile-telemetry.adoc | 81 ++++++++++--------- 1 file changed, 41 insertions(+), 40 deletions(-) diff --git a/modules/ROOT/pages/microprofile-telemetry.adoc b/modules/ROOT/pages/microprofile-telemetry.adoc index 0dbf1af13c..6b5c587c45 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -12,25 +12,34 @@ :page-type: general = Enable distributed tracing with MicroProfile Telemetry -== Introducing OpenTelemetry == - In microservice applications, sources of latency or inaccuracy can be difficult to determine because relationships and dependencies among the constituent services are not always obvious. MicroProfile Telemetry helps you collect data on the paths that application requests take through services. One way to increase observability of an application is by emitting traces. Traces represent requests and consist of multiple spans. A span represents a single operation in a request and contains a name, time-related data, log messages, and metadata to gather data about what occurs during a transaction. link:https://projects.eclipse.org/projects/technology.microprofile/releases/microprofile-telemetry-1.0/plan%E2%80%A8%E2%80%A822.0.0.10-bet[MicroProfile Telemetry] is based on the https://opentelemetry.io/[OpenTelemetry project], which is a collection of open source vendor-agnostic tools, APIs, and SDKs for creating and managing trace data. You can enable MicroProfile Telemetry for Open Liberty by adding the feature:mpTelemetry[display=MicroProfile Telemetry] feature to your `server.xml` file and configuring the feature to connect to your distributed trace service. -MicroProfile Telemetry replaces MicroProfile OpenTracing. For information about migrating your applications from MicroProfile OpenTracing to MicroProfile Telemetry, see xref:reference:diff/mp-50-60-diff.adoc#telemetry[Differences between MicroProfile Telemetry 1.0 and MicroProfile OpenTracing 3.0]. +MicroProfile Telemetry replaces MicroProfile OpenTracing. For information about migrating your applications from MicroProfile OpenTracing to MicroProfile Telemetry, see xref:reference:diff/mp-50-60-diff.adoc#telemetry[Differences between MicroProfile Telemetry 1.0 and MicroProfile OpenTracing 3.0]. + +== OpenTelemetry configuration + +To enable OpenTelemetry, you must add the feature:mpTelemetry[display=MicroProfile Telemetry] feature to your `server.xml` file. Different versions of the MicroProfile Telemetry feature are compatible with different MicroProfile versions Jakarta and Java Enterprise Editions and the Open Liberty umbrella features that support them. -== Using OpenTelemetry == +* feature:mpTelemetry-1.0[] is compatible with feature:jakartaee-10.0[] and feature:microProfile-6.0[]. +* featutre:mpTelemetry-1.1[] is compatible with the following features: +** feature:javaee-7.0[] and feature:microProfile-1.4[] +** feature:jakartaee-8.0[] and feature:microProfile-4.1[] +** feature:jakartaee-9.1[] and feature:microProfile-5.0[] +** `jakartaee-10.0` and `microProfile-6.1` + +=== Configuration properties -To enable OpenTelemetry you must add one the following features `mpTelemetry-1.0` or `mpTelemetry-1.1` to your server.xml file. +You can configure how MicroProfile Telemetry collects and exports traces by specifying configuration properties in any of the xref:external-configuration.adoc#default[config sources that are available to MicroProfile Config]. If you choose to set these configuration properties by using environment variables, make the key name uppercase and convert any punctuation to underscores. For example, the `otel.sdk.disabled=false` property is equivalent to the `OTEL_SDK_DISABLED=false` environment variable. -By Default OpenTelemetry is disabled. To enable the generation of traces, set the property `otel.sdk.disabled=false`. +OpenTelemetry is disabled by default. To enable the generation of traces, set the `otel.sdk.disabled=false` property. -To store the generated traces a OpenTelemetry storage solution such as Jaeger or Zipkin is required. To export the generated traces to these, an exporter definition is required that includes the exporter type and the endpoint to be connected to. For example you can add the following to your `bootstrap.properties` file: +To store the generated traces, you need an OpenTelemetry storage solution, such as link:https://www.jaegertracing.io/[Jaeger] or link:https://zipkin.io/[Zipkin]. To export the generated traces to these systems, you must specify an exporter definition that includes the exporter type and the endpoint to connect to. -Configuring OpenTelemetry to use a Jager server: +For example, to use a Jaeger server, you might add configuration similar to the following example to your `bootstrap.properties` file: [source,properties] ---- @@ -39,7 +48,7 @@ otel.traces.exporter=otlp otel.exporter.otlp.endpoint=http://localhost:4317/ ---- -Configuring OpenTelemetry to use a Zipkin server: +Alternatively, to use a Zipkin server, you might add configuration similar to following example to your `bootstrap.properties`: [source,properties] ---- @@ -48,29 +57,31 @@ otel.traces.exporter=zipkin otel.exporter.zipkin.endpoint=http://localhost:9411/api/v2/spans ---- -Once you have completed these prerequisites you can use one or more of: +If you want to export traces to Open Liberty log files, set the following property: + +[source,properties] +---- +otel.traces.exporter=logging +---- -* <<#auto, automatic instrumentation>> - which automatically traces your JAX-RS or RESTful web services. -* <<#manual, manual instrumentation>> - which allows you to start and end telemetry spans manually. -* <<#agent, agent instrumentation>> - which automatically adds telemetry to popular open source libraries. Agent instrumentation imposes additional limitations which are documented in <<#agent, agent instrumentation>>. +For more information about the available properties, see xref:microprofile-config-properties.adoc#telemetry[MicroProfile Config properties: MicroProfile Telemetry]. -=== Telemetry Versions and Java Enterprise Editions === +== Code instrumentation -* `mpTelemetry-1.0` is compatible with `jakartaee-10.0` and `microProfile-6.0` -* `mpTelemetry-1.1` is compatible with -** `javaee-7.0` and `microProfile-1.4` -** `jakartaee-8.0` and `microProfile-4.1` -** `jakartaee-9.1` and `microProfile-5.0` -** `jakartaee-10.0` and `microProfile-6.1` +After you enable OpenTelemetry and configure a trace server, you can instrument tracing by using one of the following methods: + +* <<#auto, automatic instrumentation>>, which automatically traces your RESTful web services (JAX-RS). +* <<#manual, manual instrumentation>>, which allows you to start and end telemetry spans manually. +* <<#agent, agent instrumentation>>, which automatically adds telemetry to popular open source libraries. However, agent instrumentation also imposes certain <<#limit, limitations>>. [#auto] -== Automatic instrumentation +=== Automatic instrumentation -With automatic instrumentation, you can observe traces without modifying the source code in your JAX-RS or Jakarta RESTful web service applications. +With automatic instrumentation, you can observe traces without modifying the source code in your JAX-RS or Jakarta RESTful web service applications. From Open Liberty version 23.0.0.11 onwards, spans are automatically generated for incoming HTTP requests, including static files, servlets, and JSPs. -To start emitting traces with automatic instrumentation, enable the feature:mpTelemetry[display=MicroProfile Telemetry] feature in your `server.xml` file by adding `mpTelemetry-1.0` or `mpTelemetry-1.1` to your server.xml file. By default, MicroProfile Telemetry tracing is off. To enable tracing, specify the `otel.sdk.disabled=false` MicroProfile Config property and any exporter configuration that your tracing service service requires. +To start emitting traces with automatic instrumentation, enable the MicroProfile Telemetry feature in your `server.xml` file by adding `mpTelemetry-1.0` or `mpTelemetry-1.1` to your server.xml file. By default, MicroProfile Telemetry tracing is off. To enable tracing, specify the `otel.sdk.disabled=false` MicroProfile Config property and any exporter configuration that your tracing service service requires. For example, to export traces to a Jaeger server with the OpenTelemetry Protocol (OTLP) enabled, add the following entries to your `bootstrap.properties` file. @@ -90,20 +101,8 @@ otel.traces.exporter=zipkin otel.exporter.zipkin.endpoint=http://localhost:9411/api/v2/spans ---- -If you want to export traces to OpenLiberty's log files use the following properties: - -[source,properties] ----- -otel.sdk.disabled=false -otel.traces.exporter=logging ----- - -You can configure how MicroProfile Telemetry collects and exports traces by specifying configuration properties in any of the xref:external-configuration.adoc#default[config sources that are available to MicroProfile Config]. If you set these properties by using environment variables, make the key name uppercase and convert any punctuation to underscores. For example, the `otel.sdk.disabled=false` property is equivalent to the `OTEL_SDK_DISABLED=false` environment variable. - -For more information about the available properties, see xref:microprofile-config-properties.adoc#telemetry[MicroProfile Config properties: MicroProfile Telemetry]. - [#manual] -== Manual instrumentation +=== Manual instrumentation Automatic instrumentation is available only for JAX-RS and Jakarta RESTful web service applications. To create spans for other operations, such as database calls, you can add manual instrumentation to the source code for those operations by using the https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/1.19.0/io/opentelemetry/api/trace/package-summary.html[OpenTelemetry API]. However, before you manually instrument your code, you must complete the following prerequisites. - Enable OpenTelemetry by setting `otel.sdk.disabled=false` and configure an exporter. For example, to export traces to a Jaeger server with the OpenTelemetry Protocol (OTLP) enabled, add the following entries to your `bootstrap.properties` file. As with automatic instrumentation, you can instead set `otel.traces.exporter` to `zipkin` or `logging`. @@ -198,7 +197,7 @@ class SpanBean { } ---- -=== Considerations for using manual instrumentation +==== Considerations for using manual instrumentation The following important considerations apply to manual instrumentation. @@ -210,7 +209,7 @@ The following important considerations apply to manual instrumentation. For more information, see the https://opentelemetry.io/docs/instrumentation/java/manual[OpenTelemetry manual instrumentation documentation]. However, remember when you use the MicroProfile Telemetry feature in Open Liberty, you must obtain the `OpenTelemetry` and `Tracer` objects by injecting them, not by creating your own. Furthermore, be aware that this documentation includes information for the OpenTelemetry Metrics and Logging APIs, which are not supported by MicroProfile Telemetry. [#agent] -== Agent instrumentation +=== Agent instrumentation The https://github.com/open-telemetry/opentelemetry-java-instrumentation[OpenTelemetry Instrumentation for Java] project provides a Java agent JAR file that can be attached to any Java 8+ application. This file dynamically injects bytecode that adds telemetry support to popular open source libraries and frameworks. If you are using any of the https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md#libraries--frameworks[supported libraries] in your application, you can use this agent with Open Liberty to instrument them. To enable the Java agent on your Open Liberty runtime, https://github.com/open-telemetry/opentelemetry-java-instrumentation#getting-started[download the latest agent version from OpenTelemetry] and add the following line to your `jvm.options` file. @@ -222,7 +221,8 @@ To enable the Java agent on your Open Liberty runtime, https://github.com/open-t You can configure the agent with https://github.com/open-telemetry/opentelemetry-java-instrumentation#configuring-the-agent[environment variables and system properties]. You can find a list of supported libraries and frameworks in the https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md#libraries--frameworks[OpenTelemetry Java instrumentation documentation]. -=== Limitations of agent instrumentation +[#limit] +==== Limitations of agent instrumentation The OpenTelemetry Java agent is a tool that is provided by the OpenTelemetry project. Although it is compatible with Open Liberty, it is a separate project and is subject to the following limitations. @@ -235,8 +235,9 @@ The OpenTelemetry Java agent is a tool that is provided by the OpenTelemetry pro * The agent is not compatible with https://www.ibm.com/docs/en/was-liberty/base?topic=security-java-2[Java 2 security]. * Open Liberty uses many open source libraries internally. Some of these libraries might be automatically instrumented by the agent. -== Troubleshooting +== Troubleshooting Microprofile Telemetry The following information can help you determine the cause of common problems and error messages. + Previous spans are incorrectly shown as current or parent spans:: If the `Scope` instance is not closed correctly, the context and baggage values of previous spans might remain when the next operation executes. Alternatively, the current span might remain and be picked up as the parent of the next operation that executes. From e45e1dfe439da038c4a3cc28510ce7eef73e6c95 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Wed, 29 Nov 2023 10:20:04 -0500 Subject: [PATCH 32/58] ID revision #6776 --- .../ROOT/pages/microprofile-telemetry.adoc | 79 +++++++++++-------- 1 file changed, 45 insertions(+), 34 deletions(-) diff --git a/modules/ROOT/pages/microprofile-telemetry.adoc b/modules/ROOT/pages/microprofile-telemetry.adoc index 6b5c587c45..4a2e0cefeb 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -16,14 +16,19 @@ In microservice applications, sources of latency or inaccuracy can be difficult One way to increase observability of an application is by emitting traces. Traces represent requests and consist of multiple spans. A span represents a single operation in a request and contains a name, time-related data, log messages, and metadata to gather data about what occurs during a transaction. -link:https://projects.eclipse.org/projects/technology.microprofile/releases/microprofile-telemetry-1.0/plan%E2%80%A8%E2%80%A822.0.0.10-bet[MicroProfile Telemetry] is based on the https://opentelemetry.io/[OpenTelemetry project], which is a collection of open source vendor-agnostic tools, APIs, and SDKs for creating and managing trace data. You can enable MicroProfile Telemetry for Open Liberty by adding the feature:mpTelemetry[display=MicroProfile Telemetry] feature to your `server.xml` file and configuring the feature to connect to your distributed trace service. +link:https://projects.eclipse.org/projects/technology.microprofile/releases/microprofile-telemetry-1.0/plan%E2%80%A8%E2%80%A822.0.0.10-bet[MicroProfile Telemetry] is based on the https://opentelemetry.io/[OpenTelemetry project], which is a collection of open source vendor-independent tools, APIs, and SDKs for creating and managing trace data. You can enable MicroProfile Telemetry for Open Liberty by adding the feature:mpTelemetry[display=MicroProfile Telemetry] feature to your `server.xml` file and configuring the feature to connect to your distributed trace service. MicroProfile Telemetry replaces MicroProfile OpenTracing. For information about migrating your applications from MicroProfile OpenTracing to MicroProfile Telemetry, see xref:reference:diff/mp-50-60-diff.adoc#telemetry[Differences between MicroProfile Telemetry 1.0 and MicroProfile OpenTracing 3.0]. -== OpenTelemetry configuration +[#ol-config] +== Configuring Open Liberty to use MicroProfile Telemetry -To enable OpenTelemetry, you must add the feature:mpTelemetry[display=MicroProfile Telemetry] feature to your `server.xml` file. Different versions of the MicroProfile Telemetry feature are compatible with different MicroProfile versions Jakarta and Java Enterprise Editions and the Open Liberty umbrella features that support them. +To enable MicroProfile Telemetry in your Open Liberty runtime, you must add the MicroProfile Telemetry feature to your `server.xml` file and specify MicroProfile Config properties to configure how MicroProfile Telemetry collects and exports traces. +. Add a version of the feature:mpTelemetry[display=MicroProfile Telemetry] feature to your `server.xml` file. ++ +Different versions of the MicroProfile Telemetry feature are compatible with different MicroProfile versions Jakarta and Java Enterprise Editions and the Open Liberty umbrella features that support them. ++ * feature:mpTelemetry-1.0[] is compatible with feature:jakartaee-10.0[] and feature:microProfile-6.0[]. * featutre:mpTelemetry-1.1[] is compatible with the following features: ** feature:javaee-7.0[] and feature:microProfile-1.4[] @@ -31,25 +36,27 @@ To enable OpenTelemetry, you must add the feature:mpTelemetry[display=MicroProfi ** feature:jakartaee-9.1[] and feature:microProfile-5.0[] ** `jakartaee-10.0` and `microProfile-6.1` -=== Configuration properties - +. Enable tracing and configure a trace storage system by specifying MicroProfile Config properties. ++ You can configure how MicroProfile Telemetry collects and exports traces by specifying configuration properties in any of the xref:external-configuration.adoc#default[config sources that are available to MicroProfile Config]. If you choose to set these configuration properties by using environment variables, make the key name uppercase and convert any punctuation to underscores. For example, the `otel.sdk.disabled=false` property is equivalent to the `OTEL_SDK_DISABLED=false` environment variable. +.. Enable the generation of traces by setting the `otel.sdk.disabled` property to `false`. ++ OpenTelemetry is disabled by default. To enable the generation of traces, set the `otel.sdk.disabled=false` property. -To store the generated traces, you need an OpenTelemetry storage solution, such as link:https://www.jaegertracing.io/[Jaeger] or link:https://zipkin.io/[Zipkin]. To export the generated traces to these systems, you must specify an exporter definition that includes the exporter type and the endpoint to connect to. - +.. Configure a trace storage system by specifying an exporter definition that includes the exporter type and the endpoint to connect to. ++ For example, to use a Jaeger server, you might add configuration similar to the following example to your `bootstrap.properties` file: - ++ [source,properties] ---- otel.sdk.disabled=false otel.traces.exporter=otlp otel.exporter.otlp.endpoint=http://localhost:4317/ ---- - -Alternatively, to use a Zipkin server, you might add configuration similar to following example to your `bootstrap.properties`: - ++ +Alternatively, to use a Zipkin server, you might add configuration similar to the following example to your `bootstrap.properties` file: ++ [source,properties] ---- otel.sdk.disabled=false @@ -57,31 +64,38 @@ otel.traces.exporter=zipkin otel.exporter.zipkin.endpoint=http://localhost:9411/api/v2/spans ---- -If you want to export traces to Open Liberty log files, set the following property: - +.. Optionally, set other MicroProfile Config properties to configure trace details. ++ +For example, if you want to export traces to Open Liberty log files, set the following property: ++ [source,properties] ---- otel.traces.exporter=logging ---- - ++ For more information about the available properties, see xref:microprofile-config-properties.adoc#telemetry[MicroProfile Config properties: MicroProfile Telemetry]. +. Depending on how you choose to instrument your application code for tracing, further configuration might be required. ++ +For more information, see the following section. + == Code instrumentation -After you enable OpenTelemetry and configure a trace server, you can instrument tracing by using one of the following methods: +After you enable MicroProfile Telemetry and configure a trace server, you can instrument tracing in your application code by using one of the following methods: -* <<#auto, automatic instrumentation>>, which automatically traces your RESTful web services (JAX-RS). +* <<#auto, automatic instrumentation>>, which automatically traces your JAX-RS or RESTful web services. * <<#manual, manual instrumentation>>, which allows you to start and end telemetry spans manually. * <<#agent, agent instrumentation>>, which automatically adds telemetry to popular open source libraries. However, agent instrumentation also imposes certain <<#limit, limitations>>. [#auto] === Automatic instrumentation -With automatic instrumentation, you can observe traces without modifying the source code in your JAX-RS or Jakarta RESTful web service applications. +With automatic instrumentation, you can observe traces without modifying the source code in your applications. However, automatic instrumentation is available only for JAX-RS and Jakarta RESTful web service applications. From Open Liberty version 23.0.0.11 onwards, spans are automatically generated for incoming HTTP requests, including static files, servlets, and JSPs. -To start emitting traces with automatic instrumentation, enable the MicroProfile Telemetry feature in your `server.xml` file by adding `mpTelemetry-1.0` or `mpTelemetry-1.1` to your server.xml file. By default, MicroProfile Telemetry tracing is off. To enable tracing, specify the `otel.sdk.disabled=false` MicroProfile Config property and any exporter configuration that your tracing service service requires. +//// +To start emitting traces with automatic instrumentation, enable the MicroProfile Telemetry feature in your `server.xml` file by adding `mpTelemetry-1.0` or `mpTelemetry-1.1` to your server.xml file. By default, MicroProfile Telemetry tracing is off. To enable tracing, specify the `otel.sdk.disabled=false` MicroProfile Config property and any exporter configuration that your tracing service requires. For example, to export traces to a Jaeger server with the OpenTelemetry Protocol (OTLP) enabled, add the following entries to your `bootstrap.properties` file. @@ -100,21 +114,18 @@ otel.sdk.disabled=false otel.traces.exporter=zipkin otel.exporter.zipkin.endpoint=http://localhost:9411/api/v2/spans ---- +//// [#manual] === Manual instrumentation -Automatic instrumentation is available only for JAX-RS and Jakarta RESTful web service applications. To create spans for other operations, such as database calls, you can add manual instrumentation to the source code for those operations by using the https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/1.19.0/io/opentelemetry/api/trace/package-summary.html[OpenTelemetry API]. However, before you manually instrument your code, you must complete the following prerequisites. -- Enable OpenTelemetry by setting `otel.sdk.disabled=false` and configure an exporter. For example, to export traces to a Jaeger server with the OpenTelemetry Protocol (OTLP) enabled, add the following entries to your `bootstrap.properties` file. As with automatic instrumentation, you can instead set `otel.traces.exporter` to `zipkin` or `logging`. +Automatic instrumentation is available only for JAX-RS and Jakarta RESTful web service applications. To create spans for other operations, such as database calls, you can add manual instrumentation to the source code for those operations by using the https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/1.19.0/io/opentelemetry/api/trace/package-summary.html[OpenTelemetry API]. However, before you manually instrument your code, you must complete the following prerequisites. -[source,properties] ----- -otel.sdk.disabled=false -otel.traces.exporter=otlp -otel.exporter.otlp.endpoint=http://localhost:4317/ ----- +. Enable OpenTelemetry by setting `otel.sdk.disabled=false` and configure an exporter. ++ +For more information, see <<#ol-config,Configuring Open Liberty to use MicroProfile Telemetry>>. -- Enable third-party APIs for your application by adding the following code in your `server.xml` file: +. Enable third-party APIs for your application by adding the following code in your `server.xml` file: + [source,xml] ---- @@ -123,7 +134,7 @@ otel.exporter.otlp.endpoint=http://localhost:4317/ ---- -- Add the `opentelemetry` API and OpenTelemetry instrumentation annotations as a provided dependency to your build path. For example, with Maven, add the following code to your `pom.xml` file. +. Add the `opentelemetry` API and OpenTelemetry instrumentation annotations as a provided dependency to your build path. For example, with Maven, add the following code to your `pom.xml` file. + [source,xml] ---- @@ -159,7 +170,7 @@ public String myMethod() { } ---- -- Create a subspan around a particular operation, such as querying a database. This subspan allows you to see how long it took and the order in which it occurred relative to other spans. +- Create a subspan around a particular operation, such as querying a database. This subspan shows you how long it took and the order in which it occurred relative to other spans. + [source,java] ---- @@ -202,9 +213,9 @@ class SpanBean { The following important considerations apply to manual instrumentation. - You must call the `.end()` method on any span you create, otherwise the span is not recorded. -- The current span is used as the parent for any new spans that are created. Therefore, when you create a span, you usually also want to make it current. However, you must close the `Scope` instance that is returned by the `Span.makeCurrent()` method. You can close a `Scope` instance by specifying a try-with-resources block, as shown in the previous example for creating a subspan. -- Becuase Liberty supports per-application configuration it does not support `GlobalOpenTelemetry`. Using that class will not produce any telemetry data. -- If you set any properties by using environment variables, including the `server.env` file, the keys must be in upper case and all punctuation must be replaced by an underscore. Values must be written normally. +- The current span is used as the parent for any new spans that are created. Therefore, when you create a span, you usually also want to make it current. However, you must close the `Scope` instance that is returned by the `Span.makeCurrent()` method. You can close a `Scope` instance by specifying a try-with-resources block, as shown in the previous example for creating a subspan. +- Because Liberty supports per-application configuration, it does not support `GlobalOpenTelemetry`. Using that class will not produce any telemetry data. +- If you set any properties by using environment variables, including the `server.env` file, the keys must be in uppercase and all punctuation must be replaced by an underscore. Values must be written normally. For more information, see the https://opentelemetry.io/docs/instrumentation/java/manual[OpenTelemetry manual instrumentation documentation]. However, remember when you use the MicroProfile Telemetry feature in Open Liberty, you must obtain the `OpenTelemetry` and `Tracer` objects by injecting them, not by creating your own. Furthermore, be aware that this documentation includes information for the OpenTelemetry Metrics and Logging APIs, which are not supported by MicroProfile Telemetry. @@ -256,8 +267,8 @@ try (Scope scope = span.makeCurrent()) { You receive the `CWMOT5100I` message that tracing is disabled:: -If you enable the `mpTelemetry-1.1` or `mpTelemetry-1.0` feature, you must also set the `otel.sdk.disabled=false` property in any of the configuration sources that are accessible through MicroProfile Config to enable tracing. +If you enable the `mpTelemetry-1.1` or `mpTelemetry-1.0` feature, you must also set the `otel.sdk.disabled=false` property in any of the configuration sources that are accessible through MicroProfile Config to enable tracing. You receive the CWMOT5003W message that the application attempted to acquire MicroProfile Telemetry after shut down:: -Review the application to see why it attempted to use MicroProfile Telemetry after it shut down. Actions that might trigger the use of MicroProfile Telemetry include calling a method that is annotated with `@WithSpan`` or making a request with a JAX-RS Client or MP Rest Client. +Review the application to see why it attempted to use MicroProfile Telemetry after it shut down. Actions that might trigger MicroProfile Telemetry include calling a method that is annotated with `@WithSpan`` or making a request with a JAX-RS Client or MP Rest Client. From b86edcf628bb53178b73f5c0c8ccea4de8bcabc3 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Wed, 29 Nov 2023 11:19:48 -0500 Subject: [PATCH 33/58] apply example to all feature versions #7068 --- .../pages/feature/mpOpenAPI-3.1/examples.adoc | 13 ------------- .../pages/feature/mpOpenAPI/examples.adoc | 15 +++++++++++++++ 2 files changed, 15 insertions(+), 13 deletions(-) create mode 100644 modules/reference/pages/feature/mpOpenAPI/examples.adoc diff --git a/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc b/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc index 1a23a5e27e..222ae3fed3 100644 --- a/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc +++ b/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc @@ -35,16 +35,3 @@ mp.openapi.extensions.liberty.merged.info= * The `mp.openapi.extensions.liberty.merged.info` property sets the `info` section for the final OpenAPI document, which documents web modules 1, 2, and 4. For more information, see xref:ROOT:documentation-openapi.adoc#multi-module[Multiple application and multi-module application support with MicroProfile OpenAPI] - -=== Configure MicroProfile OpenAPI documentation endpoints - -MicroProfile OpenAPI generates and serves OpenAPI documentation for Jakarta RESTful Services (formerly JAX-RS) applications that are deployed to the Open Liberty runtime. The OpenAPI documentation is served from the `:/openapi` endpoint and a user interface for browsing this documentation is served from the `:/openapi/ui` endpoint. - -In MicroProfile OpenAPI 3.1 and later, you can configure the paths for these endpoints. Specify the `docPath` and `uiPath` attributes for the `mpOpenAPI` element in your `server.xml` file. For example, the following configuration sets the OpenAPI documentation for an `appA` application to `/appA/openapi`, while the UI to browse that documentation is available at `/appA/openapi/docUi`: - -[source:xml] ----- - ----- - -When the `uiPath` attribute is not set, it defaults to the value of the `docPath` attribute with `/ui` appended. diff --git a/modules/reference/pages/feature/mpOpenAPI/examples.adoc b/modules/reference/pages/feature/mpOpenAPI/examples.adoc new file mode 100644 index 0000000000..0a72738509 --- /dev/null +++ b/modules/reference/pages/feature/mpOpenAPI/examples.adoc @@ -0,0 +1,15 @@ + +== Examples + +=== Configure MicroProfile OpenAPI documentation endpoints + +MicroProfile OpenAPI generates and serves OpenAPI documentation for Jakarta RESTful Services or JAX-RS applications that are deployed to the Open Liberty runtime. The OpenAPI documentation is served from the `:/openapi` endpoint and a user interface for browsing this documentation is served from the `:/openapi/ui` endpoint. + +You can configure the paths for these endpoints. Specify the `docPath` and `uiPath` attributes for the `mpOpenAPI` element in your `server.xml` file. For example, the following configuration sets the OpenAPI documentation for an `appA` application to `/appA/openapi`, while the UI to browse that documentation is available at `/appA/openapi/docUi`: + +[source:xml] +---- + +---- + +When the `uiPath` attribute is not set, it defaults to the value of the `docPath` attribute with `/ui` appended. From f70e3aff9e382a994dcf152e778973ab128fecaf Mon Sep 17 00:00:00 2001 From: David Mueller Date: Wed, 29 Nov 2023 11:52:09 -0500 Subject: [PATCH 34/58] add OCP #7090 --- modules/ROOT/pages/instanton.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/ROOT/pages/instanton.adoc b/modules/ROOT/pages/instanton.adoc index 92f270725a..f6c40069a4 100644 --- a/modules/ROOT/pages/instanton.adoc +++ b/modules/ROOT/pages/instanton.adoc @@ -318,6 +318,7 @@ Currently, Open Liberty InstantOn is tested and supported on the following publi - link:https://aws.amazon.com/eks/[Amazon Elastic Kubernetes Service (EKS)] - link:https://azure.microsoft.com/en-us/products/kubernetes-service[Azure Kubernetes Service (AKS)] +- link:https://www.redhat.com/en/technologies/cloud-computing/openshift[Red Hat OpenShift] (version 4.14 and later) Other public cloud Kubernetes services might also work if they have the <<#required-to-restore,prerequisites>> to allow the InstantOn application process to restore. From a61a790491eaf00a0e9df95a7761c2f4e6125303 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Wed, 29 Nov 2023 13:55:48 -0500 Subject: [PATCH 35/58] edits #6776 --- .../ROOT/pages/microprofile-telemetry.adoc | 27 ++++++++----------- 1 file changed, 11 insertions(+), 16 deletions(-) diff --git a/modules/ROOT/pages/microprofile-telemetry.adoc b/modules/ROOT/pages/microprofile-telemetry.adoc index 4a2e0cefeb..c457150cd3 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -27,14 +27,11 @@ To enable MicroProfile Telemetry in your Open Liberty runtime, you must add the . Add a version of the feature:mpTelemetry[display=MicroProfile Telemetry] feature to your `server.xml` file. + -Different versions of the MicroProfile Telemetry feature are compatible with different MicroProfile versions Jakarta and Java Enterprise Editions and the Open Liberty umbrella features that support them. +Different versions of the MicroProfile Telemetry feature are compatible with different MicroProfile versions Jakarta and Java Enterprise Editions and the Open Liberty umbrella features that support them. Both feature:mpTelemetry-1.0[] and feature:mpTelemetry-1.1[] are compatible with feature:jakartaee-10.0[] and feature:microProfile-6.0[]. However, `mpTelemetry-1.1` is also compatible with the following earlier umbrella features: + -* feature:mpTelemetry-1.0[] is compatible with feature:jakartaee-10.0[] and feature:microProfile-6.0[]. -* featutre:mpTelemetry-1.1[] is compatible with the following features: -** feature:javaee-7.0[] and feature:microProfile-1.4[] -** feature:jakartaee-8.0[] and feature:microProfile-4.1[] -** feature:jakartaee-9.1[] and feature:microProfile-5.0[] -** `jakartaee-10.0` and `microProfile-6.1` +* feature:javaee-7.0[] and feature:microProfile-1.4[] +* feature:jakartaee-8.0[] and feature:microProfile-4.1[] +* feature:jakartaee-9.1[] and feature:microProfile-5.0[] . Enable tracing and configure a trace storage system by specifying MicroProfile Config properties. + @@ -84,15 +81,15 @@ For more information, see the following section. After you enable MicroProfile Telemetry and configure a trace server, you can instrument tracing in your application code by using one of the following methods: * <<#auto, automatic instrumentation>>, which automatically traces your JAX-RS or RESTful web services. -* <<#manual, manual instrumentation>>, which allows you to start and end telemetry spans manually. +* <<#manual, manual instrumentation>>, which allows you to start and end telemetry spans manually for applications that are not JAX-RS or RESTful web services. * <<#agent, agent instrumentation>>, which automatically adds telemetry to popular open source libraries. However, agent instrumentation also imposes certain <<#limit, limitations>>. [#auto] === Automatic instrumentation -With automatic instrumentation, you can observe traces without modifying the source code in your applications. However, automatic instrumentation is available only for JAX-RS and Jakarta RESTful web service applications. +With automatic instrumentation, you can observe traces without modifying the source code in your applications. All you need to do is configure your server, as described in <<#ol-config,Configuring Open Liberty to use MicroProfile Telemetry>>. However, automatic instrumentation is available only for JAX-RS and Jakarta RESTful web service applications. -From Open Liberty version 23.0.0.11 onwards, spans are automatically generated for incoming HTTP requests, including static files, servlets, and JSPs. +In Open Liberty version 23.0.0.11 and later, spans are automatically generated for incoming HTTP requests, including static files, servlets, and JSPs. //// To start emitting traces with automatic instrumentation, enable the MicroProfile Telemetry feature in your `server.xml` file by adding `mpTelemetry-1.0` or `mpTelemetry-1.1` to your server.xml file. By default, MicroProfile Telemetry tracing is off. To enable tracing, specify the `otel.sdk.disabled=false` MicroProfile Config property and any exporter configuration that your tracing service requires. @@ -121,9 +118,7 @@ otel.exporter.zipkin.endpoint=http://localhost:9411/api/v2/spans Automatic instrumentation is available only for JAX-RS and Jakarta RESTful web service applications. To create spans for other operations, such as database calls, you can add manual instrumentation to the source code for those operations by using the https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/1.19.0/io/opentelemetry/api/trace/package-summary.html[OpenTelemetry API]. However, before you manually instrument your code, you must complete the following prerequisites. -. Enable OpenTelemetry by setting `otel.sdk.disabled=false` and configure an exporter. -+ -For more information, see <<#ol-config,Configuring Open Liberty to use MicroProfile Telemetry>>. +. Enable MicroPRofile Telemetry, as described in <<#ol-config,Configuring Open Liberty to use MicroProfile Telemetry>>. . Enable third-party APIs for your application by adding the following code in your `server.xml` file: + @@ -214,8 +209,8 @@ The following important considerations apply to manual instrumentation. - You must call the `.end()` method on any span you create, otherwise the span is not recorded. - The current span is used as the parent for any new spans that are created. Therefore, when you create a span, you usually also want to make it current. However, you must close the `Scope` instance that is returned by the `Span.makeCurrent()` method. You can close a `Scope` instance by specifying a try-with-resources block, as shown in the previous example for creating a subspan. -- Because Liberty supports per-application configuration, it does not support `GlobalOpenTelemetry`. Using that class will not produce any telemetry data. -- If you set any properties by using environment variables, including the `server.env` file, the keys must be in uppercase and all punctuation must be replaced by an underscore. Values must be written normally. +- Because Liberty supports per-application configuration, it does not support `GlobalOpenTelemetry`. Using that class does not produce any telemetry data. +- If you set any properties by using environment variables, including the in the `server.env` file, the keys must be in uppercase and all punctuation must be replaced by an underscore. Values must be written normally. For more information, see the https://opentelemetry.io/docs/instrumentation/java/manual[OpenTelemetry manual instrumentation documentation]. However, remember when you use the MicroProfile Telemetry feature in Open Liberty, you must obtain the `OpenTelemetry` and `Tracer` objects by injecting them, not by creating your own. Furthermore, be aware that this documentation includes information for the OpenTelemetry Metrics and Logging APIs, which are not supported by MicroProfile Telemetry. @@ -246,7 +241,7 @@ The OpenTelemetry Java agent is a tool that is provided by the OpenTelemetry pro * The agent is not compatible with https://www.ibm.com/docs/en/was-liberty/base?topic=security-java-2[Java 2 security]. * Open Liberty uses many open source libraries internally. Some of these libraries might be automatically instrumented by the agent. -== Troubleshooting Microprofile Telemetry +== Troubleshooting MicroProfile Telemetry The following information can help you determine the cause of common problems and error messages. Previous spans are incorrectly shown as current or parent spans:: From 034e6475dde66a068709ed2968fd62f314b5d84b Mon Sep 17 00:00:00 2001 From: David Mueller Date: Wed, 29 Nov 2023 15:47:09 -0500 Subject: [PATCH 36/58] edits #6776 --- modules/ROOT/pages/microprofile-telemetry.adoc | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/modules/ROOT/pages/microprofile-telemetry.adoc b/modules/ROOT/pages/microprofile-telemetry.adoc index c457150cd3..bd0cebd30a 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -27,7 +27,7 @@ To enable MicroProfile Telemetry in your Open Liberty runtime, you must add the . Add a version of the feature:mpTelemetry[display=MicroProfile Telemetry] feature to your `server.xml` file. + -Different versions of the MicroProfile Telemetry feature are compatible with different MicroProfile versions Jakarta and Java Enterprise Editions and the Open Liberty umbrella features that support them. Both feature:mpTelemetry-1.0[] and feature:mpTelemetry-1.1[] are compatible with feature:jakartaee-10.0[] and feature:microProfile-6.0[]. However, `mpTelemetry-1.1` is also compatible with the following earlier umbrella features: +Different versions of the MicroProfile Telemetry feature are compatible with different MicroProfile versions, Jakarta and Java Enterprise Editions, and the Open Liberty umbrella features that support them. Both feature:mpTelemetry-1.0[] and feature:mpTelemetry-1.1[] are compatible with feature:jakartaee-10.0[] and feature:microProfile-6.0[]. However, `mpTelemetry-1.1` is also compatible with the following earlier umbrella features: + * feature:javaee-7.0[] and feature:microProfile-1.4[] * feature:jakartaee-8.0[] and feature:microProfile-4.1[] @@ -37,10 +37,8 @@ Different versions of the MicroProfile Telemetry feature are compatible with dif + You can configure how MicroProfile Telemetry collects and exports traces by specifying configuration properties in any of the xref:external-configuration.adoc#default[config sources that are available to MicroProfile Config]. If you choose to set these configuration properties by using environment variables, make the key name uppercase and convert any punctuation to underscores. For example, the `otel.sdk.disabled=false` property is equivalent to the `OTEL_SDK_DISABLED=false` environment variable. -.. Enable the generation of traces by setting the `otel.sdk.disabled` property to `false`. +.. OpenTelemetry is disabled by default. To enable the generation of traces, set the `otel.sdk.disabled=false` property. + -OpenTelemetry is disabled by default. To enable the generation of traces, set the `otel.sdk.disabled=false` property. - .. Configure a trace storage system by specifying an exporter definition that includes the exporter type and the endpoint to connect to. + For example, to use a Jaeger server, you might add configuration similar to the following example to your `bootstrap.properties` file: @@ -87,7 +85,7 @@ After you enable MicroProfile Telemetry and configure a trace server, you can in [#auto] === Automatic instrumentation -With automatic instrumentation, you can observe traces without modifying the source code in your applications. All you need to do is configure your server, as described in <<#ol-config,Configuring Open Liberty to use MicroProfile Telemetry>>. However, automatic instrumentation is available only for JAX-RS and Jakarta RESTful web service applications. +With automatic instrumentation, you can observe traces without modifying the source code in your applications. All you need to do is configure runtime as described in <<#ol-config,Configuring Open Liberty to use MicroProfile Telemetry>>. However, automatic instrumentation is available only for JAX-RS and Jakarta RESTful web service applications. In Open Liberty version 23.0.0.11 and later, spans are automatically generated for incoming HTTP requests, including static files, servlets, and JSPs. @@ -120,7 +118,7 @@ Automatic instrumentation is available only for JAX-RS and Jakarta RESTful web s . Enable MicroPRofile Telemetry, as described in <<#ol-config,Configuring Open Liberty to use MicroProfile Telemetry>>. -. Enable third-party APIs for your application by adding the following code in your `server.xml` file: +. xref:class-loader-library-configuration.adoc#3rd-party[Enable third-party APIs] for your application by adding the following code in your `server.xml` file: + [source,xml] ---- @@ -247,9 +245,9 @@ The following information can help you determine the cause of common problems an Previous spans are incorrectly shown as current or parent spans:: If the `Scope` instance is not closed correctly, the context and baggage values of previous spans might remain when the next operation executes. Alternatively, the current span might remain and be picked up as the parent of the next operation that executes. - ++ Always close the `Scope` instance when you exit an operation. This configuration stops the span from being current and makes the previous span current again. Use a `try-with-resources` block, which automatically closes the `Scope` instance at the end of the block, as shown in the following example: - ++ [source, java] ---- Span span = tracer.spanBuilder("PerformingOperation").startSpan(); From ea2fdc65958f4ef56ee15fb63590ee6ab0c9b031 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Thu, 30 Nov 2023 10:30:09 -0500 Subject: [PATCH 37/58] edits #6776 --- modules/ROOT/pages/microprofile-telemetry.adoc | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/microprofile-telemetry.adoc b/modules/ROOT/pages/microprofile-telemetry.adoc index bd0cebd30a..8f003f0cd0 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -20,18 +20,24 @@ link:https://projects.eclipse.org/projects/technology.microprofile/releases/micr MicroProfile Telemetry replaces MicroProfile OpenTracing. For information about migrating your applications from MicroProfile OpenTracing to MicroProfile Telemetry, see xref:reference:diff/mp-50-60-diff.adoc#telemetry[Differences between MicroProfile Telemetry 1.0 and MicroProfile OpenTracing 3.0]. +- <<#ol-config, Configuring Open Liberty to use MicroProfile Telemetry>> +- <<#code, Code instrumentation>> +- <<#trouble, Troubleshooting MicroProfile Telemetry>> + [#ol-config] == Configuring Open Liberty to use MicroProfile Telemetry To enable MicroProfile Telemetry in your Open Liberty runtime, you must add the MicroProfile Telemetry feature to your `server.xml` file and specify MicroProfile Config properties to configure how MicroProfile Telemetry collects and exports traces. . Add a version of the feature:mpTelemetry[display=MicroProfile Telemetry] feature to your `server.xml` file. +//// + Different versions of the MicroProfile Telemetry feature are compatible with different MicroProfile versions, Jakarta and Java Enterprise Editions, and the Open Liberty umbrella features that support them. Both feature:mpTelemetry-1.0[] and feature:mpTelemetry-1.1[] are compatible with feature:jakartaee-10.0[] and feature:microProfile-6.0[]. However, `mpTelemetry-1.1` is also compatible with the following earlier umbrella features: + * feature:javaee-7.0[] and feature:microProfile-1.4[] * feature:jakartaee-8.0[] and feature:microProfile-4.1[] * feature:jakartaee-9.1[] and feature:microProfile-5.0[] +//// . Enable tracing and configure a trace storage system by specifying MicroProfile Config properties. + @@ -74,6 +80,7 @@ For more information about the available properties, see xref:microprofile-confi + For more information, see the following section. +[#code] == Code instrumentation After you enable MicroProfile Telemetry and configure a trace server, you can instrument tracing in your application code by using one of the following methods: @@ -118,7 +125,7 @@ Automatic instrumentation is available only for JAX-RS and Jakarta RESTful web s . Enable MicroPRofile Telemetry, as described in <<#ol-config,Configuring Open Liberty to use MicroProfile Telemetry>>. -. xref:class-loader-library-configuration.adoc#3rd-party[Enable third-party APIs] for your application by adding the following code in your `server.xml` file: +. xref:class-loader-library-config.adoc#3rd-party[Enable third-party APIs] for your application by adding the following code in your `server.xml` file: + [source,xml] ---- @@ -239,6 +246,7 @@ The OpenTelemetry Java agent is a tool that is provided by the OpenTelemetry pro * The agent is not compatible with https://www.ibm.com/docs/en/was-liberty/base?topic=security-java-2[Java 2 security]. * Open Liberty uses many open source libraries internally. Some of these libraries might be automatically instrumented by the agent. +[#trouble] == Troubleshooting MicroProfile Telemetry The following information can help you determine the cause of common problems and error messages. From a90e23c580f757b6dc9a173d54fb1811281eb7ab Mon Sep 17 00:00:00 2001 From: David Mueller Date: Thu, 30 Nov 2023 10:42:00 -0500 Subject: [PATCH 38/58] test From 4fff333654ed7122d5b96bd18804e45f64246a32 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Thu, 30 Nov 2023 11:37:02 -0500 Subject: [PATCH 39/58] edits #6776 --- .../ROOT/pages/microprofile-telemetry.adoc | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/modules/ROOT/pages/microprofile-telemetry.adoc b/modules/ROOT/pages/microprofile-telemetry.adoc index 8f003f0cd0..8764fb1ac8 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -20,6 +20,8 @@ link:https://projects.eclipse.org/projects/technology.microprofile/releases/micr MicroProfile Telemetry replaces MicroProfile OpenTracing. For information about migrating your applications from MicroProfile OpenTracing to MicroProfile Telemetry, see xref:reference:diff/mp-50-60-diff.adoc#telemetry[Differences between MicroProfile Telemetry 1.0 and MicroProfile OpenTracing 3.0]. +The following sections explain how to prepare your Open Liberty runtime and application code to use MicroProfile Telemetry. + - <<#ol-config, Configuring Open Liberty to use MicroProfile Telemetry>> - <<#code, Code instrumentation>> - <<#trouble, Troubleshooting MicroProfile Telemetry>> @@ -30,14 +32,6 @@ MicroProfile Telemetry replaces MicroProfile OpenTracing. For information about To enable MicroProfile Telemetry in your Open Liberty runtime, you must add the MicroProfile Telemetry feature to your `server.xml` file and specify MicroProfile Config properties to configure how MicroProfile Telemetry collects and exports traces. . Add a version of the feature:mpTelemetry[display=MicroProfile Telemetry] feature to your `server.xml` file. -//// -+ -Different versions of the MicroProfile Telemetry feature are compatible with different MicroProfile versions, Jakarta and Java Enterprise Editions, and the Open Liberty umbrella features that support them. Both feature:mpTelemetry-1.0[] and feature:mpTelemetry-1.1[] are compatible with feature:jakartaee-10.0[] and feature:microProfile-6.0[]. However, `mpTelemetry-1.1` is also compatible with the following earlier umbrella features: -+ -* feature:javaee-7.0[] and feature:microProfile-1.4[] -* feature:jakartaee-8.0[] and feature:microProfile-4.1[] -* feature:jakartaee-9.1[] and feature:microProfile-5.0[] -//// . Enable tracing and configure a trace storage system by specifying MicroProfile Config properties. + @@ -273,3 +267,12 @@ If you enable the `mpTelemetry-1.1` or `mpTelemetry-1.0` feature, you must also You receive the CWMOT5003W message that the application attempted to acquire MicroProfile Telemetry after shut down:: Review the application to see why it attempted to use MicroProfile Telemetry after it shut down. Actions that might trigger MicroProfile Telemetry include calling a method that is annotated with `@WithSpan`` or making a request with a JAX-RS Client or MP Rest Client. + +//// ++ +Different versions of the MicroProfile Telemetry feature are compatible with different MicroProfile versions, Jakarta and Java Enterprise Editions, and the Open Liberty umbrella features that support them. Both feature:mpTelemetry-1.0[] and feature:mpTelemetry-1.1[] are compatible with feature:jakartaee-10.0[] and feature:microProfile-6.0[]. However, `mpTelemetry-1.1` is also compatible with the following earlier umbrella features: ++ +* feature:javaee-7.0[] and feature:microProfile-1.4[] +* feature:jakartaee-8.0[] and feature:microProfile-4.1[] +* feature:jakartaee-9.1[] and feature:microProfile-5.0[] +//// From df99f0581343331b9c54df7b107bd8250973bec3 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Fri, 1 Dec 2023 16:20:54 +0530 Subject: [PATCH 40/58] 7062-Added-mp-50-51-diff-to-doc 7062-Added-mp-50-51-diff-to-doc #7062 --- .../reference/pages/diff/mp-60-61-diff.adoc | 73 ++++++++++++++++++- 1 file changed, 72 insertions(+), 1 deletion(-) diff --git a/modules/reference/pages/diff/mp-60-61-diff.adoc b/modules/reference/pages/diff/mp-60-61-diff.adoc index 034ee11295..2b2175e8ac 100644 --- a/modules/reference/pages/diff/mp-60-61-diff.adoc +++ b/modules/reference/pages/diff/mp-60-61-diff.adoc @@ -30,8 +30,79 @@ If you are updating your application from using MicroProfile 6.0 features to usi The MicroProfile Metrics 5.1 release introduces many changes to the specification and programming model that impact users who are migrating from MicroProfile Metrics 5.0. +The MicroProfile Metrics 5.1 release introduces a swathe of new MicroProfile Config properties that are used to customize the metric data that is tracked and output by the histogram and timer metrics. MicroProfile Metrics 5.1 introduces new properties that make it possible for you to specify a custom range of percentiles and a custom set of histogram buckets specifically for Histogram and Timer metrics. More configuration properties are now available for establishing a default range of histogram buckets, including options to specify the starting and ending points of the bucket set. + +.New Properties in MicroProfile Metrics 5.1 +|=== + +| Name| Description + +|`mp.metrics.distribution.percentiles` +|Customize the percentile or quantile output for histogram and timers + +|`mp.metrics.distribution.histogram.buckets` +| Customize the set of histogram-buckets to be output by histogram metric + +|`mp.metrics.distribution.timer.buckets` +| Customize the set of histogram-buckets to be output by timer metric + +|`mp.metrics.distribution.percentiles-histogram.enabled` +| Enable a pre-set list of histogram-buckets for the histogram or timer metric + +|`mp.metrics.distribution.histogram.min-value` +| Upper bound bucket for pre-set list of histogram-buckets for histogram metric + +|`mp.metrics.distribution.histogram.max-value` +| Lower bound bucket for pre-set list of histogram-buckets for histogram metric + +|`mp.metrics.distribution.timer.min-value` +| Upper bound bucket for pre-set list of timer-buckets for histogram metric + +|`mp.metrics.distribution.timer.max-value` +| Lower bound bucket for pre-set list of timer-buckets for histogram metric + +|=== + +For more information on the properties and how to use them, see the xref:microprofile-config-properties.adoc#metrics[MicroProfile Config properties: MicroProfile Metrics]. + +The following example of MicroProfile Config definitions sets up the `alpha.timer` metric to output the 50th, 70th, 75th, and 80th percentile. It also configures histogram buckets to track and report the count of durations within specific intervals: from 0 to 100 milliseconds, 0 to 200 milliseconds, and 0 to 1 second. These intervals function as cumulative ranges, which is how the histogram buckets operate. + +[source,xml] +---- +mp.metrics.distribution.percentiles=alpha.timer=0.5,0.7,0.75,0.8 +mp.metrics.distribution.timer.buckets=alpha.timer=100ms,200ms,1s +---- + +The corresponding Prometheus output for the `alpha.timer` metric at the `/metrics` REST endpoint is as follows. + +[source,xml] +---- +# HELP alpha_timer_seconds_max +# TYPE alpha_timer_seconds_max gauge +alpha_timer_seconds_max{scope="application",} 5.633 +# HELP alpha_timer_seconds +# TYPE alpha_timer_seconds histogram <1> +alpha_timer_seconds{scope="application",quantile="0.5",} 0.67108864 +alpha_timer_seconds{scope="application",quantile="0.7",} 5.603590144 +alpha_timer_seconds{scope="application",quantile="0.75",} 5.603590144 +alpha_timer_seconds{scope="application",quantile="0.8",} 5.603590144 +alpha_timer_seconds_bucket{scope="application",le="0.1",} 0.0 <2> +alpha_timer_seconds_bucket{scope="application",le="0.2",} 0.0 <2> +alpha_timer_seconds_bucket{scope="application",le="1.0",} 1.0 <2> +alpha_timer_seconds_bucket{scope="application",le="+Inf",} 2.0 <2><3> +alpha_timer_seconds_count{scope="application",} 2.0 +alpha_timer_seconds_sum{scope="application",} 6.333 +---- + +<1> The Prometheus metric type is `histogram`, where both quantiles or percentiles, and buckets, are represented under this type. +<2> The `le` tag represents _less than_ and is for the defined buckets that are converted to seconds. +<3> Prometheus requires that a +Inf bucket that count all hits. + +Also, the @RegistryScope annotation, suitable for use during metric registry injection, is now a CDI qualifier. + [#telemetry] == Differences between MicroProfile Telemetry 1.0 and 1.1 -MicroProfile Telemetry 1.1 provides developers with the latest Open Telemetry technology; the feature now consumes OpenTelemetry-1.29.0, updated from 1.19.0. Consequently, a lot of the dependencies are now stable. The feature is compatible with Java EE 7 with MicroProfile 1.4, Java EE 8 with MicroProfile 4.1, Jakarta EE 9 with MicroProfile 5.0 and Jakarta EE 10 with MicroProfile 6.1. +MicroProfile Telemetry 1.1 equips developers with the most recent Open Telemetry technology; this feature now uses OpenTelemetry-1.29.0, upgraded from 1.19.0. Therefore, a significant number of the dependencies are now stable. +This feature provides seamless integration with several environments. It is compatible with Java EE 7 and MicroProfile 1.4, and also Java EE 8 and MicroProfile 4.1. It also supports Jakarta EE 9 with MicroProfile 5.0, and Jakarta EE 10 paired with MicroProfile 6.1. From 330e2f9ff8c84223d418f0b262a025ea07f53f40 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Mon, 4 Dec 2023 14:46:12 +0530 Subject: [PATCH 41/58] 7062-Added-mp-50-51-diff-to-doc-2 7062-Added-mp-50-51-diff-to-doc-2 #7062 --- modules/reference/pages/diff/mp-60-61-diff.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/reference/pages/diff/mp-60-61-diff.adoc b/modules/reference/pages/diff/mp-60-61-diff.adoc index 2b2175e8ac..2659b5c834 100644 --- a/modules/reference/pages/diff/mp-60-61-diff.adoc +++ b/modules/reference/pages/diff/mp-60-61-diff.adoc @@ -16,9 +16,9 @@ :page-type: general = Differences between MicroProfile 6.1 and 6.0 -MicroProfile 6.1 is a minor release. It includes Jakarta EE 10 Core Profile and replaces MicroProfile OpenTracing with MicroProfile Telemetry. +MicroProfile 6.1 is a minor release. It includes the minor changes from Config 3.1, Metrics 5.1, Telemetry 1.1. -Therefore, MicroProfile OpenTracing moves out of the umbrella release and becomes a stand-alone specification. For more information about Jakarta EE 10 Core Profile, see the link:https://jakarta.ee/specifications/coreprofile/10/[Core Profile specification]. +The changes for Config 3.1 are minor specification refinements and TCK improvements. The update makes it clear that the _profile-specific_ feature has no functional impact and influences only the values that are chosen from each configuration source. If you are updating your application from using MicroProfile 6.0 features to using link:https://github.com/eclipse/microprofile/releases/tag/6.1[MicroProfile 6.1] features, changes in API behavior might require you to update your application code. The following sections provide details about migrating your applications from MicroProfile 6.0 to 6.1: From c9a7498d534484dee7defc700eca3cabc9ce4382 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Mon, 4 Dec 2023 11:36:46 -0500 Subject: [PATCH 42/58] remove stray formatting #6776 --- modules/ROOT/pages/microprofile-telemetry.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/microprofile-telemetry.adoc b/modules/ROOT/pages/microprofile-telemetry.adoc index 8764fb1ac8..c2cf1a6562 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -262,11 +262,11 @@ try (Scope scope = span.makeCurrent()) { You receive the `CWMOT5100I` message that tracing is disabled:: -If you enable the `mpTelemetry-1.1` or `mpTelemetry-1.0` feature, you must also set the `otel.sdk.disabled=false` property in any of the configuration sources that are accessible through MicroProfile Config to enable tracing. +If you enable the `mpTelemetry-1.1` or `mpTelemetry-1.0` feature, you must also set the `otel.sdk.disabled=false` property in any of the configuration sources that are accessible through MicroProfile Config to enable tracing. You receive the CWMOT5003W message that the application attempted to acquire MicroProfile Telemetry after shut down:: -Review the application to see why it attempted to use MicroProfile Telemetry after it shut down. Actions that might trigger MicroProfile Telemetry include calling a method that is annotated with `@WithSpan`` or making a request with a JAX-RS Client or MP Rest Client. +Review the application to see why it attempted to use MicroProfile Telemetry after it shut down. Actions that might trigger MicroProfile Telemetry include calling a method that is annotated with `@WithSpan` or making a request with a JAX-RS Client or MP Rest Client. //// + From 30e9f630478c76d3846a64aff29023e113cfd0e9 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Tue, 5 Dec 2023 09:26:58 -0500 Subject: [PATCH 43/58] edits per peer review #6776 --- modules/ROOT/pages/microprofile-telemetry.adoc | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/modules/ROOT/pages/microprofile-telemetry.adoc b/modules/ROOT/pages/microprofile-telemetry.adoc index c2cf1a6562..e176427de3 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -14,11 +14,11 @@ In microservice applications, sources of latency or inaccuracy can be difficult to determine because relationships and dependencies among the constituent services are not always obvious. MicroProfile Telemetry helps you collect data on the paths that application requests take through services. -One way to increase observability of an application is by emitting traces. Traces represent requests and consist of multiple spans. A span represents a single operation in a request and contains a name, time-related data, log messages, and metadata to gather data about what occurs during a transaction. +One way to increase observability of an application is by emitting traces. Traces represent requests and consist of multiple spans. A span represents a single operation in a request. It includes a name, time-related data, log messages, and metadata to collect data about what happens during a transaction. -link:https://projects.eclipse.org/projects/technology.microprofile/releases/microprofile-telemetry-1.0/plan%E2%80%A8%E2%80%A822.0.0.10-bet[MicroProfile Telemetry] is based on the https://opentelemetry.io/[OpenTelemetry project], which is a collection of open source vendor-independent tools, APIs, and SDKs for creating and managing trace data. You can enable MicroProfile Telemetry for Open Liberty by adding the feature:mpTelemetry[display=MicroProfile Telemetry] feature to your `server.xml` file and configuring the feature to connect to your distributed trace service. +link:https://projects.eclipse.org/projects/technology.microprofile/releases/microprofile-telemetry-1.0/plan%E2%80%A8%E2%80%A822.0.0.10-bet[MicroProfile Telemetry] is based on the https://opentelemetry.io/[OpenTelemetry project], a collection of open source vendor-independent tools, APIs, and SDKs for creating and managing trace data. You can enable MicroProfile Telemetry for Open Liberty by adding the feature:mpTelemetry[display=MicroProfile Telemetry] feature to your `server.xml` file and configuring the feature to connect to your distributed trace service. -MicroProfile Telemetry replaces MicroProfile OpenTracing. For information about migrating your applications from MicroProfile OpenTracing to MicroProfile Telemetry, see xref:reference:diff/mp-50-60-diff.adoc#telemetry[Differences between MicroProfile Telemetry 1.0 and MicroProfile OpenTracing 3.0]. +MicroProfile Telemetry replaces MicroProfile OpenTracing. For more information about migrating your applications from MicroProfile OpenTracing to MicroProfile Telemetry, see xref:reference:diff/mp-50-60-diff.adoc#telemetry[Differences between MicroProfile Telemetry 1.0 and MicroProfile OpenTracing 3.0]. The following sections explain how to prepare your Open Liberty runtime and application code to use MicroProfile Telemetry. @@ -79,9 +79,9 @@ For more information, see the following section. After you enable MicroProfile Telemetry and configure a trace server, you can instrument tracing in your application code by using one of the following methods: -* <<#auto, automatic instrumentation>>, which automatically traces your JAX-RS or RESTful web services. -* <<#manual, manual instrumentation>>, which allows you to start and end telemetry spans manually for applications that are not JAX-RS or RESTful web services. -* <<#agent, agent instrumentation>>, which automatically adds telemetry to popular open source libraries. However, agent instrumentation also imposes certain <<#limit, limitations>>. +* <<#auto, Automatic instrumentation>>, which automatically traces your JAX-RS or RESTful web services. +* <<#manual, Manual instrumentation>>, which allows you to start and end telemetry spans manually for applications that are not JAX-RS or RESTful web services. +* <<#agent, Agent instrumentation>>, which automatically adds telemetry to popular open source libraries. However, agent instrumentation also imposes certain <<#limit, limitations>>. [#auto] === Automatic instrumentation @@ -117,7 +117,7 @@ otel.exporter.zipkin.endpoint=http://localhost:9411/api/v2/spans Automatic instrumentation is available only for JAX-RS and Jakarta RESTful web service applications. To create spans for other operations, such as database calls, you can add manual instrumentation to the source code for those operations by using the https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/1.19.0/io/opentelemetry/api/trace/package-summary.html[OpenTelemetry API]. However, before you manually instrument your code, you must complete the following prerequisites. -. Enable MicroPRofile Telemetry, as described in <<#ol-config,Configuring Open Liberty to use MicroProfile Telemetry>>. +. Enable MicroProfile Telemetry, as described in <<#ol-config,Configuring Open Liberty to use MicroProfile Telemetry>>. . xref:class-loader-library-config.adoc#3rd-party[Enable third-party APIs] for your application by adding the following code in your `server.xml` file: + @@ -140,7 +140,7 @@ Automatic instrumentation is available only for JAX-RS and Jakarta RESTful web s io.opentelemetry.instrumentation - opentelemetry-instrumentation-annotions + opentelemetry-instrumentation-annotations 1.19.0-alpha provided @@ -209,7 +209,7 @@ The following important considerations apply to manual instrumentation. - You must call the `.end()` method on any span you create, otherwise the span is not recorded. - The current span is used as the parent for any new spans that are created. Therefore, when you create a span, you usually also want to make it current. However, you must close the `Scope` instance that is returned by the `Span.makeCurrent()` method. You can close a `Scope` instance by specifying a try-with-resources block, as shown in the previous example for creating a subspan. - Because Liberty supports per-application configuration, it does not support `GlobalOpenTelemetry`. Using that class does not produce any telemetry data. -- If you set any properties by using environment variables, including the in the `server.env` file, the keys must be in uppercase and all punctuation must be replaced by an underscore. Values must be written normally. +- If you set any properties by using environment variables, including those in the `server.env` file, the keys must be in uppercase and all punctuation must be replaced by an underscore. Values must be written normally. For more information, see the https://opentelemetry.io/docs/instrumentation/java/manual[OpenTelemetry manual instrumentation documentation]. However, remember when you use the MicroProfile Telemetry feature in Open Liberty, you must obtain the `OpenTelemetry` and `Tracer` objects by injecting them, not by creating your own. Furthermore, be aware that this documentation includes information for the OpenTelemetry Metrics and Logging APIs, which are not supported by MicroProfile Telemetry. From 8926a8183765474c0feef91f897a16a1d2000feb Mon Sep 17 00:00:00 2001 From: David Mueller Date: Tue, 5 Dec 2023 10:58:23 -0500 Subject: [PATCH 44/58] edits per review #1127 --- .../pages/slow-hung-request-detection.adoc | 30 ++++++++++--------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/modules/ROOT/pages/slow-hung-request-detection.adoc b/modules/ROOT/pages/slow-hung-request-detection.adoc index eeb96f6a31..4044a137bb 100644 --- a/modules/ROOT/pages/slow-hung-request-detection.adoc +++ b/modules/ROOT/pages/slow-hung-request-detection.adoc @@ -6,22 +6,22 @@ :seo-description: The request timing feature automatically detects slow and hung requests and logs the information when the request is completed. = Slow and hung request detection -When an application takes longer than expected to complete a request, the request can be logged as slow or hung. +When an application takes longer than expected to complete a request, the request might be logged as slow or hung. The Request Timing feature automatically detects slow and hung requests and provides detailed information to help you find the root cause of the delay. -The feature:requestTiming[display=Request Timing] feature identifies incoming requests that run longer than a slow request threshold. +Enable the Request Timing feature to identify incoming requests that run longer than a slow request threshold. The Request Timing feature documents slow and hung requests as they occur, so you don't need to re-create the problem to collect more data. In addition to the global settings for slow and hung request thresholds, you can set thresholds for specific servlets or JDBC requests. -For more information, see the feature:requestTiming[display=Request Timing] feature. +For more information and configuration examples, see the feature:requestTiming[display=Request Timing] feature. == Slow request detection -A request can be slow because its code path length is long. -Slow requests can also be caused if a resource, which the request depends on, is busy. -Users need to know what actions occurred during the processing of that request, and the processing stage of the request. +A request might be slow because its code path is long. +Slow requests can occur when a resource that the request depends on is busy. +To diagnose a slow request, you need to know what actions occurred during the processing of that request and the processing stage of the request. -When a request runs for longer than the slow request threshold, the Request Timing feature generates a warning message in the messages log file. -The message includes details about the request and events that made up the request. +When a request runs longer than the slow request threshold, the Request Timing feature generates a warning message in the messages log file. +The message includes details about the request and the events that made up the request. The default threshold value is 10 seconds. The following example shows the format of a log message: @@ -33,20 +33,22 @@ TRAS0112W: Request <(Request ID)> has been running on thread for at l ---- -The `Request ID` can be used to search for log and trace messages that correspond to the request. If you use binary logging, you can search for log and trace entries with the same `requestID` extension by using the binary log command. The `STACK TRACE` indicates that the method is running. After the `STACK TRACE`, the `DURATION AND OPERATIONS Table` provides the format of the request that includes the duration and operation. The `Duration` column indicates the time that is taken by the corresponding operation of the request. The plus sign (+) that is shown in the `Duration` column indicates events within the request that are still running. The `Duration` column also includes duration without the plus sign to indicate that the corresponding operation completed in the specified duration. The `Operation` column shows the `EVENT TYPE` and optional `CONTEXT INFO` for the specified operation. +- You can use the `Request ID` value to search for log and trace messages that correspond to the request. If you use binary logging, you can search for log and trace entries with the same `requestID` extension by using the `binaryLog` command. +- The `STACK TRACE` indicates that the method is running. +- After the `STACK TRACE`, the `DURATION AND OPERATIONS Table` provides the format of the request that includes the duration and operation. The `Duration` column indicates the time that is taken by the corresponding operation of the request. The plus sign (+) that is shown in the `Duration` column indicates events within the request that are still running. The `Duration` column also includes duration without the plus sign to indicate that the corresponding operation finished in the specified duration. The `Operation` column shows the `EVENT TYPE` and optional `CONTEXT INFO` for the specified operation. -The message helps you analyze the reason behind the slow request, though it is difficult to determine whether the request is hung at that point or is still running slowly. -To address this issue, three messages are displayed for any slow request at the interval specified by the xref:reference:config/requestTiming.adoc[slowRequestThreshold] attribute. +The message helps you analyze the reason behind the slow request, though at this point you might not be able to determine whether the request is hung or is still running slowly. +To address this issue, three messages are displayed for any slow request at the interval that is specified by the xref:reference:config/requestTiming.adoc[slowRequestThreshold] attribute. The stack trace data gives the information about the method that is running, while the request data gives details about the request, like the request ID and duration. -The three different stack trace and request data help you better understand where the request is going wrong by looking into what the thread is running currently. +The three different stack trace and request messages help you better understand where the request is going wrong by looking into what the thread is running currently. No further warnings are logged about the request unless the duration of the request crosses the hung request detection threshold. == Hung request detection -Requests that take longer than the hung request threshold are typically blocked by lack of access to a shared resource, for example, a section of code that allows only serial access and transfers information sequentially. +Requests that take longer than the hung request threshold are typically blocked by lack of access to a shared resource. For example, the problem might result from a section of code that allows only serial access and transfers information sequentially. Such longer requests are likely to be hung, and can be blocked for a long time or even indefinitely. One particular form of hung request, called a deadlock, occurs when two threads are blocked waiting on each other to return shared resources. -For a hung request, users need to know where all the threads are at in their processing, and which locks the threads are waiting on. +For a hung request, you need to know where all the threads are at in their processing, and which locks the threads are waiting on. If the request exceeds the hung request threshold, the Request Timing feature generates a warning message in the messages log file with the request details and events that make up the request. A series of three Java cores is recorded with a 1-minute delay among the cores. From 7b344ea07da6a668aeb371819c6a79322e6193b9 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Tue, 5 Dec 2023 11:43:27 -0500 Subject: [PATCH 45/58] cs edits #1274 --- modules/ROOT/pages/jaxrs-integration-cdi.adoc | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/jaxrs-integration-cdi.adoc b/modules/ROOT/pages/jaxrs-integration-cdi.adoc index 4f957aeaea..42dd86cbd6 100644 --- a/modules/ROOT/pages/jaxrs-integration-cdi.adoc +++ b/modules/ROOT/pages/jaxrs-integration-cdi.adoc @@ -15,7 +15,9 @@ In Open Liberty, Jakarta RESTful Web Services (formerly known as JAX-RS) can integrate with the Contexts and Dependency Injection (CDI) specification. By integrating RESTful Web Services with CDI, you can annotate CDI beans or managed beans as REST endpoints and use CDI injection for web services. -In Open Liberty, RESTful Web Services support is enabled by the feature:restfulWS[display=Jakarta RESTful Services feature]. This feature helps applications build and consume RESTful services. It also supports CDI-style beans as root resource classes, providers, and application subclasses. Providers and application subclasses must be singleton classes or use the application scope. The CDI specification helps integrate various kinds of Jakarta EE components in a loosely coupled but type-safe way. This specification provides a common mechanism to inject components, such as enterprise beans or managed beans, into other components, such as Jakarta Server Pages (JSP) files or other enterprise beans. CDI support in Open Liberty is enabled by the xref:reference:feature/cdi-2.0.adoc[Contexts and Dependency Injection feature]. +In Open Liberty, RESTful Web Services support is enabled by the feature:restfulWS[display=Jakarta RESTful Services feature]. This feature helps applications build and consume RESTful services. It also supports CDI-style beans as root resource classes, providers, and application subclasses. Providers and application subclasses must either be singleton classes or use the application scope. + +The CDI specification helps integrate various kinds of Jakarta EE components in a loosely coupled but type-safe way. This specification provides a common mechanism to inject components, such as enterprise beans or managed beans, into other components, such as Jakarta Server Pages (JSP) files or other enterprise beans. CDI support in Open Liberty is enabled by the xref:reference:feature/cdi-2.0.adoc[Contexts and Dependency Injection feature]. One way to implement CDI with RESTful Web Services resources is to use the `@ApplicationScoped` and `@Inject` annotations with application-scoped beans in your application code, as shown in the following example: @@ -34,6 +36,7 @@ public class ApplicationScopedResource { } ---- + The `@ApplicationScoped` annotation specifies that only one instance of this bean is used for the lifecycle of the application. Normally, RESTful Web Services resources are per-request, which means the RESTful Web Services engine creates a new instance of the class for each HTTP request. Per-request classes are beneficial in some cases but they are generally less efficient than per-application resources, in which the same instance is used for every HTTP request. The `@Inject` annotation injects an instance of the `SimpleBean` class into the instance of the `ApplicationScopedResource` bean. For more information about CDI, see xref:cdi-beans.adoc[Context and Dependency Injection beans]. @@ -41,11 +44,11 @@ The `@Inject` annotation injects an instance of the `SimpleBean` class into the == RESTful Web Services and CDI scopes -The scope of a bean defines the lifecycle of its instances. A bean lifecycle can be singleton, so that the same instance is used for every HTTP request, or per-request, so that a new instance is created for each HTTP request. Bean lifecycles can also be scoped to a particular session, or by conversation, which is defined by explicit developer-controlled boundaries for JSF applications. +The scope of a bean defines the lifecycle of its instances. A bean lifecycle can be singleton, so that the same instance is used for every HTTP request, or per-request, so that a new instance is created for each HTTP request. Bean lifecycles can also be scoped to a particular session, or by conversation, which is defined by explicit developer-controlled boundaries for Jakarta Server Faces (JSF) applications. RESTful Web Services and CDI specify slightly different scopes. If the lifecycle scopes that are specified by RESTful Web Services and CDI are in conflict, the resulting lifecycle depends on the component type of the RESTful Web Services resource. RESTful Web Services provider component types are always singletons, regardless of the CDI annotation. RESTful Web Services resource component types adopt whatever lifecycle is specified by the CDI annotation. -For example, the `ApplicationScoped` CDI scope annotation defines a singleton lifecycle, because only one instance of a class with this annotation is used for the lifecycle of the application. If you configure a RESTful Web Services resource scope as per-request, but then specify the `@ApplicationScoped` CDI scope on it, the resource lifecycle is singleton. Similarly, if you configure a RESTful Web Services resource scope as singleton, but then specify the `@RequestScoped` CDI scope on it, the resource lifecycle is per-request, as specified by the CDI annotation. +For example, the `ApplicationScoped` CDI scope annotation defines a singleton lifecycle, because only one instance of a class with this annotation is used for the lifecycle of the application. If you configure a RESTful Web Services resource scope as per-request, but then specify the `@ApplicationScoped` CDI scope on it, the resource lifecycle is singleton. Similarly, if you configure a RESTful Web Services resource scope as a singleton class, but then specify the `@RequestScoped` CDI scope on it, the resource lifecycle is per-request, as specified by the CDI annotation. However, if the RESTful Web Services component is a provider, the lifecycle is singleton, regardless of the CDI annotation. For more information, see xref:cdi-beans.adoc#_cdi_scopes[CDI scopes]. @@ -56,8 +59,8 @@ CDI with RESTful Web Services in Open Liberty is subject to the following restri - If the Contexts and Dependency Injection feature is not enabled in your `server.xml` file, the runtime has no CDI support. Therefore, if you specify a CDI annotation in a Java class, the RESTful Web Services engine uses the Java class as a plain old Java object (POJO) class. - If a resource class with the `@Path` annotation implements a RESTful Web Services provider interface or declares with the `@Provider` annotation, then this class works as both a resource and a provider. In this case, the RESTful Web Services engine uses only one instance of this class that is shared by the resource class and the provider. The lifecycle of the instance is singleton. -- If a RESTful resource is also a CDI-managed bean and its scope is `javax.enterprise.context.Dependent`, the `PreDestroy` method cannot be called because of the CDI restriction. -- If a class is registered in both the `getClasses` and `getSingletons` methods of the application class, the RESTful Web Services engine uses the instance from the `getSingletons` method and ignores the `getClasses` instance. However, objects that are returned in the `getSingletons` method are not managed by CDI. In general, avoid use of the `getSingletons` method as it is targeted for deprecation and eventual removal from future versions of the RESTful Web Services specification. +- If a RESTful resource is also a CDI-managed bean and its scope is `jakarta.enterprise.context.Dependent`, the `PreDestroy` method cannot be called because of the CDI restriction. +- If a class is registered in both the `getClasses` and `getSingletons` methods of the application class, the RESTful Web Services engine uses the instance from the `getSingletons` method and ignores the `getClasses` instance. However, objects that are returned in the `getSingletons` method are not managed by CDI. In general, avoid use of the `getSingletons` method. == See also - Guide: link:/guides//cdi-intro.html[Injecting dependencies into microservices] From 95a587b36350e96a0107535b43813240ea97e18a Mon Sep 17 00:00:00 2001 From: David Mueller Date: Tue, 5 Dec 2023 11:49:42 -0500 Subject: [PATCH 46/58] minor edits #1290 --- modules/reference/pages/feature/sessionCache/examples.adoc | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/modules/reference/pages/feature/sessionCache/examples.adoc b/modules/reference/pages/feature/sessionCache/examples.adoc index 830f5f36e7..f41d319087 100644 --- a/modules/reference/pages/feature/sessionCache/examples.adoc +++ b/modules/reference/pages/feature/sessionCache/examples.adoc @@ -7,7 +7,7 @@ The `sessionCache` feature does not include a JCache implementation, so you must You must define a location for the implementation files with the `library` element and reference that library by specifying the `jCacheLibraryRef` attribute for the `cachingProvider` element. In the following example, Hazelcast is specified as the JCache implementation. -The `library` element specifies that Hazelcast must be used as the JCache provider, which is located in the `hazelcast.jar` library. +The `library` element specifies that Hazelcast which is located in the `hazelcast.jar` library, must be used as the JCache provider: [source, xml] ---- @@ -24,12 +24,10 @@ The `library` element specifies that Hazelcast must be used as the JCache provi === Customizing the JCache implementation -You can provide a configuration file to customize how your JCache implementation manages HTTP session caching. +You can provide an optional configuration file to customize how your JCache implementation manages HTTP session caching. To specify the file location, use the `uri` attribute for the `cacheManager` element. In the following example, the `uri` attribute specifies the location of a Hazelcast configuration file: -The following example shows the configuration of session persistence with Hazelcast as the JCache provider: - [source,xml] ---- @@ -43,7 +41,6 @@ The following example shows the configuration of session persistence with Hazelc ---- -The Hazelcast configuration file is optional. For more information, see xref:ROOT:distributed-session-caching.adoc[Distributed session caching]. === Specify JCache vendor-specific properties From e1b426741d942da41f6063e3e7292ce8c3bc26e6 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Tue, 5 Dec 2023 11:59:16 -0500 Subject: [PATCH 47/58] Update examples.adoc --- modules/reference/pages/feature/sessionCache/examples.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/reference/pages/feature/sessionCache/examples.adoc b/modules/reference/pages/feature/sessionCache/examples.adoc index f41d319087..3dec8d0dde 100644 --- a/modules/reference/pages/feature/sessionCache/examples.adoc +++ b/modules/reference/pages/feature/sessionCache/examples.adoc @@ -7,7 +7,7 @@ The `sessionCache` feature does not include a JCache implementation, so you must You must define a location for the implementation files with the `library` element and reference that library by specifying the `jCacheLibraryRef` attribute for the `cachingProvider` element. In the following example, Hazelcast is specified as the JCache implementation. -The `library` element specifies that Hazelcast which is located in the `hazelcast.jar` library, must be used as the JCache provider: +The `library` element specifies that Hazelcast, which is located in the `hazelcast.jar` library, must be used as the JCache provider: [source, xml] ---- From fbfce3ec439cce98048f16cdd917499145d7f1ed Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Wed, 6 Dec 2023 15:34:42 +0530 Subject: [PATCH 48/58] 7062-Added-mp-50-51-diff-to-doc-3 7062-Added-mp-50-51-diff-to-doc-3 #7062 --- modules/reference/pages/diff/mp-60-61-diff.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/reference/pages/diff/mp-60-61-diff.adoc b/modules/reference/pages/diff/mp-60-61-diff.adoc index 2659b5c834..e7ee002fa6 100644 --- a/modules/reference/pages/diff/mp-60-61-diff.adoc +++ b/modules/reference/pages/diff/mp-60-61-diff.adoc @@ -18,7 +18,7 @@ MicroProfile 6.1 is a minor release. It includes the minor changes from Config 3.1, Metrics 5.1, Telemetry 1.1. -The changes for Config 3.1 are minor specification refinements and TCK improvements. The update makes it clear that the _profile-specific_ feature has no functional impact and influences only the values that are chosen from each configuration source. +The changes for Config 3.1 are minor specification refinements and TCK improvements. The update makes it clear that the _profile-specific_ feature affects only the values that are selected from each configuration source, not among the configuration sources. The TCK updates make sure that the tests are compatible with CDI Lite. If you are updating your application from using MicroProfile 6.0 features to using link:https://github.com/eclipse/microprofile/releases/tag/6.1[MicroProfile 6.1] features, changes in API behavior might require you to update your application code. The following sections provide details about migrating your applications from MicroProfile 6.0 to 6.1: From ded697f76ecb334681fdefb340db3fbac96670a1 Mon Sep 17 00:00:00 2001 From: Anjum Fatima Date: Wed, 6 Dec 2023 11:08:59 -0600 Subject: [PATCH 49/58] Address review comments --- modules/ROOT/pages/instanton-limitations.adoc | 27 ++++++++++--------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/modules/ROOT/pages/instanton-limitations.adoc b/modules/ROOT/pages/instanton-limitations.adoc index 661767bb4d..0b7f8a2d77 100644 --- a/modules/ROOT/pages/instanton-limitations.adoc +++ b/modules/ROOT/pages/instanton-limitations.adoc @@ -23,7 +23,7 @@ The following sections describe the limitations and known issues with using Open - <<#trans-before, Jakarta Transaction before checkpoint>> - <<#mp-config, Accessing MicroProfile Configuration too early>> - <<#datasource, Injecting a DataSource too early>> -- <<#mp-config-no-default, Accessing microprofile config with no default value at Checkpoint>> +- <<#mp-config-no-default, Accessing MicroProfile Configuration with no default value at Checkpoint>> - <<#features, Using product extensions, user features, or features that are not supported by InstantOn>> - <<#boot,Updating configuration with a bootstrap.properties file>> - <<#securitymanager, Java SecurityManager is not supported>> @@ -163,8 +163,10 @@ This configuration uses placeholder values for things like the database name, ho If an application is injected with a `DataSource` before the checkpoint and the configuration of the `DataSource` changes, the application is restarted when the InstantOn application container image is run with the updated configuration. You can avoid this scenario by using the `beforeAppStart` option or by modifying the component not to be early startup code. In this example, that modification is to remove the `loadOnStartup = 1` attribute. [#mp-config-no-default] -== Accessing microprofile config with no default value at Checkpoint -The configuration property can be introduced inside the application either statically through `` or `Optional`, or dynamically using a `Provider`. The following example shows ways to inject static, static-optional, dynamic and dynamic-optional config property. +== Accessing MicroProfile Configuration with no default value at Checkpoint +An application injected with a configuration property that has no default value set in any configuration source during checkpoint could cause some errors. This section provides the different types of error that are encountered and the remedy to fix those errors. + +A configuration property can be introduced into the application either statically or dynamically, and in either case, the property can be declared optional. The following example shows ways to inject static, static-optional, dynamic, and dynamic-optional configuration properties. [source,java] ---- @Inject @@ -183,16 +185,16 @@ The configuration property can be introduced inside the application either stati @ConfigProperty(name = "dynamic_optional_config") Provider> dynamicOptionalConfig; ---- -The injected `static_config` will cause an error like the following example if there is no value found in an existing config source during checkpoint. +If no value is found in an existing configuration source during checkpoint, the injected `static_config` property causes an error similar to the following example: [source,sh] ---- SRCFG02000: Failed to Inject @ConfigProperty for key static_config into io.example.Example.staticConfig since the config property could not be found in any config source. ---- -This error can be avoided by providing a default value for the configuration key in one of the following ways: +You can avoid this error by providing a default value for the configuration key in one of the following ways: -Specify the default value on the @ConfigProperty annotation like the following: +Specify the default value on the `@ConfigProperty` annotation:: [source,java] ---- @Inject @@ -200,32 +202,31 @@ Specify the default value on the @ConfigProperty annotation like the following: String staticConfig; ---- -Specify the default value in the application `META-INF/microprofile-config.properties` resource. +Specify the default value in the application `META-INF/microprofile-config.properties` resource:: [source,sh] ---- static_config=defaultValue ---- -Specify a default value in a server.xml variable. +Specify a default value in a `variable` element in the server.xml` file:: [source,xml] ---- ---- -The `defaultValue` can then be overridden on restore by configuring the value with an environment variable or values from the variable source directory. - -However, if no default value is set, we can still avoid the above error by injecting config using `static_optional_config`, `dynamic_config`, `dynamic_optional_config`. But caution is needed for CDI beans that are `@ApplicationScoped` which are created during application startup when using the afterAppStart checkpoint option. Trying to access the `dynamic_config` early during the application startup at checkpoint can cause the following error: +If no default value is set, you can still avoid the previous error by injecting configuration with the `static_optional_config`, `dynamic_config`, or `dynamic_optional_config` properties. +However, the following error might occur if you use the checkpoint option with CDI beans that are `@ApplicationScoped` and the `dynamic_config` is accessed too early during application startup: [source,sh] ---- java.util.NoSuchElementException: SRCFG00014: The config property dynamic_config is required but it could not be found in any config source. ---- -While accessing the `static_optional_config` and `dynamic_optional_config` can cause the following error: +Similarly, accessing the `static_optional_config` and `dynamic_optional_config` too early might cause the following error: [source,sh] ---- java.util.NoSuchElementException: No value present ---- -Therefore, it is advisable to have a default value set for injected config properties in order to avoid the above mentioned errors. Furthermore, if the @ConfigProperty injection site is not using dynamic config then any default value injected into the application scoped bean before checkpoint will not be updated on restore. This is already mentioned in the docs at xref:#mp-config[Accessing MicroProfile Config too early] +Therefore, to avoid these errors it is best to set a default value for injected config properties as optional and dynamic config can be accessed too early during application startup. Furthermore, if the `@ConfigProperty` injection site is not using dynamic configuration, then any default value that is injected into the application-scoped bean before checkpoint is not updated on restore. For more information, see xref:#mp-config[Accessing MicroProfile Config too early] [#features] From 346d90095daec2bb706d4359d34f287633a4ea97 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Thu, 7 Dec 2023 11:16:31 -0500 Subject: [PATCH 50/58] 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` From 177c3e97b7e5a9683bc037ce76ba025c429bd056 Mon Sep 17 00:00:00 2001 From: Anjum Fatima Date: Thu, 7 Dec 2023 12:27:37 -0600 Subject: [PATCH 51/58] Address ID review comments --- modules/ROOT/pages/instanton-limitations.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/instanton-limitations.adoc b/modules/ROOT/pages/instanton-limitations.adoc index 0b7f8a2d77..853687aef5 100644 --- a/modules/ROOT/pages/instanton-limitations.adoc +++ b/modules/ROOT/pages/instanton-limitations.adoc @@ -23,7 +23,7 @@ The following sections describe the limitations and known issues with using Open - <<#trans-before, Jakarta Transaction before checkpoint>> - <<#mp-config, Accessing MicroProfile Configuration too early>> - <<#datasource, Injecting a DataSource too early>> -- <<#mp-config-no-default, Accessing MicroProfile Configuration with no default value at Checkpoint>> +- <<#mp-config-no-default, Accessing MicroProfile Config properties with no default value at checkpoint>> - <<#features, Using product extensions, user features, or features that are not supported by InstantOn>> - <<#boot,Updating configuration with a bootstrap.properties file>> - <<#securitymanager, Java SecurityManager is not supported>> @@ -163,8 +163,8 @@ This configuration uses placeholder values for things like the database name, ho If an application is injected with a `DataSource` before the checkpoint and the configuration of the `DataSource` changes, the application is restarted when the InstantOn application container image is run with the updated configuration. You can avoid this scenario by using the `beforeAppStart` option or by modifying the component not to be early startup code. In this example, that modification is to remove the `loadOnStartup = 1` attribute. [#mp-config-no-default] -== Accessing MicroProfile Configuration with no default value at Checkpoint -An application injected with a configuration property that has no default value set in any configuration source during checkpoint could cause some errors. This section provides the different types of error that are encountered and the remedy to fix those errors. +== Accessing MicroProfile Config properties with no default value at checkpoint +An application injected with a configuration property that has no default value set in any configuration source might cause errors during checkpoint. This section provides solutions for common errors that are encountered. A configuration property can be introduced into the application either statically or dynamically, and in either case, the property can be declared optional. The following example shows ways to inject static, static-optional, dynamic, and dynamic-optional configuration properties. [source,java] From 1815dd203d0008758e1d7ad3e806c03fe6cd2ef4 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Thu, 7 Dec 2023 13:46:46 -0500 Subject: [PATCH 52/58] add OCP SCC info #7090 --- modules/ROOT/pages/instanton.adoc | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/modules/ROOT/pages/instanton.adoc b/modules/ROOT/pages/instanton.adoc index f6c40069a4..9dde35068d 100644 --- a/modules/ROOT/pages/instanton.adoc +++ b/modules/ROOT/pages/instanton.adoc @@ -338,6 +338,36 @@ When you deploy to Kubernetes, the container must be granted the `CHECKPOINT_RES - ALL ---- +==== Red Hat OpenShift security context constraints + +To deploy applications to Red Hat OpenShift with InstantOn, you must specify a security context constraint (SCC) that at a minimum grants the capabilities to the defaults that are needed for InstantOn. The following example defines an SCC with these capabilities that is called `defaultAddCapabilities`: + +[source,yaml] +---- +defaultAddCapabilities: +- CHECKPOINT_RESTORE +- SETPCAP +---- + +The applications you deploy must be associated with this SCC, for example, by specifying the `serviceAccountName` setting in the deployment yaml file. The following example specifies the `defaultAddCapabilities` SCC that was defined in the previous example: + +[source,yaml] +---- + serviceAccountName: defaultAddCapabilities + securityContext: + allowPrivilegeEscalation: true + privileged: false + runAsNonRoot: true + capabilities: + add: + - CHECKPOINT_RESTORE + - SETPCAP + drop: + - ALL +---- + +For more information, see the Red Hat documentation for link:https://docs.openshift.com/container-platform/latest/authentication/managing-security-context-constraints.html[Managing security context constraints]. + [#supported-features] == Open Liberty InstantOn supported features From e76115c9972f2507da4f7644c5ad6ec2165ed8e2 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Thu, 7 Dec 2023 15:04:58 -0500 Subject: [PATCH 53/58] edits per review #7090 --- modules/ROOT/pages/instanton.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/instanton.adoc b/modules/ROOT/pages/instanton.adoc index 9dde35068d..de0a0ce02f 100644 --- a/modules/ROOT/pages/instanton.adoc +++ b/modules/ROOT/pages/instanton.adoc @@ -340,7 +340,7 @@ When you deploy to Kubernetes, the container must be granted the `CHECKPOINT_RES ==== Red Hat OpenShift security context constraints -To deploy applications to Red Hat OpenShift with InstantOn, you must specify a security context constraint (SCC) that at a minimum grants the capabilities to the defaults that are needed for InstantOn. The following example defines an SCC with these capabilities that is called `defaultAddCapabilities`: +To deploy applications to Red Hat OpenShift with InstantOn, you must specify a security context constraint (SCC) that at a minimum specifies a list of additional capabilities that are added to any pod. The following SSC yaml file example defines an SCC with the required capabilities by using the `defaultAddCapabilities` parameter : [source,yaml] ---- @@ -349,11 +349,11 @@ defaultAddCapabilities: - SETPCAP ---- -The applications you deploy must be associated with this SCC, for example, by specifying the `serviceAccountName` setting in the deployment yaml file. The following example specifies the `defaultAddCapabilities` SCC that was defined in the previous example: +The applications you deploy must be associated with an SCC that adds the required capabilities. For example, you might deploy an SCC called `liberty-instanton-scc` that adds the required capabilities. The following example specifies the `serviceAccountName` parameter to set the SCC name to `liberty-instanton-scc`: [source,yaml] ---- - serviceAccountName: defaultAddCapabilities + serviceAccountName: liberty-instanton-scc securityContext: allowPrivilegeEscalation: true privileged: false From 44a9f6a1f29937a8ec72bb2a2e5decf86f0d68da Mon Sep 17 00:00:00 2001 From: David Mueller Date: Thu, 7 Dec 2023 16:08:52 -0500 Subject: [PATCH 54/58] Update instanton.adoc --- modules/ROOT/pages/instanton.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/instanton.adoc b/modules/ROOT/pages/instanton.adoc index de0a0ce02f..96aeafab73 100644 --- a/modules/ROOT/pages/instanton.adoc +++ b/modules/ROOT/pages/instanton.adoc @@ -349,7 +349,7 @@ defaultAddCapabilities: - SETPCAP ---- -The applications you deploy must be associated with an SCC that adds the required capabilities. For example, you might deploy an SCC called `liberty-instanton-scc` that adds the required capabilities. The following example specifies the `serviceAccountName` parameter to set the SCC name to `liberty-instanton-scc`: +The applications you deploy must be associated with an SCC that adds the required capabilities. For example, you might deploy an SCC called `liberty-instanton-scc` that adds the required capabilities. The following deployment yaml file example specifies the `serviceAccountName` parameter to set the SCC name to `liberty-instanton-scc`: [source,yaml] ---- From 580ab4bba62dbd59c0ac35113d6f8a4d81e18d8e Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Fri, 8 Dec 2023 13:25:49 +0530 Subject: [PATCH 55/58] 7062-Added-mp-50-51-diff-to-doc-4 7062-Added-mp-50-51-diff-to-doc-4 #7062 --- .../reference/pages/diff/mp-60-61-diff.adoc | 20 ++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/modules/reference/pages/diff/mp-60-61-diff.adoc b/modules/reference/pages/diff/mp-60-61-diff.adoc index e7ee002fa6..1bfecb75af 100644 --- a/modules/reference/pages/diff/mp-60-61-diff.adoc +++ b/modules/reference/pages/diff/mp-60-61-diff.adoc @@ -16,21 +16,27 @@ :page-type: general = Differences between MicroProfile 6.1 and 6.0 -MicroProfile 6.1 is a minor release. It includes the minor changes from Config 3.1, Metrics 5.1, Telemetry 1.1. - -The changes for Config 3.1 are minor specification refinements and TCK improvements. The update makes it clear that the _profile-specific_ feature affects only the values that are selected from each configuration source, not among the configuration sources. The TCK updates make sure that the tests are compatible with CDI Lite. +MicroProfile 6.1 is a minor release. It includes minor changes for the MicroProfile Config 3.1, Metrics 5.1, and Telemetry 1.1 features. If you are updating your application from using MicroProfile 6.0 features to using link:https://github.com/eclipse/microprofile/releases/tag/6.1[MicroProfile 6.1] features, changes in API behavior might require you to update your application code. The following sections provide details about migrating your applications from MicroProfile 6.0 to 6.1: +- <<#config, Differences between MicroProfile Config 3.1 and 3.0>> - <<#metrics, Differences between MicroProfile Metrics 5.0 and 5.1>> - <<#telemetry, Differences between MicroProfile Telemetry 1.0 and 1.1>> + +[#config] +== Differences between MicroProfile Config 3.1 and 3.0 + +The changes for MicroProfile Config 3.1 are minor specification refinements and TCK improvements. The update clarifies that the profile-specific properties affect only the values that are selected from each configuration source, not among the configuration sources. The TCK updates make sure that the tests are compatible with CDI Lite. + + [#metrics] == Differences between MicroProfile Metrics 5.0 and 5.1 The MicroProfile Metrics 5.1 release introduces many changes to the specification and programming model that impact users who are migrating from MicroProfile Metrics 5.0. -The MicroProfile Metrics 5.1 release introduces a swathe of new MicroProfile Config properties that are used to customize the metric data that is tracked and output by the histogram and timer metrics. MicroProfile Metrics 5.1 introduces new properties that make it possible for you to specify a custom range of percentiles and a custom set of histogram buckets specifically for Histogram and Timer metrics. More configuration properties are now available for establishing a default range of histogram buckets, including options to specify the starting and ending points of the bucket set. +The MicroProfile Metrics 5.1 release introduces a set of new MicroProfile Config properties that customize the metric data that is tracked and output by the histogram and timer metrics. MicroProfile Metrics 5.1 introduces properties that specify a custom range of percentiles and a custom set of histogram buckets specifically for histogram and timer metrics. More configuration properties are now available for establishing a default range of histogram buckets, including options to specify the starting and ending points of the bucket set. .New Properties in MicroProfile Metrics 5.1 |=== @@ -63,7 +69,7 @@ The MicroProfile Metrics 5.1 release introduces a swathe of new MicroProfile Con |=== -For more information on the properties and how to use them, see the xref:microprofile-config-properties.adoc#metrics[MicroProfile Config properties: MicroProfile Metrics]. +For more information on the properties and how to use them, see the xref:ROOT:microprofile-config-properties.adoc#metrics[MicroProfile Config properties: MicroProfile Metrics]. The following example of MicroProfile Config definitions sets up the `alpha.timer` metric to output the 50th, 70th, 75th, and 80th percentile. It also configures histogram buckets to track and report the count of durations within specific intervals: from 0 to 100 milliseconds, 0 to 200 milliseconds, and 0 to 1 second. These intervals function as cumulative ranges, which is how the histogram buckets operate. @@ -98,11 +104,11 @@ alpha_timer_seconds_sum{scope="application",} 6.333 <2> The `le` tag represents _less than_ and is for the defined buckets that are converted to seconds. <3> Prometheus requires that a +Inf bucket that count all hits. -Also, the @RegistryScope annotation, suitable for use during metric registry injection, is now a CDI qualifier. +Also, the `@RegistryScope` annotation, suitable for use during metric registry injection, is now a CDI qualifier. [#telemetry] == Differences between MicroProfile Telemetry 1.0 and 1.1 -MicroProfile Telemetry 1.1 equips developers with the most recent Open Telemetry technology; this feature now uses OpenTelemetry-1.29.0, upgraded from 1.19.0. Therefore, a significant number of the dependencies are now stable. +MicroProfile Telemetry 1.1 equips you with the most recent Open Telemetry technology. This feature now uses OpenTelemetry-1.29.0, upgraded from 1.19.0. Therefore, a significant number of the dependencies are now stable. This feature provides seamless integration with several environments. It is compatible with Java EE 7 and MicroProfile 1.4, and also Java EE 8 and MicroProfile 4.1. It also supports Jakarta EE 9 with MicroProfile 5.0, and Jakarta EE 10 paired with MicroProfile 6.1. From eb2cef8eb15861d1b7afab3b2cc1be653c97ac55 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Fri, 8 Dec 2023 16:03:54 +0530 Subject: [PATCH 56/58] 7062-Added-mp-50-51-diff-to-doc-5 7062-Added-mp-50-51-diff-to-doc-5 #7062 --- .../reference/pages/feature/microProfile-6.1/description.adoc | 1 + 1 file changed, 1 insertion(+) create mode 100644 modules/reference/pages/feature/microProfile-6.1/description.adoc diff --git a/modules/reference/pages/feature/microProfile-6.1/description.adoc b/modules/reference/pages/feature/microProfile-6.1/description.adoc new file mode 100644 index 0000000000..0208e2bcc4 --- /dev/null +++ b/modules/reference/pages/feature/microProfile-6.1/description.adoc @@ -0,0 +1 @@ +If you are updating your application from using MicroProfile 6.0 features to using MicroProfile 6.1 features, changes in API behavior might require you to update your application code. For more information, see xref:diff/mp-60-61-diff.adoc[Differences between MicroProfile 6.1 and 6.0]. \ No newline at end of file From baa71b5e2eab867c11ef42e1494b316a2e161e8d Mon Sep 17 00:00:00 2001 From: David Mueller Date: Fri, 8 Dec 2023 11:52:20 -0500 Subject: [PATCH 57/58] edits per peer review #7090 --- modules/ROOT/pages/instanton.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/instanton.adoc b/modules/ROOT/pages/instanton.adoc index 96aeafab73..75a665d2da 100644 --- a/modules/ROOT/pages/instanton.adoc +++ b/modules/ROOT/pages/instanton.adoc @@ -318,7 +318,7 @@ Currently, Open Liberty InstantOn is tested and supported on the following publi - link:https://aws.amazon.com/eks/[Amazon Elastic Kubernetes Service (EKS)] - link:https://azure.microsoft.com/en-us/products/kubernetes-service[Azure Kubernetes Service (AKS)] -- link:https://www.redhat.com/en/technologies/cloud-computing/openshift[Red Hat OpenShift] (version 4.14 and later) +- link:https://www.redhat.com/en/technologies/cloud-computing/openshift[Red Hat OpenShift (version 4.14 and later)] Other public cloud Kubernetes services might also work if they have the <<#required-to-restore,prerequisites>> to allow the InstantOn application process to restore. @@ -340,7 +340,7 @@ When you deploy to Kubernetes, the container must be granted the `CHECKPOINT_RES ==== Red Hat OpenShift security context constraints -To deploy applications to Red Hat OpenShift with InstantOn, you must specify a security context constraint (SCC) that at a minimum specifies a list of additional capabilities that are added to any pod. The following SSC yaml file example defines an SCC with the required capabilities by using the `defaultAddCapabilities` parameter : +To deploy applications to Red Hat OpenShift with InstantOn, you must specify a security context constraint (SCC) that, at a minimum, specifies a list of additional capabilities that are added to any pod. The following SSC yaml file example defines an SCC with the required capabilities by using the `defaultAddCapabilities` parameter: [source,yaml] ---- @@ -349,7 +349,7 @@ defaultAddCapabilities: - SETPCAP ---- -The applications you deploy must be associated with an SCC that adds the required capabilities. For example, you might deploy an SCC called `liberty-instanton-scc` that adds the required capabilities. The following deployment yaml file example specifies the `serviceAccountName` parameter to set the SCC name to `liberty-instanton-scc`: +The applications you deploy must be associated with an SCC that adds the required capabilities. For example, you might deploy an SCC called `liberty-instanton-scc` that adds the required capabilities. In the following example, the deployment yaml file specifies the `serviceAccountName` parameter to set the SCC name to `liberty-instanton-scc`: [source,yaml] ---- From 4f125cfb33b63be93d5f7a36330db605279313f2 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Fri, 8 Dec 2023 22:23:44 +0530 Subject: [PATCH 58/58] 7062-MP 6.1 and 6.0 Difference 7062-MP 6.1 and 6.0 Difference --- modules/reference/nav.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/reference/nav.adoc b/modules/reference/nav.adoc index 3a4ec8ae95..8027279b78 100644 --- a/modules/reference/nav.adoc +++ b/modules/reference/nav.adoc @@ -71,6 +71,7 @@ include::reference:partial$feature-nav.adoc[] ** xref:javadoc/microprofile-1.4-javadoc.adoc[MicroProfile 1.4] ** xref:javadoc/microprofile-1.3-javadoc.adoc[MicroProfile 1.3] ** xref:javadoc/microprofile-1.2-javadoc.adoc[MicroProfile 1.2] + ** xref:diff/mp-60-61-diff.adoc[Differences between MicroProfile 6.1 and 6.0] ** xref:diff/mp-50-60-diff.adoc[Differences between MicroProfile 6.0 and 5.0] ** xref:diff/mp-41-50-diff.adoc[Differences between MicroProfile 5.0 and 4.1] ** xref:diff/mp-33-40-diff.adoc[Differences between MicroProfile 4.0 and 3.3]