From 4c9819c5bde7cc636e380431c473679fe4610d90 Mon Sep 17 00:00:00 2001 From: Benjamin Confino Date: Tue, 17 Sep 2024 12:31:05 +0100 Subject: [PATCH 01/81] add ft metrics to open telemetry metric list --- .../ROOT/pages/mptelemetry-metrics-list.adoc | 105 ++++++++++++++++++ 1 file changed, 105 insertions(+) diff --git a/modules/ROOT/pages/mptelemetry-metrics-list.adoc b/modules/ROOT/pages/mptelemetry-metrics-list.adoc index 79b23d104..4f49aa319 100644 --- a/modules/ROOT/pages/mptelemetry-metrics-list.adoc +++ b/modules/ROOT/pages/mptelemetry-metrics-list.adoc @@ -19,6 +19,8 @@ :mp-4-0: feature:mpMetrics-4.0[display=MicroProfile Metrics 4.0] :mp-5-0: feature:mpMetrics-5.0[display=MicroProfile Metrics 5.0] :mp-ft-3-0: feature:mpFaultTolerance-3.0[display=MicroProfile Fault Tolerance 3.0] +:mp-tel-2-0: feature:mpTelemetry-2.0[display=MicroProfile Telemetry 2.0] +:mp-tel-2-0-ft-4-1: feature:mpTelemetry-2.0[display=MicroProfile Telemetry 2.0] and feature:mpFaultTolerance-4.1[display=MicroProfile Fault Tolerance 4.1] :connector-metric-features: feature:mpMetrics[display=MicroProfile Metrics] and feature:mpReactiveMessaging[display=MicroProfile Reactive Messaging 3.0] :base-metric-features: feature:mpMetrics[display=MicroProfile Metrics] :vendor-metric-features: feature:mpMetrics[display=MicroProfile Metrics] @@ -304,6 +306,109 @@ The **Version introduced** column specifies the minimum version of the feature t | feature:mpTelemetry[display=MicroProfile Telemetry] | feature:mpTelemetry-2.0[display=MicroProfile Telemetry 2.0] +| ft.invocations.total +| * `method` - the fully qualified method name +* `result = [valueReturned\|exceptionThrown]` - whether the invocation returned a value or threw an exception +* `fallback = [applied\|notApplied\|notDefined]` - `applied` if fallback was used, `notApplied` if a fallback is configured but was not used, `notDefined` if a fallback is not configured. +| The number of times the method was called. This metric is a `LongCounter`. +| n/a +| {mp-tel-2-0-ft-4-1} +| {mp-tel-2-0} + +| ft.retry.calls.total +| * `method` - the fully qualified method name, +* `retried = [true\|false]` - whether any retries occurred +* `retryResult = [valueReturned\|exceptionNotRetryable\|maxRetriesReached\|maxDurationReached]` - the reason that last attempt to call the method was not retried. +| The number of times the retry logic was run. This value is always equal to once per method call. This metric is a `LongCounter`. +| n/a +| {mp-tel-2-0-ft-4-1} +| {mp-tel-2-0} + +| ft.retry.retries.total +| `method` - the fully qualified method name +| The number of times the method was retried. This metric is a `LongCounter`. +| `method` - the fully qualified method name +| {mp-tel-2-0-ft-4-1} +| {mp-tel-2-0} + +| ft.timeout.calls.total +| * `method` - the fully qualified method name +* `timedOut = [true\|false]` - whether the method call timed out +| The number of times the timeout logic was run. This value is typically equal to once per method call. However, it might be zero if the circuit breaker prevents execution or more than once per method call if the method is retried. This metric is a `LongCounter`. +| n/a +| {mp-tel-2-0-ft-4-1} +| {mp-tel-2-0} + +| ft.timeout.executionDuration +| `method` - the fully qualified method name +| Histogram of execution times for the method. This metric is a `DoubleHistogram` +| n/a +| {mp-tel-2-0-ft-4-1} +| {mp-tel-2-0} + +| ft.circuitbreaker.calls.total +| * `method` - the fully qualified method name, + * `circuitBreakerResult = [success\|failure\|circuitBreakerOpen]` - the result of the method call, as considered by the circuit breaker according to the rules in https://download.eclipse.org/microprofile/microprofile-fault-tolerance-4.0.2/microprofile-fault-tolerance-spec-4.0.2.html#circuit-breaker-success-failure[Configuring which exceptions are considered a failure] + ** `success` - the method ran and was successful + ** `failure` - the method ran and failed + ** `circuitBreakerOpen` - the method did not run because the circuit breaker was in open or half-open state + +| The number of times the circuit breaker logic was run. This value is typically equal to once per method call, but might be more than once if the method is retried. This metric is a `LongCounter`. +| n/a +| {mp-tel-2-0-ft-4-1} +| {mp-tel-2-0} + +| ft.circuitbreaker.state.total +| * `method` - the fully qualified method name + * `state = [open\|closed\|halfOpen]` - the circuit breaker state +| Amount of time the circuit breaker spent in each state. This metric is a `LongCounter`. +| n/a +| {mp-tel-2-0-ft-4-1} +| {mp-tel-2-0} + +| ft.circuitbreaker.opened.total +| `method` - the fully qualified method name +| Number of times the circuit breaker moved from closed state to open state. This metric is a `LongCounter`. +| n/a +| {mp-tel-2-0-ft-4-1} +| {mp-tel-2-0} + +| ft.bulkhead.calls.total +| * `method` - the fully qualified method name +* `bulkheadResult = [accepted\|rejected]` - whether the bulkhead allowed the method call to run +| The number of times the bulkhead logic was run. This value is typically equal to once per method call. However, it might be zero if the circuit breaker prevents execution or more than once per method call if the method is retried. This metric is a `LongCounter`. +| n/a +| {mp-tel-2-0-ft-4-1} +| {mp-tel-2-0} + +| ft.bulkhead.executionsRunning +| `method` - the fully qualified method name +| Number of currently running executions. This metric is a `LongUpDownCounter`. +| n/a +| {mp-tel-2-0-ft-4-1} +| {mp-tel-2-0} + +| ft.bulkhead.executionsWaiting +| `method` - the fully qualified method name +| Number of executions that are currently waiting in the queue. This metric is a `LongUpDownCounter`. +| n/a +| {mp-tel-2-0-ft-4-1} +| {mp-tel-2-0} + +| ft.bulkhead.runningDuration +| `method` - the fully qualified method name +| Histogram of the time that method executions spent running. This metric is a `DoubleHistogram`. +| n/a +| {mp-tel-2-0-ft-4-1} +| {mp-tel-2-0} + +| ft.bulkhead.waitingDuration +| `method` - the fully qualified method name +| Histogram of the time that method executions spent waiting in the queue. This metric is a `DoubleHistogram`. +| n/a +| {mp-tel-2-0-ft-4-1} +| {mp-tel-2-0} + |=== {empty} + From 019bc3da0c677104508cf1d7d0348e04f1b77b0b Mon Sep 17 00:00:00 2001 From: Benjamin Confino Date: Thu, 26 Sep 2024 10:01:22 +0100 Subject: [PATCH 02/81] Implement review comments --- .../ROOT/pages/mptelemetry-metrics-list.adoc | 210 +++++++++--------- 1 file changed, 106 insertions(+), 104 deletions(-) diff --git a/modules/ROOT/pages/mptelemetry-metrics-list.adoc b/modules/ROOT/pages/mptelemetry-metrics-list.adoc index 4f49aa319..0825a67d0 100644 --- a/modules/ROOT/pages/mptelemetry-metrics-list.adoc +++ b/modules/ROOT/pages/mptelemetry-metrics-list.adoc @@ -77,6 +77,112 @@ The **Version introduced** column specifies the minimum version of the feature t |=== | MicroProfile Telemetry 2.0 name | Attributes | Type and description | Monitoring component | Features required | Version introduced +| ft.bulkhead.calls.total +| * `method` : the fully qualified method name +* `bulkheadResult = [accepted\|rejected]` : whether the bulkhead allowed the method call to run +| The number of times the bulkhead logic was run. This value is typically equal to once per method call. However, it might be zero if the circuit breaker prevents execution or more than once per method call if the method is retried. This metric is a `LongCounter`. +| n/a +| {mp-tel-2-0-ft-4-1} +| {mp-tel-2-0} + +| ft.bulkhead.executionsRunning +| `method` : the fully qualified method name +| Number of currently running executions. This metric is a `LongUpDownCounter`. +| n/a +| {mp-tel-2-0-ft-4-1} +| {mp-tel-2-0} + +| ft.bulkhead.executionsWaiting +| `method` : the fully qualified method name +| Number of executions that are currently waiting in the queue. This metric is a `LongUpDownCounter`. +| n/a +| {mp-tel-2-0-ft-4-1} +| {mp-tel-2-0} + +| ft.bulkhead.runningDuration +| `method` : the fully qualified method name +| Histogram of the time that method executions spent running. This metric is a `DoubleHistogram`. +| n/a +| {mp-tel-2-0-ft-4-1} +| {mp-tel-2-0} + +| ft.bulkhead.waitingDuration +| `method` : the fully qualified method name +| Histogram of the time that method executions spent waiting in the queue. This metric is a `DoubleHistogram`. +| n/a +| {mp-tel-2-0-ft-4-1} +| {mp-tel-2-0} + +| ft.circuitbreaker.calls.total +| * `method` : the fully qualified method name, + * `circuitBreakerResult = [success\|failure\|circuitBreakerOpen]` : the result of the method call, as considered by the circuit breaker according to the rules in https://download.eclipse.org/microprofile/microprofile-fault-tolerance-4.0.2/microprofile-fault-tolerance-spec-4.0.2.html#circuit-breaker-success-failure[Configuring which exceptions are considered a failure] + ** `success` : the method ran and was successful + ** `failure` : the method ran and failed + ** `circuitBreakerOpen` : the method did not run because the circuit breaker was in open or half-open state + +| The number of times the circuit breaker logic was run. This value is typically equal to once per method call, but might be more than once if the method is retried. This metric is a `LongCounter`. +| n/a +| {mp-tel-2-0-ft-4-1} +| {mp-tel-2-0} + +| ft.circuitbreaker.opened.total +| `method` : the fully qualified method name +| Number of times the circuit breaker moved from closed state to open state. This metric is a `LongCounter`. +| n/a +| {mp-tel-2-0-ft-4-1} +| {mp-tel-2-0} + +| ft.circuitbreaker.state.total +| * `method` : the fully qualified method name + * `state = [open\|closed\|halfOpen]` : the circuit breaker state +| Amount of time the circuit breaker spent in each state. This metric is a `LongCounter`. +| n/a +| {mp-tel-2-0-ft-4-1} +| {mp-tel-2-0} + +| ft.invocations.total +| * `method` : the fully qualified method name +* `result = [valueReturned\|exceptionThrown]` : whether the invocation returned a value or threw an exception +* `fallback = [applied\|notApplied\|notDefined]` : Wheather the fallback method was invoked + ** `applied` if fallback was used + ** `notApplied` if a fallback is configured but was not used + ** `notDefined` if a fallback is not configured. +| The number of times the method was called. This metric is a `LongCounter`. +| n/a +| {mp-tel-2-0-ft-4-1} +| {mp-tel-2-0} + +| ft.retry.calls.total +| * `method` : the fully qualified method name, +* `retried = [true\|false]` : whether any retries occurred +* `retryResult = [valueReturned\|exceptionNotRetryable\|maxRetriesReached\|maxDurationReached]` - the reason that last attempt to call the method was not retried. +| The number of times the retry logic was run. This value is always equal to once per method call. This metric is a `LongCounter`. +| n/a +| {mp-tel-2-0-ft-4-1} +| {mp-tel-2-0} + +| ft.retry.retries.total +| `method` : the fully qualified method name +| The number of times the method was retried. This metric is a `LongCounter`. +| n/a +| {mp-tel-2-0-ft-4-1} +| {mp-tel-2-0} + +| ft.timeout.executionDuration +| `method` : the fully qualified method name +| Histogram of execution times for the method. This metric is a `DoubleHistogram` +| n/a +| {mp-tel-2-0-ft-4-1} +| {mp-tel-2-0} + +| ft.timeout.calls.total +| * `method` : the fully qualified method name +* `timedOut = [true\|false]` : whether the method call timed out +| The number of times the timeout logic was run. This value is typically equal to once per method call. However, it might be zero if the circuit breaker prevents execution or more than once per method call if the method is retried. This metric is a `LongCounter`. +| n/a +| {mp-tel-2-0-ft-4-1} +| {mp-tel-2-0} + | `http.server.request.duration` |* `http.request.method` * `url.scheme` @@ -270,7 +376,6 @@ The **Version introduced** column specifies the minimum version of the feature t | feature:mpTelemetry[display=MicroProfile Telemetry] | feature:mpTelemetry-2.0[display=MicroProfile Telemetry 2.0] - | jvm.class.unloaded | n/a | Number of classes unloaded since JVM start. This metric is a Counter. / ({class}) @@ -306,109 +411,6 @@ The **Version introduced** column specifies the minimum version of the feature t | feature:mpTelemetry[display=MicroProfile Telemetry] | feature:mpTelemetry-2.0[display=MicroProfile Telemetry 2.0] -| ft.invocations.total -| * `method` - the fully qualified method name -* `result = [valueReturned\|exceptionThrown]` - whether the invocation returned a value or threw an exception -* `fallback = [applied\|notApplied\|notDefined]` - `applied` if fallback was used, `notApplied` if a fallback is configured but was not used, `notDefined` if a fallback is not configured. -| The number of times the method was called. This metric is a `LongCounter`. -| n/a -| {mp-tel-2-0-ft-4-1} -| {mp-tel-2-0} - -| ft.retry.calls.total -| * `method` - the fully qualified method name, -* `retried = [true\|false]` - whether any retries occurred -* `retryResult = [valueReturned\|exceptionNotRetryable\|maxRetriesReached\|maxDurationReached]` - the reason that last attempt to call the method was not retried. -| The number of times the retry logic was run. This value is always equal to once per method call. This metric is a `LongCounter`. -| n/a -| {mp-tel-2-0-ft-4-1} -| {mp-tel-2-0} - -| ft.retry.retries.total -| `method` - the fully qualified method name -| The number of times the method was retried. This metric is a `LongCounter`. -| `method` - the fully qualified method name -| {mp-tel-2-0-ft-4-1} -| {mp-tel-2-0} - -| ft.timeout.calls.total -| * `method` - the fully qualified method name -* `timedOut = [true\|false]` - whether the method call timed out -| The number of times the timeout logic was run. This value is typically equal to once per method call. However, it might be zero if the circuit breaker prevents execution or more than once per method call if the method is retried. This metric is a `LongCounter`. -| n/a -| {mp-tel-2-0-ft-4-1} -| {mp-tel-2-0} - -| ft.timeout.executionDuration -| `method` - the fully qualified method name -| Histogram of execution times for the method. This metric is a `DoubleHistogram` -| n/a -| {mp-tel-2-0-ft-4-1} -| {mp-tel-2-0} - -| ft.circuitbreaker.calls.total -| * `method` - the fully qualified method name, - * `circuitBreakerResult = [success\|failure\|circuitBreakerOpen]` - the result of the method call, as considered by the circuit breaker according to the rules in https://download.eclipse.org/microprofile/microprofile-fault-tolerance-4.0.2/microprofile-fault-tolerance-spec-4.0.2.html#circuit-breaker-success-failure[Configuring which exceptions are considered a failure] - ** `success` - the method ran and was successful - ** `failure` - the method ran and failed - ** `circuitBreakerOpen` - the method did not run because the circuit breaker was in open or half-open state - -| The number of times the circuit breaker logic was run. This value is typically equal to once per method call, but might be more than once if the method is retried. This metric is a `LongCounter`. -| n/a -| {mp-tel-2-0-ft-4-1} -| {mp-tel-2-0} - -| ft.circuitbreaker.state.total -| * `method` - the fully qualified method name - * `state = [open\|closed\|halfOpen]` - the circuit breaker state -| Amount of time the circuit breaker spent in each state. This metric is a `LongCounter`. -| n/a -| {mp-tel-2-0-ft-4-1} -| {mp-tel-2-0} - -| ft.circuitbreaker.opened.total -| `method` - the fully qualified method name -| Number of times the circuit breaker moved from closed state to open state. This metric is a `LongCounter`. -| n/a -| {mp-tel-2-0-ft-4-1} -| {mp-tel-2-0} - -| ft.bulkhead.calls.total -| * `method` - the fully qualified method name -* `bulkheadResult = [accepted\|rejected]` - whether the bulkhead allowed the method call to run -| The number of times the bulkhead logic was run. This value is typically equal to once per method call. However, it might be zero if the circuit breaker prevents execution or more than once per method call if the method is retried. This metric is a `LongCounter`. -| n/a -| {mp-tel-2-0-ft-4-1} -| {mp-tel-2-0} - -| ft.bulkhead.executionsRunning -| `method` - the fully qualified method name -| Number of currently running executions. This metric is a `LongUpDownCounter`. -| n/a -| {mp-tel-2-0-ft-4-1} -| {mp-tel-2-0} - -| ft.bulkhead.executionsWaiting -| `method` - the fully qualified method name -| Number of executions that are currently waiting in the queue. This metric is a `LongUpDownCounter`. -| n/a -| {mp-tel-2-0-ft-4-1} -| {mp-tel-2-0} - -| ft.bulkhead.runningDuration -| `method` - the fully qualified method name -| Histogram of the time that method executions spent running. This metric is a `DoubleHistogram`. -| n/a -| {mp-tel-2-0-ft-4-1} -| {mp-tel-2-0} - -| ft.bulkhead.waitingDuration -| `method` - the fully qualified method name -| Histogram of the time that method executions spent waiting in the queue. This metric is a `DoubleHistogram`. -| n/a -| {mp-tel-2-0-ft-4-1} -| {mp-tel-2-0} - |=== {empty} + From 8cfb4bd4acffaa2e26e74811349a5709b02bc1e5 Mon Sep 17 00:00:00 2001 From: Benjamin Confino Date: Thu, 26 Sep 2024 15:52:30 +0100 Subject: [PATCH 03/81] second batch of review comments --- .../ROOT/pages/mptelemetry-metrics-list.adoc | 54 +++++++++---------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/modules/ROOT/pages/mptelemetry-metrics-list.adoc b/modules/ROOT/pages/mptelemetry-metrics-list.adoc index 0825a67d0..faba711a1 100644 --- a/modules/ROOT/pages/mptelemetry-metrics-list.adoc +++ b/modules/ROOT/pages/mptelemetry-metrics-list.adoc @@ -78,47 +78,47 @@ The **Version introduced** column specifies the minimum version of the feature t | MicroProfile Telemetry 2.0 name | Attributes | Type and description | Monitoring component | Features required | Version introduced | ft.bulkhead.calls.total -| * `method` : the fully qualified method name -* `bulkheadResult = [accepted\|rejected]` : whether the bulkhead allowed the method call to run +| * `method`: The fully qualified method name +* `bulkheadResult = [accepted\|rejected]`: Whether the bulkhead allowed the method call to run | The number of times the bulkhead logic was run. This value is typically equal to once per method call. However, it might be zero if the circuit breaker prevents execution or more than once per method call if the method is retried. This metric is a `LongCounter`. | n/a | {mp-tel-2-0-ft-4-1} | {mp-tel-2-0} | ft.bulkhead.executionsRunning -| `method` : the fully qualified method name +| `method`: The fully qualified method name | Number of currently running executions. This metric is a `LongUpDownCounter`. | n/a | {mp-tel-2-0-ft-4-1} | {mp-tel-2-0} | ft.bulkhead.executionsWaiting -| `method` : the fully qualified method name +| `method`: The fully qualified method name | Number of executions that are currently waiting in the queue. This metric is a `LongUpDownCounter`. | n/a | {mp-tel-2-0-ft-4-1} | {mp-tel-2-0} | ft.bulkhead.runningDuration -| `method` : the fully qualified method name +| `method`: The fully qualified method name | Histogram of the time that method executions spent running. This metric is a `DoubleHistogram`. | n/a | {mp-tel-2-0-ft-4-1} | {mp-tel-2-0} | ft.bulkhead.waitingDuration -| `method` : the fully qualified method name +| `method`: The fully qualified method name | Histogram of the time that method executions spent waiting in the queue. This metric is a `DoubleHistogram`. | n/a | {mp-tel-2-0-ft-4-1} | {mp-tel-2-0} | ft.circuitbreaker.calls.total -| * `method` : the fully qualified method name, - * `circuitBreakerResult = [success\|failure\|circuitBreakerOpen]` : the result of the method call, as considered by the circuit breaker according to the rules in https://download.eclipse.org/microprofile/microprofile-fault-tolerance-4.0.2/microprofile-fault-tolerance-spec-4.0.2.html#circuit-breaker-success-failure[Configuring which exceptions are considered a failure] - ** `success` : the method ran and was successful - ** `failure` : the method ran and failed - ** `circuitBreakerOpen` : the method did not run because the circuit breaker was in open or half-open state +| * `method`: The fully qualified method name, + * `circuitBreakerResult = [success\|failure\|circuitBreakerOpen]`: The result of the method call, as considered by the circuit breaker according to the rules in https://download.eclipse.org/microprofile/microprofile-fault-tolerance-4.0.2/microprofile-fault-tolerance-spec-4.0.2.html#circuit-breaker-success-failure[Configuring which exceptions are considered a failure] + ** `success`: The method ran and was successful + ** `failure`: The method ran and failed + ** `circuitBreakerOpen`: The method did not run because the circuit breaker was in open or half-open state | The number of times the circuit breaker logic was run. This value is typically equal to once per method call, but might be more than once if the method is retried. This metric is a `LongCounter`. | n/a @@ -126,58 +126,58 @@ The **Version introduced** column specifies the minimum version of the feature t | {mp-tel-2-0} | ft.circuitbreaker.opened.total -| `method` : the fully qualified method name +| `method`: The fully qualified method name | Number of times the circuit breaker moved from closed state to open state. This metric is a `LongCounter`. | n/a | {mp-tel-2-0-ft-4-1} | {mp-tel-2-0} | ft.circuitbreaker.state.total -| * `method` : the fully qualified method name - * `state = [open\|closed\|halfOpen]` : the circuit breaker state +| * `method`: The fully qualified method name + * `state = [open\|closed\|halfOpen]`: the circuit breaker state | Amount of time the circuit breaker spent in each state. This metric is a `LongCounter`. | n/a | {mp-tel-2-0-ft-4-1} | {mp-tel-2-0} | ft.invocations.total -| * `method` : the fully qualified method name -* `result = [valueReturned\|exceptionThrown]` : whether the invocation returned a value or threw an exception -* `fallback = [applied\|notApplied\|notDefined]` : Wheather the fallback method was invoked - ** `applied` if fallback was used - ** `notApplied` if a fallback is configured but was not used - ** `notDefined` if a fallback is not configured. +| * `method`: The fully qualified method name +* `result = [valueReturned\|exceptionThrown]`: Whether the invocation returned a value or threw an exception +* `fallback = [applied\|notApplied\|notDefined]`: Wheather the fallback method was invoked + ** `applied` If fallback was used + ** `notApplied` If a fallback is configured but was not used + ** `notDefined` If a fallback is not configured. | The number of times the method was called. This metric is a `LongCounter`. | n/a | {mp-tel-2-0-ft-4-1} | {mp-tel-2-0} | ft.retry.calls.total -| * `method` : the fully qualified method name, -* `retried = [true\|false]` : whether any retries occurred -* `retryResult = [valueReturned\|exceptionNotRetryable\|maxRetriesReached\|maxDurationReached]` - the reason that last attempt to call the method was not retried. +| * `method`: The fully qualified method name, +* `retried = [true\|false]`: Whether any retries occurred +* `retryResult = [valueReturned\|exceptionNotRetryable\|maxRetriesReached\|maxDurationReached]` - The reason that last attempt to call the method was not retried. | The number of times the retry logic was run. This value is always equal to once per method call. This metric is a `LongCounter`. | n/a | {mp-tel-2-0-ft-4-1} | {mp-tel-2-0} | ft.retry.retries.total -| `method` : the fully qualified method name +| `method`: The fully qualified method name | The number of times the method was retried. This metric is a `LongCounter`. | n/a | {mp-tel-2-0-ft-4-1} | {mp-tel-2-0} | ft.timeout.executionDuration -| `method` : the fully qualified method name +| `method`: The fully qualified method name | Histogram of execution times for the method. This metric is a `DoubleHistogram` | n/a | {mp-tel-2-0-ft-4-1} | {mp-tel-2-0} | ft.timeout.calls.total -| * `method` : the fully qualified method name -* `timedOut = [true\|false]` : whether the method call timed out +| * `method`: The fully qualified method name +* `timedOut = [true\|false]`: Whether the method call timed out | The number of times the timeout logic was run. This value is typically equal to once per method call. However, it might be zero if the circuit breaker prevents execution or more than once per method call if the method is retried. This metric is a `LongCounter`. | n/a | {mp-tel-2-0-ft-4-1} From f0f85252298baf1896872ee3f2302b9ebff55b91 Mon Sep 17 00:00:00 2001 From: David Mueller <48686014+dmuelle@users.noreply.github.com> Date: Thu, 26 Sep 2024 11:00:16 -0400 Subject: [PATCH 04/81] Update modules/ROOT/pages/mptelemetry-metrics-list.adoc --- modules/ROOT/pages/mptelemetry-metrics-list.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/mptelemetry-metrics-list.adoc b/modules/ROOT/pages/mptelemetry-metrics-list.adoc index faba711a1..8a62a58e4 100644 --- a/modules/ROOT/pages/mptelemetry-metrics-list.adoc +++ b/modules/ROOT/pages/mptelemetry-metrics-list.adoc @@ -143,7 +143,7 @@ The **Version introduced** column specifies the minimum version of the feature t | ft.invocations.total | * `method`: The fully qualified method name * `result = [valueReturned\|exceptionThrown]`: Whether the invocation returned a value or threw an exception -* `fallback = [applied\|notApplied\|notDefined]`: Wheather the fallback method was invoked +* `fallback = [applied\|notApplied\|notDefined]`: Whether the fallback method was invoked ** `applied` If fallback was used ** `notApplied` If a fallback is configured but was not used ** `notDefined` If a fallback is not configured. From 64732780ee4878765ef19f49b364ea71b05dea98 Mon Sep 17 00:00:00 2001 From: Benjamin Confino Date: Wed, 2 Oct 2024 15:23:04 +0100 Subject: [PATCH 05/81] Apply suggestions from code review Co-authored-by: David Mueller <48686014+dmuelle@users.noreply.github.com> --- modules/ROOT/pages/mptelemetry-metrics-list.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/mptelemetry-metrics-list.adoc b/modules/ROOT/pages/mptelemetry-metrics-list.adoc index 8a62a58e4..95694cfa9 100644 --- a/modules/ROOT/pages/mptelemetry-metrics-list.adoc +++ b/modules/ROOT/pages/mptelemetry-metrics-list.adoc @@ -134,7 +134,7 @@ The **Version introduced** column specifies the minimum version of the feature t | ft.circuitbreaker.state.total | * `method`: The fully qualified method name - * `state = [open\|closed\|halfOpen]`: the circuit breaker state + * `state = [open\|closed\|halfOpen]`: The circuit breaker state | Amount of time the circuit breaker spent in each state. This metric is a `LongCounter`. | n/a | {mp-tel-2-0-ft-4-1} @@ -155,7 +155,7 @@ The **Version introduced** column specifies the minimum version of the feature t | ft.retry.calls.total | * `method`: The fully qualified method name, * `retried = [true\|false]`: Whether any retries occurred -* `retryResult = [valueReturned\|exceptionNotRetryable\|maxRetriesReached\|maxDurationReached]` - The reason that last attempt to call the method was not retried. +* `retryResult = [valueReturned\|exceptionNotRetryable\|maxRetriesReached\|maxDurationReached]`: The reason that last attempt to call the method was not retried | The number of times the retry logic was run. This value is always equal to once per method call. This metric is a `LongCounter`. | n/a | {mp-tel-2-0-ft-4-1} From 49ec0a364682b3622106cffbf2c52c868dd94e19 Mon Sep 17 00:00:00 2001 From: David Mueller <48686014+dmuelle@users.noreply.github.com> Date: Mon, 4 Nov 2024 12:19:06 -0500 Subject: [PATCH 06/81] Update modules/ROOT/pages/mptelemetry-metrics-list.adoc --- modules/ROOT/pages/mptelemetry-metrics-list.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/mptelemetry-metrics-list.adoc b/modules/ROOT/pages/mptelemetry-metrics-list.adoc index 95694cfa9..b333a1660 100644 --- a/modules/ROOT/pages/mptelemetry-metrics-list.adoc +++ b/modules/ROOT/pages/mptelemetry-metrics-list.adoc @@ -114,7 +114,7 @@ The **Version introduced** column specifies the minimum version of the feature t | {mp-tel-2-0} | ft.circuitbreaker.calls.total -| * `method`: The fully qualified method name, +| * `method`: The fully qualified method name * `circuitBreakerResult = [success\|failure\|circuitBreakerOpen]`: The result of the method call, as considered by the circuit breaker according to the rules in https://download.eclipse.org/microprofile/microprofile-fault-tolerance-4.0.2/microprofile-fault-tolerance-spec-4.0.2.html#circuit-breaker-success-failure[Configuring which exceptions are considered a failure] ** `success`: The method ran and was successful ** `failure`: The method ran and failed From 76cd90227f781c3fe2c7948546a1944058921ad7 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Tue, 5 Nov 2024 17:42:23 +0530 Subject: [PATCH 07/81] 7624-MicroProfile Rest Client 4.0 ID-1 7624-MicroProfile Rest Client 4.0 ID-1 #7624 --- modules/ROOT/pages/rest-clients.adoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/rest-clients.adoc b/modules/ROOT/pages/rest-clients.adoc index 743ec0a35..a04d1b24d 100644 --- a/modules/ROOT/pages/rest-clients.adoc +++ b/modules/ROOT/pages/rest-clients.adoc @@ -27,7 +27,9 @@ The template interface that you build with MicroProfile REST Client maps to the You can use MicroProfile REST Client with Open Liberty by enabling the feature:mpRestClient[display=MicroProfile Rest Client] feature in your `server.xml` file. For more information, see link:/guides/microprofile-rest-client.html[Consuming RESTful services with template interfaces] and link:/guides/microprofile-rest-client-async.html[Consuming RESTful services asynchronously with template interfaces]. -If you update your server from an earlier version of the feature:mpRestClient[display=MicroProfile REST Client] to version 3.0, changes in API behavior might require you to update your application code. For more information, see xref:reference:diff/mp-41-50-diff.adoc#rc[Differences between MicroProfile REST Client 3.0 and 2.0]. +If you update your server from a version of the feature:mpRestClient[display=MicroProfile REST Client] earlier than 3.0 to version 3.0 or higher, changes in API behavior might require you to update to your application code. For more information, see xref:reference:diff/mp-41-50-diff.adoc#rc[Differences between MicroProfile REST Client 3.0 and 2.0]. + +In addition, If you update your server to version 4.0 of the feature:mpRestClient[display=MicroProfile REST Client], see xref:reference:diff/mp-70-61-diff.adoc#rc[Differences between MicroProfile REST Client 4.0 and 3.0]. == Synchronous and asynchronous REST clients From 7403e57ec0fc0312bebd6eda6d93edf111f14e6d Mon Sep 17 00:00:00 2001 From: David Mueller Date: Wed, 6 Nov 2024 11:46:05 -0500 Subject: [PATCH 08/81] Update microprofile-telemetry.adoc --- .../ROOT/pages/microprofile-telemetry.adoc | 163 +++++++----------- 1 file changed, 64 insertions(+), 99 deletions(-) diff --git a/modules/ROOT/pages/microprofile-telemetry.adoc b/modules/ROOT/pages/microprofile-telemetry.adoc index 063010e30..4fffe8cbf 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -10,10 +10,9 @@ :seo-description: :page-layout: general-reference :page-type: general -= Enable observability with MicroProfile Telemetry += OpenTelemetry -With MicroProfile Telemetry 2.0 and later, you can manage logs, metrics, and traces in a standardized way by using the OpenTelemetry protocol. -MicroProfile Telemetry is based on the OpenTelemetry project, a collection of open source vendor-independent tools, APIs, and SDKs for creating and managing logs, metrics, and trace data. +The OpenTelemetry project is a collection of open source vendor-independent tools, APIs, and SDKs for creating and managing logs, metrics, and trace data. With Open Liberty and MicroProfile Telemetry 2.0 and later, you can manage logs, metrics, and traces in a standardized way by using the OpenTelemetry protocol. The following sections explain how to prepare your Open Liberty runtime and application code to use MicroProfile Telemetry. @@ -25,42 +24,66 @@ The following sections explain how to prepare your Open Liberty runtime and appl - <<#trouble, Troubleshooting>> [#global] -== Enabling MicroProfile Telemetry for Open Liberty +== Collecting and exporting logs, metrics, and traces with OpenTelemetry -To enable MicroProfile Telemetry in your Open Liberty runtime, you must add the MicroProfile Telemetry feature to your `server.xml` file and enable the OpenTelemetry SDK. OpenTelemetry is disabled by default. Depending on your needs, you can configure OpenTelemetry SDK instances at the runtime level or the application level. In most cases, runtime-level configuration is preferred as it includes both runtime-level telemetry and application-specific telemetry. +To use OpenTelemetry to collect and export logs, metrics, and traces in your Open Liberty runtime, you must add the MicroProfile Telemetry feature to your `server.xml` file and specify the `otel.sdk.disabled=false` system property in one of the valid configuration sources. Depending on whether you have a single application hosted on your Liberty runtime or multiple applications on the same runtime, you can specify this property at the runtime level or the application level. In most cases, runtime-level configuration is preferred as it includes both runtime-level telemetry and application-specific telemetry. The following table summarizes the benefits and use cases for each option. -Runtime-level configuration:: -Runtime-level configuration collects and emits telemetry from the runtime and all applications. As all telemetry from the runtime and applications is labeled as coming from the same service, this configuration works best when you are running a single application per Liberty runtime. -+ -You can configure your runtime instance in a few different sources, including your `jvm.options`, `bootstrap.properties`, or `server.env` files. You do not need to modify your application configuration to configure your runtime instance. +.OpenTelemetry configuration sources +[options="header"cols="3,3,6a,3a"] +|=== +|Use case| Configuration level | Description | Configuration sources -Application-level configuration:: -Configuring application-level OpenTelemetry instances gives you more fine-grained control over the data you collect for each application. This option also supports configuration compatibility with feature:mpTelemetry-1.1[display=MicroProfile Telemetry 1.1] and earlier, which created only application-level SDK instances. Runtime-level data is not collected or emitted by application-level instances. -+ -You can configure your application-level OpenTelemetry instances in the `microprofile-config.properties` file or the `appProperties` attribute for the config:application[] element in the `server.xml` file. When you create application-level instances, any system and server environment properties overwrite your application-level configuration. +| One application per Liberty runtime +| Runtime level +| Collects and emits telemetry from both the runtime and the application. +| * `bootstrap.properties` file +* `jvm.options` file +* `server.env` file -For more information about configuration sources and their ordinal values, see xref:external-configuration.adoc#default[Default configuration sources]. +| Multiple applications in the same Liberty runtime +| Application level +| Collects and emits telemetry for a single application and does not include runtime-level data. Provides fine-grained control over data collection for each application. +| * `microprofile-config.properties` file +* `appProperties` attribute for the config:application[] element in the `server.xml` file. +|=== -To enable MicroProfile Telemetry to collect and emit logs, metrics, and traces, complete the following steps. +=== Enabling OpenTelemetry for a Liberty runtime with a single application -. Enable the feature:mpTelemetry[display=MicroProfile Telemetry] feature in your `server.xml` file. To export metrics or logs, you must enable `mpTelemetry-2.0` or later. +When your Liberty runtime hosts only one application, you can enable Open Telemetry at the runtime level to collect and export logs, metrics, and traces for both the runtime and the application -. Set the `otel.sdk.disabled=false` property at the runtime level or the application level. +* Enable the feature:mpTelemetry[display=MicroProfile Telemetry] feature version 2.0 or later in the `featureManager` element of your `server.xml` file. + -At runtime initialization, if the `otel.sdk.disabled` property is set to `false`, the runtime-level OpenTelemetry SDK instance is created. If the runtime instance is not enabled and `otel.sdk.disabled=false` is specified at the application level, an application-level instance is created during application initialization. +[source,xml] +---- + + mpTelemetry-2.0 + ... + +---- -.. To enable the OpenTelemetry SDK at the runtime level, set the `otel.sdk.disabled=false` property as a system property, for example, in the `bootstrap.properties` file: +* Set `otel.sdk.disabled=false` as a runtime-level property, for example, in the `bootstrap.properties` file: + ---- otel.sdk.disabled=false -otel.service.name=RT1 ---- + +After you enable the MicroProfile Telemetry feature and set this system property, your runtime is ready to start collecting and exporting logs, metrics, and traces from the application and the runtime. For more information, see the individual sections for logs, metrics, and traces. + +=== Enabling OpenTelemetry for multiple applications in the same Liberty runtime + +When your Liberty runtime hosts multiple applications, you can enable OpenTelemetry to collect logs, metrics, and traces at the application level for each application. Although this option does not collect runtime-level telemetry, it gives you fine-grained control of the data you collect for each application. + +* Enable the feature:mpTelemetry[display=MicroProfile Telemetry] feature version 2.0 or later in the `featureManager` element of the `server.xml` file of each application that you want to collect telemetry for. + -The `otel.service.name` property creates a name for any telemetry that this OpenTelemetry SDK instance collects and emits. -+ -Alternatively, you can set runtime-level configuration properties by using environment variables in your `server.env` file. For any property definition, 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. +[source,xml] +---- + + mpTelemetry-2.0 + ... + +---- -.. To enable the OpenTelemetry SDK at the application level, set the `otel.sdk.disabled=false` property in the `microprofile-config.properties` file of each application. +* Set `otel.sdk.disabled=false` as an application-level property in the `microprofile-config.properties` file of each application. You can also set the `otel.service.name` property in each application to assign a service name to the telemetry data that is collected. This service name helps you identify the source of the data from each application when you send your data to monitoring and analytics tools. + Application 1 `microprofile-config.properties` file: + @@ -76,126 +99,68 @@ otel.sdk.disabled=false otel.service.name=A2 ---- + -This configuration creates all telemetry from Application 1 with the service name `A1`, and from Application 2 with the service name `A2`. It omits all runtime-level telemetry. +This configuration creates all telemetry from Application 1 with the service name `A1`, and from Application 2 with the service name `A2`. -.. Optionally, use a combination of application-level and runtime-level configuration. +* You can also use a combination of runtime-level and application-level configuration, so that some settings apply to all applications on the runtime, while others are specific to each application. Any configuration in the system properties and server environment variables takes precedence over application-level configuration. Therefore, you can enable OpenTelemetry and assign a service name individually for each application, but specify other settings at the runtime level to apply globally to all applications on the runtime. + -Regardless of whether a runtime instance is created, any configuration in the system properties and server environment variables takes precedence over application-level configuration. Therefore, you can configure shared application configuration at the runtime level and make application-specific changes in your application configuration. -+ -For example, you can set the OpenTelemetry exporter at the runtime-level in the `bootstrap.properties` file: +For example, you might want to collect a unique set of telemetry data for each application in the runtime, but have all applications share the same OpenTelemetry exporter. You can set the OpenTelemetry exporter at the runtime-level in the `bootstrap.properties` file: + ---- otel.logs.exporter=myExporter ---- + -Then, enable an application-level OpenTelemetry SDK instance in the `microprofile-config.properties` file for each application in the runtime: +Then, enable application-level telemetry and specify a service name in the `microprofile-config.properties` file for each application in the runtime: + ---- otel.sdk.disabled=false otel.service.name= ---- + -This configuration enables an application-level SDK instance and custom service name for each configured application, while all applications in the runtime use the `myExporter` OpenTelemetry exporter. +This configuration enables an application-level telemetry with a unique service name for each application, while all applications in the runtime use the `myExporter` OpenTelemetry exporter. + +After you enable the MicroProfile Telemetry feature and set the `otel.sdk.disabled=false` property for each application on the runtime, your applications are ready to start collecting and exporting logs, metrics, and traces. For more information, see the individual sections for logs, metrics, and traces. +== OpenTelemetry settings and configuration [#traces] -== Configuring Open Liberty to use MicroProfile Telemetry to collect traces +== Trace 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 about what happens during a transaction. -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]. - -. Enable the MicroProfile Telemetry feature and specify a MicroProfile Config property or environment variable to enable the OpenTelemetry SDK. -+ -For more information, see <<#global,Enabling MicroProfile Telemetry for Open Liberty>> +When you enable OpenTelemetry for Open Liberty, Jakarta RESTful Web Services and JAX-RS applications are instrumented for trace by default. Spans are automatically generated for incoming HTTP requests, including static files, servlets, and JSPs. These spans are automatically exported according to the configured OpenTelemetry settings. -. Configure a trace storage system by specifying an exporter definition that includes the exporter type and endpoint. -+ -For example, to use a Jaeger server or to forward data to an OpenTelemetry collector, 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 the following example to your `bootstrap.properties` file: -+ -[source,properties] ----- -otel.sdk.disabled=false -otel.traces.exporter=zipkin -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 OpenTelemetry API. Alternatively, you can attach the OpenTelemetry Java agent to any Java 8+ application. For more information about these options, see xref:telemetry-trace.adoc#t[Code instrumentation for MicroProfile Telemetry tracing]. -. 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=console ----- -+ -For more information about the available properties, see xref:reference:microprofile-config-properties.adoc#telemetry[MicroProfile Config properties: MicroProfile Telemetry]. +By default, OpenTelemetry exports traces to the `otlp` exporter at the `http://localhost:4317` endpoint. You can configure an alternative trace storage system by setting MicroProfile Config properties. -. Depending on how you choose to instrument your application code for tracing, further configuration might be required. -+ -For more information, see xref:telemetry-trace.adoc#t[Code instrumentation for MicroProfile Telemetry tracing]. [#logs] -== Configuring Open Liberty to use MicroProfile Telemetry to collect logs +== Logs -To enable MicroProfile Telemetry to collect and export logs in your Open Liberty runtime, add the MicroProfile Telemetry feature 2.0 or later to your `server.xml` file and enable the OpenTelemetry SDK. Optionally, you can specify MicroProfile Config properties to configure how MicroProfile Telemetry collects and exports logs. +When you enable OpenTelemetry for Open Liberty, by default, logs are collected from the `message` log or the application or runtime and exported to the `otlp` exporter. -. Enable the MicroProfile Telemetry feature 2.0 or later and specify a MicroProfile Config property or environment variable to enable the OpenTelemetry SDK. -+ -For more information, see <<#global,Enabling MicroProfile Telemetry for Open Liberty>>. - -. Optionally, configure the log sources that MicroProfile Telemetry collects and where the logs are exported. -+ -You can configure how MicroProfile Telemetry collects and exports logs by specifying configuration properties in any of the xref:external-configuration.adoc#default[config sources that are available to MicroProfile Config], or by specifying environment variables. - -.. Enable MicroProfile Telemetry to collect logs from different sources in the Open Liberty runtime environment. -+ -Configure the `source` attribute for the `mpTelemetry` element with a comma-separated list of log sources: +* To specify one or more alternative log sources, configure the `source` attribute for the `mpTelemetry` element in your `server.xml` file with a comma-separated list of log sources: + [source,xml] ---- ---- + -The `mpTelemetry` configuration element is optional. If you do not specify it, or if you do not include the `source` attribute, the default configuration source is `message`. For more information, see feature:mpTelemetry-2.0[display=Collect logs from a specified source]. +For information about Liberty message event fields for MicroProfile Telemetry, see xref:mptel-log-events-list.adoc[MicroProfile Telemetry log events reference list]. -.. Change the log exporter that MicroProfile Telemetry uses. -+ -By default, all OpenTelemetry data is exported to link:https://opentelemetry.io/docs/languages/java/exporters/#otlp[OTLP]. You can change this setting by specifying the `otel.logs.exporter` property. +* To change the log exporter that MicroProfile Telemetry uses, specifying the `otel.logs.exporter` property. + For example, to send logs to the `console.log` file for debugging purposes, you might add configuration similar to the following example to your `bootstrap.properties` file: + [source,properties] ---- -otel.sdk.disabled=false otel.logs.exporter=console ---- + If you set this property to `console`, all the logs are exported to standard out (`stdout`) or the `console.log` file. The `console.log` file contains the usual logs, along with duplicate OpenTelemetry-mapped logs. This setting is only for debugging purposes because the `console.log` file does not roll over and might affect performance if it gets too large. If you set this property to `none`, no logs are exported. + -.. Configure MicroProfile Telemetry to use the OpenTelemetry Batch LogRecord Processor. -+ -By default, the `SimpleLogRecordProcessor` is enabled, so the records are sent immediately. However, if you want to send the records in batches, you can also configure the following logging-specific Batch LogRecord Processor properties or environment variables: -+ -* `otel.blrp.schedule.delay` or `OTEL_BLRP_SCHEDULE_DELAY` -* `otel.blrp.max.queue.size` or `OTEL_BLRP_MAX_QUEUE_SIZE` -* `otel.blrp.max.export.batch.size` or `OTEL_BLRP_MAX_EXPORT_BATCH_SIZE` -* `otel.blrp.export.timeout` or `OTEL_BLRP_EXPORT_TIMEOUT` -+ -For more information, see the OpenTelemetry link:https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#batch-logrecord-processor[Batch LogRecord Processor] documentation. -For more information about the available properties, see xref:reference:microprofile-config-properties.adoc#telemetry[MicroProfile Config properties: MicroProfile Telemetry]. -For information about Liberty message event fields for MicroProfile Telemetry, see xref:mptel-log-events-list.adoc[MicroProfile Telemetry log events reference list]. [#metrics] == Configuring Open Liberty to use MicroProfile Telemetry to collect metrics From f018476e6cd2d990a58a0a9c19319c9513b83b9f Mon Sep 17 00:00:00 2001 From: David Mueller Date: Wed, 6 Nov 2024 16:18:27 -0500 Subject: [PATCH 09/81] new drafts #7655 --- .../ROOT/pages/microprofile-telemetry.adoc | 109 ++---------------- .../ROOT/pages/telemetry-troubleshooting.adoc | 43 +++++++ 2 files changed, 54 insertions(+), 98 deletions(-) create mode 100644 modules/ROOT/pages/telemetry-troubleshooting.adoc diff --git a/modules/ROOT/pages/microprofile-telemetry.adoc b/modules/ROOT/pages/microprofile-telemetry.adoc index 4fffe8cbf..747cfee95 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -12,16 +12,8 @@ :page-type: general = OpenTelemetry -The OpenTelemetry project is a collection of open source vendor-independent tools, APIs, and SDKs for creating and managing logs, metrics, and trace data. With Open Liberty and MicroProfile Telemetry 2.0 and later, you can manage logs, metrics, and traces in a standardized way by using the OpenTelemetry protocol. +The OpenTelemetry project is a collection of open source vendor-independent tools, APIs, and SDKs for creating and managing logs, metrics, and trace data. With Open Liberty and MicroProfile Telemetry 2.0 and later, you can manage this data in a standardized way by using the OpenTelemetry protocol. -The following sections explain how to prepare your Open Liberty runtime and application code to use MicroProfile Telemetry. - - -- <<#global, Enabling MicroProfile Telemetry for Open Liberty>> -- <<#traces, Collecting traces>> -- <<#logs, Collecting logs>> -- <<#metrics, Collecting metrics>> -- <<#trouble, Troubleshooting>> [#global] == Collecting and exporting logs, metrics, and traces with OpenTelemetry @@ -47,7 +39,7 @@ To use OpenTelemetry to collect and export logs, metrics, and traces in your Ope * `appProperties` attribute for the config:application[] element in the `server.xml` file. |=== -=== Enabling OpenTelemetry for a Liberty runtime with a single application +=== Enabling OpenTelemetry for an Open Liberty runtime with a single application When your Liberty runtime hosts only one application, you can enable Open Telemetry at the runtime level to collect and export logs, metrics, and traces for both the runtime and the application @@ -69,7 +61,7 @@ otel.sdk.disabled=false After you enable the MicroProfile Telemetry feature and set this system property, your runtime is ready to start collecting and exporting logs, metrics, and traces from the application and the runtime. For more information, see the individual sections for logs, metrics, and traces. -=== Enabling OpenTelemetry for multiple applications in the same Liberty runtime +=== Enabling OpenTelemetry for multiple applications in the same Open Liberty runtime When your Liberty runtime hosts multiple applications, you can enable OpenTelemetry to collect logs, metrics, and traces at the application level for each application. Although this option does not collect runtime-level telemetry, it gives you fine-grained control of the data you collect for each application. @@ -101,7 +93,9 @@ otel.service.name=A2 + This configuration creates all telemetry from Application 1 with the service name `A1`, and from Application 2 with the service name `A2`. -* You can also use a combination of runtime-level and application-level configuration, so that some settings apply to all applications on the runtime, while others are specific to each application. Any configuration in the system properties and server environment variables takes precedence over application-level configuration. Therefore, you can enable OpenTelemetry and assign a service name individually for each application, but specify other settings at the runtime level to apply globally to all applications on the runtime. +* You can also use a combination of runtime-level and application-level configuration, so that some settings apply to all applications on the runtime, while others are specific to each application. This strategy can save you from having to duplicate general configuration settings in multiple applications on the same runtime. + +Any configuration in the system properties and server environment variables takes precedence over application-level configuration. Therefore, you can enable OpenTelemetry and assign a service name individually for each application, but specify other settings at the runtime level to apply globally to all applications on the runtime. + For example, you might want to collect a unique set of telemetry data for each application in the runtime, but have all applications share the same OpenTelemetry exporter. You can set the OpenTelemetry exporter at the runtime-level in the `bootstrap.properties` file: + @@ -131,104 +125,23 @@ When you enable OpenTelemetry for Open Liberty, Jakarta RESTful Web Services and 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 OpenTelemetry API. Alternatively, you can attach the OpenTelemetry Java agent to any Java 8+ application. For more information about these options, see xref:telemetry-trace.adoc#t[Code instrumentation for MicroProfile Telemetry tracing]. -By default, OpenTelemetry exports traces to the `otlp` exporter at the `http://localhost:4317` endpoint. You can configure an alternative trace storage system by setting MicroProfile Config properties. - - [#logs] == Logs -When you enable OpenTelemetry for Open Liberty, by default, logs are collected from the `message` log or the application or runtime and exported to the `otlp` exporter. - -* To specify one or more alternative log sources, configure the `source` attribute for the `mpTelemetry` element in your `server.xml` file with a comma-separated list of log sources: -+ -[source,xml] ----- - ----- -+ -For information about Liberty message event fields for MicroProfile Telemetry, see xref:mptel-log-events-list.adoc[MicroProfile Telemetry log events reference list]. +OpenTelemetry automatically collects any logs that are sent to the `java.util.logging` API. Any messages that are logged at a `java.util.logging.Level` log level of `INFO` and above are considered messages. Levels below `INFO` are considered trace. By default, OpenTelemetry automatically collects messages, but you can configure the sources that it collects from in your `server.xml` file. For more information, see link:/docs/latest/reference/feature/mpTelemetry-2.0.html#_collect_logs_from_a_specified_source[Collect logs from a specified source]. -* To change the log exporter that MicroProfile Telemetry uses, specifying the `otel.logs.exporter` property. -+ -For example, to send logs to the `console.log` file for debugging purposes, you might add configuration similar to the following example to your `bootstrap.properties` file: -+ -[source,properties] ----- -otel.logs.exporter=console ----- -+ -If you set this property to `console`, all the logs are exported to standard out (`stdout`) or the `console.log` file. The `console.log` file contains the usual logs, along with duplicate OpenTelemetry-mapped logs. This setting is only for debugging purposes because the `console.log` file does not roll over and might affect performance if it gets too large. If you set this property to `none`, no logs are exported. -+ +For information about Liberty message event fields for OpenTelemetry, see xref:mptel-log-events-list.adoc[MicroProfile Telemetry log events reference list]. +By default, the OpenTelemetry Simple logRecord Processor is enabled, so the records are sent immediately. However, if you want to send the records in batches, you can also configure the logging-specific Batch LogRecord Processor properties. [#metrics] -== Configuring Open Liberty to use MicroProfile Telemetry to collect metrics - -To enable MicroProfile Telemetry to collect and export metrics in your Open Liberty runtime, add the MicroProfile Telemetry 2.0 feature to your `server.xml` file and enable the OpenTelemetry SDK. Optionally, you can specify MicroProfile Config properties to configure how MicroProfile Telemetry collects and exports metrics. - -. Enable the MicroProfile Telemetry feature 2.0 or later and specify a MicroProfile Config property or environment variable to enable the OpenTelemetry SDK. -+ -For more information, see <<#global,Enabling MicroProfile Telemetry for Open Liberty>> - -. Optionally, change the log exporter that MicroProfile Telemetry uses. -+ -By default, all OpenTelemetry data is exported to link:https://opentelemetry.io/docs/languages/java/exporters/#otlp[OTLP]. You can change this setting by specifying the `otel.metrics.exporter` property or the `OTEL_METRICS_EXPORTER` environment variable. -+ -For example, to export metrics to Open Liberty log files, specify the following property: -+ ----- -otel.metrics.exporter=console ----- - -. Optionally, change the metric export interval. -+ -By default, metric data is exported at an interval of 60 seconds. To modify the export interval, specify the `otel.metric.export.interval` property or the `OTEL_METRIC_EXPORT_INTERVAL` environment variable. Specify the value in milliseconds. For more information, see link:https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#periodic-exporting-metricreader[Periodic exporter MetricReader] in the OpenTelemetry documentation. +== Metrics -Depending on how you choose to instrument your application code for metrics, further configuration might be required. For information about defining your own metrics, see xref:custom-mptelemetry-metrics.adoc[Define custom MicroProfile Telemetry metrics]. +By default, OpenTelemetry exports metric data at an interval of 60 seconds. You can modify the export interval and other default settings by using MicroProfile config properties. For a list of metrics that are available for Open Liberty when you enable the MicroProfile Telemetry feature 2.0 or later, see xref:mptelemetry-metrics-list.adoc[MicroProfile Telemetry metrics reference list]. -[#trouble] -== 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. -+ -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 MicroProfile Telemetry include calling a method that is annotated with `@WithSpan` or making a request with a JAX-RS Client or MP Rest Client. - -You receive either of the CWMOT5006W or CWMOT5007 warning message that conflicting configuration is specified for otel.sdk.disabled:: - -Specify the settings to enable or disable OpenTelemetry instances by using either environment variables or MicroProfile Config sources, but not both. If you see these warnings, the other MicroProfile Config source to look at is 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[] -//// == See also diff --git a/modules/ROOT/pages/telemetry-troubleshooting.adoc b/modules/ROOT/pages/telemetry-troubleshooting.adoc new file mode 100644 index 000000000..5fa36ea47 --- /dev/null +++ b/modules/ROOT/pages/telemetry-troubleshooting.adoc @@ -0,0 +1,43 @@ +// Copyright (c) 2022 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: +:seo-description: +:page-layout: general-reference +:page-type: general += Troubleshooting OpenTelemetry + +The following information can help you determine the cause of common problems and error messages that are associated with OpenTelemetry logs, metrics, and tracing. + +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 MicroProfile Telemetry include calling a method that is annotated with `@WithSpan` or making a request with a JAX-RS Client or MP Rest Client. + +You receive either of the CWMOT5006W or CWMOT5007 warning message that conflicting configuration is specified for otel.sdk.disabled:: + +Specify the settings to enable or disable OpenTelemetry instances by using either environment variables or MicroProfile Config sources, but not both. If you see these warnings, the other MicroProfile Config source to look at is your `server.xml` file. From a16b237cd1e192278dbd8bbe898aa58b61b5743f Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Fri, 8 Nov 2024 16:01:41 +0530 Subject: [PATCH 10/81] 7654-Documentation-MicroProfile-OpenAPI-4.0-1 7654-Documentation-MicroProfile-OpenAPI-4.0-1 #7654 --- modules/ROOT/pages/documentation-openapi.adoc | 130 ++++++++++++++---- .../pages/feature/mpOpenAPI-2.0/examples.adoc | 50 +++---- .../pages/feature/mpOpenAPI-3.0/examples.adoc | 48 +++---- .../pages/feature/mpOpenAPI-3.1/examples.adoc | 50 +++---- .../pages/feature/mpOpenAPI-4.0/examples.adoc | 34 +++++ 5 files changed, 214 insertions(+), 98 deletions(-) create mode 100644 modules/reference/pages/feature/mpOpenAPI-4.0/examples.adoc diff --git a/modules/ROOT/pages/documentation-openapi.adoc b/modules/ROOT/pages/documentation-openapi.adoc index f52b2829e..12f6ca9fe 100644 --- a/modules/ROOT/pages/documentation-openapi.adoc +++ b/modules/ROOT/pages/documentation-openapi.adoc @@ -127,33 +127,127 @@ You can augment manually created API documents by adding annotations to the code For more information, see https://openliberty.io/guides/microprofile-openapi.html#using-pregenerated-openapi-documents[Using pregenerated OpenAPI documents]. +== Supported OpenAPI versions + +The MicroProfile OpenAPI feature generates structured documentation based on the OpenAPI specification. Each new version of the OpenAPI specification updates the documentation format, and different versions of MicroProfile OpenAPI support different OpenAPI specification versions. + +|=== +|Feature | OpenAPI versions supported + +|`mpOpenAPI-4.0` +| 3.1, 3.0 + +|`mpOpenAPI-3.1` +| 3.0 + +|`mpOpenAPI-3.0` +| 3.0 + +|`mpOpenAPI-2.0` +| 3.0 + +|`mpOpenAPI-1.1` +| 3.0 + +|`mpOpenAPI-1.0` +| 3.0 +|=== + +If you are using a feature that supports more than one version of the OpenAPI specification, you can switch between versions with configuration. You might need to do this if you or your end users use tools or libraries that don't yet support a newer version of the OpenAPI specification. + +For example, you can select OpenAPI v3.0 when using `mpOpenAPI-4.0`. + +[source,xml] +---- + +---- + [#multi-module] == Multiple application and multi-module application support with MicroProfile OpenAPI -By default, OpenAPI documentation is generated for only the first web module of the first application that is deployed on the server. The MicroProfile OpenAPI feature, version 2.0 and later, provides configuration properties to select which applications and web modules OpenAPI documentation is generated for. If more than one web module or application is specified, an OpenAPI document is generated for each module or application and then they are merged to create a single OpenAPI document. A property is also provided to set the `info` section of the final merged OpenAPI document. +When multiple applications, or applications with more than one web module are deployed to the same Open Liberty server, the behavior differs between MicroProfile OpenAPI feature versions. -For example, to include all the applications in your deployment in a single merged OpenAPI document, you can define the following MicroProfile Config property as a variable in your `server.xml` file. +|=== +|Feature |Behavior + +|`mpOpenAPI-4.0` +|By default, all deployed applications and modules are included in the structured documentation. This can changed through configuration. + +|`mpOpenAPI-2.0` to `mpOpenAPI-3.1` +|By default, only the first web module of the first application deployed is included in the structured documentation. This can be changed through configuration. + +|`mpOpenAPI-1.0` to `mpOpenAPI-1.1` +|Only the first web module of the first application deployed is included in the structured documentation. This cannot be changed. +|=== + +For MicroProfile OpenAPI 2.0 and later, you can control the applications and modules that are included in the structured documentation by using the ``, ``, ``, and `` elements within the `` configuration element. + +For example, to include all deployed applications and modules in the generated structured documentation when using `mpOpenAPI-2.0`, add the following configuration to your `server.xml` file. [source,xml] ---- - + + all + ---- +For example, to include all deployed applications and modules except the `admin` module of `application1`, add the following configuration to your `server.xml` file. -The following table lists xref:external-configuration.adoc[MicroProfile Config] properties that can be specified to configure which modules or applications are included in the generated OpenAPI documentation. These properties are available when you enable the MicroProfile OpenAPI feature, version 2.0 and later. Alternatively, you can specify the feature:microProfile[display=MicroProfile] convenience feature, version 4.0 or later, which automatically enables the full set of MicroProfile features. For configuration examples, see the feature:mpOpenAPI[display=MicroProfile OpenAPI] feature. +[source,xml] +---- + + all + application1/admin + +---- + +==== Key Points: + +- The application name is determined by the value of the `name` attribute when the application is deployed in `server.xml` using ``, ``, or ``. For example: + +[source,xml] +---- + +---- + +If the application is deployed in the `dropins` directory or if the `name` attribute is not specified, the name defaults to the archive filename with the extension removed. + +- The module name is specified in the web module's `web.xml` file. If there is no `web.xml` file or if it does not specify a name, the module name defaults to the filename with the extension removed. + +You can also override the `info` section of the OpenAPI document using the following configuration: + +[source,xml] +---- + + + +---- + +This override may be useful when documenting multiple modules or applications. Without it, the `info` section would be replaced with a standard one indicating that documentation from several modules was merged. + + +=== Configuring multiple application and multi-module support using MicroProfile Config + +You can configure the modules and applications to be included in the structured documentation by using MicroProfile Config, with the following limitations: + +- If conflicting configuration is found in the `server.xml` file, the MicroProfile Config settings are ignored. + +- The configuration properties must be set by using a configuration source that is not specific to an application. For example, you can use system properties, environment variables, or `` elements in the `server.xml` file. + +The following table lists the MicroProfile Config properties that can be specified to configure which modules or applications are included in the generated OpenAPI documentation. .Configuration properties for multiple application and multi-module application support -[%header,cols="3,6,2,6a"] +[%header,cols="3,6,6a"] |=== |Property name |Description -|Default value |Valid values |`mp.openapi.extensions.liberty.merged.include` |This property specifies which modules or applications are included in the generated OpenAPI documentation. -|`first` | * `all` + This value includes all modules and applications in a deployment. @@ -163,7 +257,6 @@ This value includes only the first web module of the first application deployed. |`mp.openapi.extensions.liberty.merged.exclude` |This property overrides the `mp.openapi.extensions.liberty.merged.include` property to specify which applications or web modules are excluded from the generated OpenAPI documentation. -|`none` | * `none` + This value excludes no applications or web modules. @@ -171,30 +264,17 @@ This value excludes no applications or web modules. |`mp.openapi.extensions.liberty.merged.info` |This property sets the `info` section of the final Open API document. If it is set, the `info` section in the final OpenAPI document is replaced with the value of the property. This replacement is made after any merging is completed. -|N/A |The value must be https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#infoObject[a valid OpenAPI info section] in JSON format. |=== -=== Resolution of OpenAPI document merging conflicts - -When OpenAPI documentation from multiple modules is merged into a single document, Open Liberty applies the following rules to resolve potential conflicts between the OpenAPI documents that are being merged. - -- If all server URLs end with the context root, the context root is removed from each server URL and added as a prefix to each path. If no servers exist in a document, the context root is added as a prefix to each path. If the same path is then declared in more than one document, a warning is logged and all but one of the clashing documents is excluded from the merged documentation. - -- If the same extension name is declared with different values at the top level of more than one document, a warning is logged. All but one of the clashing documents are excluded from the merged documentation. - -- If the top-level `servers` section is not identical across all documents, each server is removed from the top level and copied under the paths that it applies to. - -- Component names are made unique by adding a number to the end of them where necessary. References to the component name are updated. - -- Operation IDs are made unique by adding a number to the end of them where necessary. References to the operation ID are updated. +- The default behavior varies between versions and has been explained earlier. -- If the `info` section is not identical across all documents, it is replaced by a standard info section that says that the documentation from several modules was merged. +==== Key Points: -- If the top-level `security` section is not the same across all documents, the security requirements are copied under each operation that they apply to. +- When you configure support for multiple applications and multi-module environments by using MicroProfile Config, the application name is taken from the application's deployment descriptor (application.xml or web.xml). If there is no deployment descriptor or if it does not specify a name, the name defaults to the application archive filename with the extension removed. -- If the `externalDocs` section is not the same across all documents, it is removed from the final document. +- The module name follows the same rules as described for the server.xml configuration. == See also diff --git a/modules/reference/pages/feature/mpOpenAPI-2.0/examples.adoc b/modules/reference/pages/feature/mpOpenAPI-2.0/examples.adoc index 222ae3fed..7fb328ef1 100644 --- a/modules/reference/pages/feature/mpOpenAPI-2.0/examples.adoc +++ b/modules/reference/pages/feature/mpOpenAPI-2.0/examples.adoc @@ -5,33 +5,35 @@ // This example only applies to 2.0 forward, and so the file and directory must be manually copied and applied to any new versions. Copy the directory and file and change the directory name to reflect the new feature version, for example `mpOpenAPI-3.2`. -You can specify xref:ROOT:external-configuration.adoc[MicroProfile Config] properties to configure the Microprofile OpenAPI feature to merge OpenAPI documentation for multiple applications or modules into a single document. +By default, only the first module of the first deployed application is included in the OpenAPI documentation. However, you can configure the MicroProfile OpenAPI feature to merge the OpenAPI documentation for multiple applications or modules into a single document. -In the following `microprofile-config.properties` file example, an OpenAPI document is configured for the `sample_app` application, which consists of an `EAR` file with five web modules. +For example, the following configuration is for the `sample_app` application, which consists of an `EAR` file containing five web modules. -[source,java] +[source,xml] ---- -mp.openapi.extensions.liberty.merged.include=all -mp.openapi.extensions.liberty.merged.exclude=sample_app/module-3,sample_app/module-5 -mp.openapi.extensions.liberty.merged.info= -{ - "title": "A multi-module sample application", - "description": "This is a sample application.", - "termsOfService": "http://example.com/sample_app/terms", - "contact": { - "name": "API Support", - "url": "http://www.example.com/sample_app/support", - "email": "sample_app_support@example.com" - }, - "license": { - "name": "License 2.0", - "url": "https://www.example.org/licenses/LICENSE-2.0.html" - }, - "version": "2.0.1" -} + + all + sample_app/module-3 + sample_app/module-5 + + ---- -* The `mp.openapi.extensions.liberty.merged.include` property specifies that all five modules are included in the final OpenAPI document. -* The `mp.openapi.extensions.liberty.merged.exclude` overrides the `mp.openapi.extensions.liberty.merged.include` property to exclude the `module-3` and `module-5` web modules. -* 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. + +- The `` element specifies that all applications are included in the final OpenAPI document. + +- The `` elements exclude the `module-3` and `module-5` web modules. + +- The `` element 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] + + diff --git a/modules/reference/pages/feature/mpOpenAPI-3.0/examples.adoc b/modules/reference/pages/feature/mpOpenAPI-3.0/examples.adoc index 222ae3fed..1de816747 100644 --- a/modules/reference/pages/feature/mpOpenAPI-3.0/examples.adoc +++ b/modules/reference/pages/feature/mpOpenAPI-3.0/examples.adoc @@ -5,33 +5,33 @@ // This example only applies to 2.0 forward, and so the file and directory must be manually copied and applied to any new versions. Copy the directory and file and change the directory name to reflect the new feature version, for example `mpOpenAPI-3.2`. -You can specify xref:ROOT:external-configuration.adoc[MicroProfile Config] properties to configure the Microprofile OpenAPI feature to merge OpenAPI documentation for multiple applications or modules into a single document. +By default, only the first module of the first deployed application is included in the OpenAPI documentation. However, you can configure the MicroProfile OpenAPI feature to merge the OpenAPI documentation for multiple applications or modules into a single document. -In the following `microprofile-config.properties` file example, an OpenAPI document is configured for the `sample_app` application, which consists of an `EAR` file with five web modules. +For example, the following configuration is for the `sample_app` application, which consists of an `EAR` file containing five web modules. -[source,java] +[source,xml] ---- -mp.openapi.extensions.liberty.merged.include=all -mp.openapi.extensions.liberty.merged.exclude=sample_app/module-3,sample_app/module-5 -mp.openapi.extensions.liberty.merged.info= -{ - "title": "A multi-module sample application", - "description": "This is a sample application.", - "termsOfService": "http://example.com/sample_app/terms", - "contact": { - "name": "API Support", - "url": "http://www.example.com/sample_app/support", - "email": "sample_app_support@example.com" - }, - "license": { - "name": "License 2.0", - "url": "https://www.example.org/licenses/LICENSE-2.0.html" - }, - "version": "2.0.1" -} + + all + sample_app/module-3 + sample_app/module-5 + + ---- -* The `mp.openapi.extensions.liberty.merged.include` property specifies that all five modules are included in the final OpenAPI document. -* The `mp.openapi.extensions.liberty.merged.exclude` overrides the `mp.openapi.extensions.liberty.merged.include` property to exclude the `module-3` and `module-5` web modules. -* 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. + +- The `` element specifies that all applications are included in the final OpenAPI document. + +- The `` elements exclude the `module-3` and `module-5` web modules. + +- The `` element 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] diff --git a/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc b/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc index 222ae3fed..a889eb6ed 100644 --- a/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc +++ b/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc @@ -5,33 +5,33 @@ // This example only applies to 2.0 forward, and so the file and directory must be manually copied and applied to any new versions. Copy the directory and file and change the directory name to reflect the new feature version, for example `mpOpenAPI-3.2`. -You can specify xref:ROOT:external-configuration.adoc[MicroProfile Config] properties to configure the Microprofile OpenAPI feature to merge OpenAPI documentation for multiple applications or modules into a single document. +By default, only the first module of the first deployed application is included in the OpenAPI documentation. However, you can configure the MicroProfile OpenAPI feature to merge the OpenAPI documentation for multiple applications or modules into a single document. -In the following `microprofile-config.properties` file example, an OpenAPI document is configured for the `sample_app` application, which consists of an `EAR` file with five web modules. +For example, the following configuration is for the `sample_app` application, which consists of an `EAR` file containing five web modules. -[source,java] +[source,xml] ---- -mp.openapi.extensions.liberty.merged.include=all -mp.openapi.extensions.liberty.merged.exclude=sample_app/module-3,sample_app/module-5 -mp.openapi.extensions.liberty.merged.info= -{ - "title": "A multi-module sample application", - "description": "This is a sample application.", - "termsOfService": "http://example.com/sample_app/terms", - "contact": { - "name": "API Support", - "url": "http://www.example.com/sample_app/support", - "email": "sample_app_support@example.com" - }, - "license": { - "name": "License 2.0", - "url": "https://www.example.org/licenses/LICENSE-2.0.html" - }, - "version": "2.0.1" -} + + all + sample_app/module-3 + sample_app/module-5 + + ---- -* The `mp.openapi.extensions.liberty.merged.include` property specifies that all five modules are included in the final OpenAPI document. -* The `mp.openapi.extensions.liberty.merged.exclude` overrides the `mp.openapi.extensions.liberty.merged.include` property to exclude the `module-3` and `module-5` web modules. -* 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] +- The `` element specifies that all applications are included in the final OpenAPI document. + +- The `` elements exclude the `module-3` and `module-5` web modules. + +- The `` element 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] \ No newline at end of file diff --git a/modules/reference/pages/feature/mpOpenAPI-4.0/examples.adoc b/modules/reference/pages/feature/mpOpenAPI-4.0/examples.adoc new file mode 100644 index 000000000..67154cd09 --- /dev/null +++ b/modules/reference/pages/feature/mpOpenAPI-4.0/examples.adoc @@ -0,0 +1,34 @@ + +== Examples + +=== Configure OpenAPI documentation for a multi-module application + +// This example only applies to 2.0 forward, and so the file and directory must be manually copied and applied to any new versions. Copy the directory and file and change the directory name to reflect the new feature version, for example `mpOpenAPI-3.2`. + +By default, all deployed applications and modules are included in the OpenAPI documentation. However, you can configure which applications and modules should be included. + +For example, the following configuration is for the `sample_app` application, which consists of an `EAR` file containing five web modules. + +[source,xml] +---- + + sample_app/module-3 + sample_app/module-5 + + +---- + +- The `` elements exclude the `module-3` and `module-5` web modules. + +- The `` element 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] \ No newline at end of file From bf510cb8364dc9868ef0f30fe303844ace061faf Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Fri, 8 Nov 2024 19:58:02 +0530 Subject: [PATCH 11/81] 7624-MicroProfile Rest Client 4.0 ID-2 7624-MicroProfile Rest Client 4.0 ID-2 #7624 --- modules/ROOT/pages/rest-clients.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/rest-clients.adoc b/modules/ROOT/pages/rest-clients.adoc index a04d1b24d..5c678c552 100644 --- a/modules/ROOT/pages/rest-clients.adoc +++ b/modules/ROOT/pages/rest-clients.adoc @@ -29,7 +29,7 @@ You can use MicroProfile REST Client with Open Liberty by enabling the feature:m If you update your server from a version of the feature:mpRestClient[display=MicroProfile REST Client] earlier than 3.0 to version 3.0 or higher, changes in API behavior might require you to update to your application code. For more information, see xref:reference:diff/mp-41-50-diff.adoc#rc[Differences between MicroProfile REST Client 3.0 and 2.0]. -In addition, If you update your server to version 4.0 of the feature:mpRestClient[display=MicroProfile REST Client], see xref:reference:diff/mp-70-61-diff.adoc#rc[Differences between MicroProfile REST Client 4.0 and 3.0]. +In addition, If you update your server to version 4.0 of the feature:mpRestClient[display=MicroProfile REST Client], see xref:reference:diff/mp-61-70-diff.adoc#rc[Differences between MicroProfile REST Client 4.0 and 3.0]. == Synchronous and asynchronous REST clients From 1e9ee351606aac8405a408bd49e2850ff118886a Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Fri, 8 Nov 2024 22:08:52 +0530 Subject: [PATCH 12/81] 7610-MicroProfile 7.0 ID 7610-MicroProfile 7.0 ID #7610 --- modules/ROOT/pages/mptel-log-events-list.adoc | 10 +- .../reference/pages/diff/mp-61-70-diff.adoc | 303 ++++++++++++++++++ 2 files changed, 310 insertions(+), 3 deletions(-) create mode 100644 modules/reference/pages/diff/mp-61-70-diff.adoc diff --git a/modules/ROOT/pages/mptel-log-events-list.adoc b/modules/ROOT/pages/mptel-log-events-list.adoc index 6778871dc..964c0d5b1 100644 --- a/modules/ROOT/pages/mptel-log-events-list.adoc +++ b/modules/ROOT/pages/mptel-log-events-list.adoc @@ -18,12 +18,13 @@ For more information, see xref:microprofile-telemetry.adoc[Enable observability MicroProfile Telemetry can collect the following types of events: -* <> -* <> -* <> +* <<#me, Message events>> +* <<#te, Trace events>> +* <<#ffdce, FFDC events>> For information about trace log detail levels and how Open Liberty settings map to OpenTelemetry severity numbers, see <>. +[#me] == Message events The following table provides the fields for Liberty message events, a description for each field, and the mapping to the OpenTelemetry logs data model and Java agent: @@ -66,6 +67,8 @@ Attributes: io.openliberty.ext.app_name="badapp" ---- + +[#te] == Trace events The following table provides the fields for Liberty trace events, a description for each field, and the mapping to the OpenTelemetry logs data model and Java agent: @@ -107,6 +110,7 @@ Attributes: io.openliberty.ext.app_name="testapp" ---- +[#ffdce] == FFDC events The following table provides the fields for the first failure data capture (FFDC) events, a description for each fiel, and the mapping to the OpenTelemetry logs data model: diff --git a/modules/reference/pages/diff/mp-61-70-diff.adoc b/modules/reference/pages/diff/mp-61-70-diff.adoc new file mode 100644 index 000000000..c91b01f3a --- /dev/null +++ b/modules/reference/pages/diff/mp-61-70-diff.adoc @@ -0,0 +1,303 @@ +// Copyright (c) 2024 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 7.0 is a major release. If you are updating your application from using MicroProfile 6.1 features to MicroProfile 7.0 features, the 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 7.0 is a major release. It introduces updated MicroProfile specifications, including MicroProfile Telemetry 2.0, MicroProfile Rest Client 4.0, MicroProfile OpenAPI 4.0, and MicroProfile Fault Tolerance 4.1. + +This release includes several significant changes. +- MicroProfile Metrics 5.1 has been removed from the MicroProfile umbrella release and is now a stand-alone specification. +- MicroProfile Telemetry 2.0 marks a major release by incorporating support for Logs and Metrics in addition to Tracing, broadening its observability capabilities. +- MicroProfile Rest Client 4.0 has adopted Jakarta Restful Web Services 3.1 to support multipart form data, while MicroProfile OpenAPI 4.0 has aligned with the OpenAPI 3.1 standards to help ensure compliance with the latest specifications. +- MicroProfile 7.0 is designed to work with Jakarta EE 10 as the minimum version. + +If you are updating your application from using MicroProfile 6.1 features to using link:https://github.com/eclipse/microprofile/releases/tag/7.0[MicroProfile 7.0] features, the changes in API behavior might require you to update your application code. The following sections provide details about migrating your applications from MicroProfile 6.1 to MicroProfile 7.0: + +- <<#rc, Differences between MicroProfile REST Client 4.0 and 3.0>> +- <<#openapi, Differences between MicroProfile OpenAPI 3.1 and 4.0>> +- <<#ft, Fault Tolerance Version Updated to 4.1>> +- <<#mp, MicroProfile 7.0 vs. MicroProfile 6.1>> +- <<#tm, Telemetry Version Updated to 2.0>> + + + +[#rc] +== Differences between MicroProfile REST Client 4.0 and 3.0 + +With the release of the feature:mpRestClient-4.0[display=MicroProfile REST Client 4.0] feature, the underlying MicroProfile REST Client implementation for Open Liberty is now compatible with Jakarta EE 10 and is designed to tolerate Jakarta EE 11. + +If you are updating your server from a version of the MicroProfile REST Client feature prior to version 3.0, you may need to update your application code due to changes in API behavior. For more information, see xref:reference:diff/mp-41-50-diff.adoc#rc[Differences between MicroProfile REST Client 3.0 and 2.0]. + +The following sections provide details about changes in behavior between the feature:mpRestClient-3.0[display=mpRestClient-3.0] and feature:mpRestClient-4.0[display=mpRestClient-4.0] features. + + +=== Client creation without URI + +You no longer need to create a `URI` object themselves to create a Client instance; instead, you can pass a `String` directly. + +[source,java] +---- +RestClientBuilder.newBuilder() + .baseUri("http://example.com") + .build(SomeClient.class) +---- + + +=== Set HTTP Headers on a per instance basis + +You can now set HTTP headers for each Client instance using the new `RestClientBuilder.header(String, Object)` method. + +[source,java] +---- +RestClientBuilder.newBuilder() + .baseUri(someURI or String) + .header("Some-Header", headerValueObj) + .build(SomeClient.class) +---- + + + +[#openapi] +== Differences between MicroProfile OpenAPI 3.1 and 4.0 + +=== OpenAPI Version Updated to 3.1 + +The OpenAPI document is now generated in OpenAPI 3.1 format by default, an update from OpenAPI 3.0 in `mpOpenAPI-3.1`. + +OpenAPI 3.1 introduces the ability to capture more detail, including the use of the full JSON Schema (2020-12 draft) for describing data objects. It also adds support for documenting webhooks and for indicating that an API uses mutual TLS for authentication. For more information see the link:https://github.com/OAI/OpenAPI-Specification/releases/tag/3.1.0[OpenAPI 3.1.0 release notes]. + +New APIs and annotation parameters are added to MicroProfile OpenAPI 4.0, to allow users to take advantage of the new OpenAPI 3.1 features. For more information on new APIs, see the link:https://download.eclipse.org/microprofile/microprofile-open-api-4.0.2/microprofile-openapi-spec-4.0.2.html#release_notes_40[MicroProfile OpenAPI 4.0 release notes]. + +However, these changes mean that OpenAPI 3.1 is not fully backward compatible with OpenAPI 3.0, and existing tools may not work with it. To maintain compatibility with existing tools, you can configure `mpOpenAPI-4.0` to produce OpenAPI 3.0 documentation. + +[source,xml] +---- + +---- + +If you use the new APIs and annotations corresponding to OpenAPI 3.1 features, the additional information they provide is not be included when the feature is configured to generate OpenAPI 3.0 documents. + +=== All Deployed Applications Are Documented by Default +In this update, all deployed applications are included in the OpenAPI documentation by default. In previous versions of mpOpenAPI, only the first module of the first deployed application was documented by default. + +You can control which applications are included in the documentation using the following configuration: + +[source,xml] +---- + + application1 + application2 + +---- + +For more information, see . + + + +[#ft] +== Fault Tolerance Version Updated to 4.1 + +MicroProfile Fault Tolerance 4.1, an update to version 4.0, introduces integration with MicroProfile Telemetry 2.0. This allows Fault Tolerance to export metrics directly to MicroProfile Telemetry. The existing integration with `mpMetrics` remains unchanged. + + +=== Enable MicroProfile Fault Tolerance + +To enable MicroProfile Fault Tolerance, add the following to your `server.xml` file. + +[source,xml] +---- +mpFaultTolerance-4.1 +---- + +For integration between `mpFaultTolerance` and `mpTelemetry`, you must enable both `mpFaultTolerance-4.1` and `mpTelemetry-2.0` simultaneously. When both features are enabled, mpFaultTolerance will automatically export metrics to mpTelemetry. + +[source,xml] +---- +mpFaultTolerance-4.1 +mpTelemetry-2.0 +---- + +For more information on configuring mpTelemetry to export metrics, see the section on `mpTelemetry-2.0`. + +If `mpFaultTolerance-4.1` is enabled alongside both `mpTelemetry-2.0` and `mpMetrics-5.1`, Fault Tolerance will export metrics to both mpTelemetry and mpMetrics. + +.Comparison between metrics in mpMetrics and mpTelemetry +[cols="1,1,1", options="header"] +|=== +|Name |Type in mpMetrics |Type in mpTelemetry + +|`ft.invocations.total` +|`Counter` +|A counter that emits long + +|`ft.retry.calls.total` +|`Counter` +|A counter that emits long + +|`ft.retry.retries.total` +|`Counter` +|A counter that emits long + +|`ft.timeout.calls.total` +|`Counter` +|A counter that emits long + +|`ft.circuitbreaker.calls.total` +|`Counter` +|A counter that emits long + +|`ft.circuitbreaker.state.total` +|`Gauge` +|A counter that emits long + +|`ft.circuitbreaker.opened.total` +|`Counter` +|A counter that emits long + +|`ft.bulkhead.calls.total` +|`Counter` +|A counter that emits long + +|`ft.bulkhead.executionsRunning` +|`Gauge` +|An UpDownCounter that emits long + +|`ft.bulkhead.executionsWaiting` +|`Gauge` +|An UpDownCounter that emits long +|=== + + +.Comparison between Histogram Metrics in mpMetrics and mpTelemetry +[cols="1,1,1,1,1", options="header"] +|=== +|Name |Type in mpMetrics |Unit in mpMetrics |Type in mpTelemetry |Unit in mpTelemetry + +|`ft.timeout.executionDuration` +|`Histogram` +|Nanoseconds +|A Histogram that records `double` values with explicit bucket boundaries `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]` +|Seconds + +|`ft.bulkhead.runningDuration` +|`Histogram` +|Nanoseconds +|A Histogram that records `double` values with explicit bucket boundaries `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]` +|Seconds + +|`ft.bulkhead.waitingDuration` +|`Histogram` +|Nanoseconds +|A Histogram that records `double` values with explicit bucket boundaries `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]` +|Seconds +|=== + + + +[#mp] +== MicroProfile 7.0 vs. MicroProfile 6.1 + +link:https://download.eclipse.org/microprofile/microprofile-7.0/microprofile-spec-7.0.html[MicroProfile 7.0] is a major release that includes backward-incompatible changes. One significant update is the replacement of MicroProfile Metrics with MicroProfile Telemetry 2.0, which offers Metrics capabilities in addition to support for logs and tracing. + +If you are using MicroProfile Metrics from MicroProfile 6.1, you will need to add the following in your `server.xml` file when upgrading to MicroProfile 7.0. + +[source,xml] +---- +mpMetrics-5.1 +---- + +If your application does not use any APIs from MicroProfile Metrics, your application will have the Metrics from MicroProfile Telemetry 2.0, and no migration effort is required. + +In Open Liberty, the Jakarta EE 10 Core Profile features are automatically included with the `microProfile-7.0` feature to provide a smoother upgrade experience from `microProfile-6.1`. + + + +[#tm] +== Telemetry Version Updated to 2.0 + +MicroProfile Telemetry 2.0 is an update to MicroProfile Telemetry 1.1, incorporating the latest OpenTelemetry SDK (version 1.39). Previously, only traces were collected and exported. The updated feature now includes the ability to collect and export metrics and logs. Specifically, the following enhancements are provided: + +* Access to the OpenTelemetry Metrics API +* HTTP metrics +* JVM runtime environment metrics +* Runtime-level logs +* Application logs + +=== Enable MicroProfile Telemetry + +To enable MicroProfile Telemetry, add the following to your `server.xml` file. + +[source,xml] +---- +mpTelemetry-2.0 +---- + +MicroProfile Telemetry 2.0 provides runtime-level telemetry. To enable this, you must add the MicroProfile Telemetry feature to your `server.xml` file and enable the OpenTelemetry SDK using system properties or environment variables. Once enabled, you can configure how MicroProfile Telemetry collects and exports traces, metrics, and logs. + +This is significantly different from MicroProfile Telemetry 1.1, which provided full functionality using only MicroProfile Config for configuration. If you do not use system properties or environment variables for configuration, runtime-level metrics and logs cannot be collected. + +To enable the OpenTelemetry SDK, use the following configuration. + +[source,properties] +---- +otel.sdk.disabled=false +---- + +=== Accessing the Metrics API + +You can use the OpenTelemetry Metrics API to define custom metrics within your application code. By enabling the MicroProfile Telemetry feature version 2.0 or later, you can collect and emit these custom metrics to customize the observability of your application. + +For more information on the OpenTelemetry metrics, see the link:https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/1.39.0/io/opentelemetry/api/metrics/package-summary.html[OpenTelemetry Metrics API documentation]. + +To make the APIs accessible, you must enable third-party APIs for your application by adding the following configuration to your `server.xml` file. + +[source,xml] +---- + + + +---- + +=== Collecting Logs + +You can enable MicroProfile Telemetry to collect logs from various sources within the Open Liberty runtime environment. MicroProfile Telemetry can collect the following types of events: + +- xref:mptel-log-events-list.adoc#me[Message events] +- xref:mptel-log-events-list.adoc#te[Trace events] +- xref:mptel-log-events-list.adoc#ffdce[FFDC events] + +To enable these log sources, configure the source attribute for the mpTelemetry element with a comma-separated list of the desired log sources: + +[source,xml] +---- + +---- + +The mpTelemetry configuration element is optional. If you do not specify it or omit the source attribute, the default configuration source is message. For more details, see feature:mpTelemetry-2.0[display=Collect logs from a specified source]. + +=== Exporting Metrics and Logs + +By default, all OpenTelemetry data is exported to link:https://opentelemetry.io/docs/specs/otel/protocol/exporter/[OTLP]. You can change the export settings for metrics by specifying the `otel.metrics.exporter` property or the `OTEL_METRICS_EXPORTER` environment variable. For logs, specify the `otel.logs.exporter` property or the `OTEL_LOGS_EXPORTER` environment variable. + +For example, to change the metrics exporter so that collected metrics are sent to the console, set the following: + +[source,properties] +---- +otel.metrics.exporter = console +---- + From 9d7f3b3b7b94b079f9f740e4dc1bf633c2e4d4bd Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Fri, 8 Nov 2024 23:16:17 +0530 Subject: [PATCH 13/81] 7654-Documentation-MicroProfile-OpenAPI-4.0-2 7654-Documentation-MicroProfile-OpenAPI-4.0-2 #7654 --- .../pages/feature/mpOpenAPI-3.1/examples.adoc | 34 ++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc b/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc index a889eb6ed..79956a5dc 100644 --- a/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc +++ b/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc @@ -34,4 +34,36 @@ For example, the following configuration is for the `sample_app` application, wh - The `` element 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] \ No newline at end of file +For more information, see xref:ROOT:documentation-openapi.adoc#multi-module[Multiple application and multi-module application support with MicroProfile OpenAPI] + + +== mpOpenAPI-4.0 - Will be placed in another doc (Placed here for REVIEW) + +By default, all deployed applications and modules are included in the OpenAPI documentation. However, you can configure which applications and modules should be included. + +For example, the following configuration is for the `sample_app` application, which consists of an `EAR` file containing five web modules. + +[source,xml] +---- + + sample_app/module-3 + sample_app/module-5 + + +---- + +- The `` elements exclude the `module-3` and `module-5` web modules. + +- The `` element 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] + From ac4b1df43a5d3eb65d8bb711f3b798de25feb084 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Fri, 8 Nov 2024 23:32:25 +0530 Subject: [PATCH 14/81] 7610-MicroProfile 7.0 ID-1 7610-MicroProfile 7.0 ID-1 #7610 --- modules/reference/pages/diff/mp-61-70-diff.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/reference/pages/diff/mp-61-70-diff.adoc b/modules/reference/pages/diff/mp-61-70-diff.adoc index c91b01f3a..a78db3db9 100644 --- a/modules/reference/pages/diff/mp-61-70-diff.adoc +++ b/modules/reference/pages/diff/mp-61-70-diff.adoc @@ -16,7 +16,7 @@ :page-type: general -= Differences between MicroProfile 6.1 and 6.0 += Differences between MicroProfile 7.0 and 6.1 MicroProfile 7.0 is a major release. It introduces updated MicroProfile specifications, including MicroProfile Telemetry 2.0, MicroProfile Rest Client 4.0, MicroProfile OpenAPI 4.0, and MicroProfile Fault Tolerance 4.1. From dcec7c6067a336f101cf0ecac38de974005f40a5 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Fri, 8 Nov 2024 13:23:20 -0500 Subject: [PATCH 15/81] edits #7655 --- .../ROOT/pages/microprofile-telemetry.adoc | 33 ++++++++++++++++--- 1 file changed, 29 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/microprofile-telemetry.adoc b/modules/ROOT/pages/microprofile-telemetry.adoc index 747cfee95..dad611b02 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -15,12 +15,24 @@ The OpenTelemetry project is a collection of open source vendor-independent tools, APIs, and SDKs for creating and managing logs, metrics, and trace data. With Open Liberty and MicroProfile Telemetry 2.0 and later, you can manage this data in a standardized way by using the OpenTelemetry protocol. +OpenTelemetry provides a link:https://opentelemetry.io/docs/collector/[Collector] component that can receive telemetry data from your applications export it to backend services of your choice for visualization and monitoring. The Collector includes various exporters for different open source or commercial services, such as sending your traces to Jaeger or your metrics to Prometheus. + +OpenTelemetry is implemented in Open Liberty through the feature:mptelemtry[display=MicroProfile Telemetry] feature, which enables a collector that you can configure with MicroProfile Config properties and other system properties or environment variables. + +When you enable the MicroProfile Telemetry feature 2.0 or later and specify the required configuration property, Open Liberty automatically collects and exports logs, traces, and metrics at the application or runtime level. For many common application scenarios, no changes are needed in your application code to collect this data. + +MicroProfile 1.1 and earlier enables only the collection of traces and only at the application level. + +When you enable OpenTelemetry for Open Liberty, by default, all telemetry data is exported to the Open Telemetry Protocol (OTLP). OTLP defines the encoding of telemetry data and the protocol that is used to exchange data between a client and server. + +Many backend services accept OTLP data without requiring conversion, but OpenTelemtry also provides a collection of service-specific exporters for popular open source and commercial services, such as Jaeger, Zipkin, and Prometheus. You can configure global or data-specific exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. + [#global] == Collecting and exporting logs, metrics, and traces with OpenTelemetry -To use OpenTelemetry to collect and export logs, metrics, and traces in your Open Liberty runtime, you must add the MicroProfile Telemetry feature to your `server.xml` file and specify the `otel.sdk.disabled=false` system property in one of the valid configuration sources. Depending on whether you have a single application hosted on your Liberty runtime or multiple applications on the same runtime, you can specify this property at the runtime level or the application level. In most cases, runtime-level configuration is preferred as it includes both runtime-level telemetry and application-specific telemetry. The following table summarizes the benefits and use cases for each option. +To use OpenTelemetry to collect and export logs, metrics, and traces in your Open Liberty runtime, you must add the MicroProfile Telemetry feature to your `server.xml` file and specify the `otel.sdk.disabled=false` system property in one of the valid configuration sources. Depending on whether your Open Liberty runtime hosts a single application or multiple applications, you can specify this property at the runtime level or the application level. In most cases, runtime-level configuration is preferred as it includes both runtime-level telemetry and application-specific telemetry. The following table summarizes the benefits and use cases for each option. -.OpenTelemetry configuration sources +.OpenTelemetry configuration options [options="header"cols="3,3,6a,3a"] |=== |Use case| Configuration level | Description | Configuration sources @@ -75,7 +87,12 @@ When your Liberty runtime hosts multiple applications, you can enable OpenTeleme ---- -* Set `otel.sdk.disabled=false` as an application-level property in the `microprofile-config.properties` file of each application. You can also set the `otel.service.name` property in each application to assign a service name to the telemetry data that is collected. This service name helps you identify the source of the data from each application when you send your data to monitoring and analytics tools. +* Set `otel.sdk.disabled=false` as an application-level property in the `microprofile-config.properties` file of each application. ++ +You can also set the `otel.service.name` property in each application to assign a service name to the telemetry data that is collected. This service name helps you identify the source of the data from each application when you send your data to monitoring and analytics tools. ++ +The following examples show an application scenario where two applications on the same Open Liberty runtime are configured to collect and export telemetry data at the application level. The data from each application is assigned a unique service name to clarify which application the data comes from. + + Application 1 `microprofile-config.properties` file: + @@ -94,7 +111,7 @@ otel.service.name=A2 This configuration creates all telemetry from Application 1 with the service name `A1`, and from Application 2 with the service name `A2`. * You can also use a combination of runtime-level and application-level configuration, so that some settings apply to all applications on the runtime, while others are specific to each application. This strategy can save you from having to duplicate general configuration settings in multiple applications on the same runtime. - ++ Any configuration in the system properties and server environment variables takes precedence over application-level configuration. Therefore, you can enable OpenTelemetry and assign a service name individually for each application, but specify other settings at the runtime level to apply globally to all applications on the runtime. + For example, you might want to collect a unique set of telemetry data for each application in the runtime, but have all applications share the same OpenTelemetry exporter. You can set the OpenTelemetry exporter at the runtime-level in the `bootstrap.properties` file: @@ -116,6 +133,14 @@ After you enable the MicroProfile Telemetry feature and set the `otel.sdk.disabl == OpenTelemetry settings and configuration +When you enable OpenTelemetry for Open Liberty, by default, all telemetry data is exported to the Open Telemetry Protocol (OTLP) at the `\http://localhost:4317` endpoint. You can configure alternative global or data-specific exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. + +Open Liberty supports all link:https://opentelemetry.io/docs/languages/java/configuration/#environment-variables-and-system-properties[OpenTelemtry Java configuration properties]. + +For information about commonly-used configuration properties, see xref:reference:microprofile-config-properties.adoc#telemetry[MicroPRofile Config properties: MicroPRofile Telemetry]. + +For common configuration examples, see the feature:mptelemtry[display=MicroProfile Telemetry] feature page. + [#traces] == Trace From aaa85d3e8f666fe6ee7a264a58d2fd6a603b06cb Mon Sep 17 00:00:00 2001 From: David Mueller Date: Fri, 8 Nov 2024 14:46:49 -0500 Subject: [PATCH 16/81] edits #7655 --- .../ROOT/pages/microprofile-telemetry.adoc | 50 ++++++------------- 1 file changed, 15 insertions(+), 35 deletions(-) diff --git a/modules/ROOT/pages/microprofile-telemetry.adoc b/modules/ROOT/pages/microprofile-telemetry.adoc index dad611b02..4a1d39d18 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -12,28 +12,19 @@ :page-type: general = OpenTelemetry -The OpenTelemetry project is a collection of open source vendor-independent tools, APIs, and SDKs for creating and managing logs, metrics, and trace data. With Open Liberty and MicroProfile Telemetry 2.0 and later, you can manage this data in a standardized way by using the OpenTelemetry protocol. +The OpenTelemetry project is a collection of open source, vendor-independent resources for collecting and managing application telemetry data. With Open Liberty and MicroProfile Telemetry 2.0 and later, you can manage this data in a standardized way by using the OpenTelemetry protocol. +OpenTelemetry provides a link:https://opentelemetry.io/docs/collector/[Collector] component that can receive telemetry data from your applications export it to backend services of your choice for visualization and monitoring. By default, all OpenTelemetry data is exported to the Open Telemetry Protocol (OTLP). OTLP defines the encoding of telemetry data and the protocol that is used to exchange data between a client and server. Many backend services accept OTLP data without requiring conversion, but OpenTelemtry also provides a collection of service-specific exporters for popular open source and commercial services, such as Jaeger, Zipkin, and Prometheus. You can configure global or data-specific exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. -OpenTelemetry provides a link:https://opentelemetry.io/docs/collector/[Collector] component that can receive telemetry data from your applications export it to backend services of your choice for visualization and monitoring. The Collector includes various exporters for different open source or commercial services, such as sending your traces to Jaeger or your metrics to Prometheus. - -OpenTelemetry is implemented in Open Liberty through the feature:mptelemtry[display=MicroProfile Telemetry] feature, which enables a collector that you can configure with MicroProfile Config properties and other system properties or environment variables. - -When you enable the MicroProfile Telemetry feature 2.0 or later and specify the required configuration property, Open Liberty automatically collects and exports logs, traces, and metrics at the application or runtime level. For many common application scenarios, no changes are needed in your application code to collect this data. - -MicroProfile 1.1 and earlier enables only the collection of traces and only at the application level. - -When you enable OpenTelemetry for Open Liberty, by default, all telemetry data is exported to the Open Telemetry Protocol (OTLP). OTLP defines the encoding of telemetry data and the protocol that is used to exchange data between a client and server. - -Many backend services accept OTLP data without requiring conversion, but OpenTelemtry also provides a collection of service-specific exporters for popular open source and commercial services, such as Jaeger, Zipkin, and Prometheus. You can configure global or data-specific exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. +OpenTelemetry is implemented in Open Liberty through the feature:mptelemtry[display=MicroProfile Telemetry] feature, which enables a collector that you can configure with MicroProfile Config properties and other system properties or environment variables. When you enable the MicroProfile Telemetry feature 2.0 or later and specify the required configuration property, Open Liberty automatically collects and exports logs, traces, and metrics at the application or runtime level. For many common application scenarios, no changes are needed in your application code to collect this data. MicroProfile Telemetry1.1 and earlier enables only the collection of traces and only at the application level. [#global] == Collecting and exporting logs, metrics, and traces with OpenTelemetry -To use OpenTelemetry to collect and export logs, metrics, and traces in your Open Liberty runtime, you must add the MicroProfile Telemetry feature to your `server.xml` file and specify the `otel.sdk.disabled=false` system property in one of the valid configuration sources. Depending on whether your Open Liberty runtime hosts a single application or multiple applications, you can specify this property at the runtime level or the application level. In most cases, runtime-level configuration is preferred as it includes both runtime-level telemetry and application-specific telemetry. The following table summarizes the benefits and use cases for each option. +To collect and export logs, metrics, and traces with OpenTelemetry in your Open Liberty runtime, you must add the MicroProfile Telemetry feature to your `server.xml` file and specify the `otel.sdk.disabled=false` system property in one of the valid configuration sources. Depending on whether your runtime hosts a single application or multiple applications, you can specify this property at the runtime level or the application level. In most cases, runtime-level configuration is preferred as it includes both runtime-level telemetry and application-specific telemetry. The following table summarizes the benefits and use cases for each option. .OpenTelemetry configuration options -[options="header"cols="3,3,6a,3a"] +[options="header"cols="4,2,6a,3a"] |=== |Use case| Configuration level | Description | Configuration sources @@ -53,7 +44,7 @@ To use OpenTelemetry to collect and export logs, metrics, and traces in your Ope === Enabling OpenTelemetry for an Open Liberty runtime with a single application -When your Liberty runtime hosts only one application, you can enable Open Telemetry at the runtime level to collect and export logs, metrics, and traces for both the runtime and the application +When your Open Liberty runtime hosts only one application, you can enable Open Telemetry at the runtime level to collect and export logs, metrics, and traces for both the runtime and the application. * Enable the feature:mpTelemetry[display=MicroProfile Telemetry] feature version 2.0 or later in the `featureManager` element of your `server.xml` file. + @@ -65,13 +56,13 @@ When your Liberty runtime hosts only one application, you can enable Open Teleme ---- -* Set `otel.sdk.disabled=false` as a runtime-level property, for example, in the `bootstrap.properties` file: +* Set `otel.sdk.disabled=false` as a runtime-level property, for example, in the xref:reference:config/server-configuration-overview.adoc#bootstrap-properties[bootstrap.properties] file: + ---- otel.sdk.disabled=false ---- -After you enable the MicroProfile Telemetry feature and set this system property, your runtime is ready to start collecting and exporting logs, metrics, and traces from the application and the runtime. For more information, see the individual sections for logs, metrics, and traces. +After you enable the MicroProfile Telemetry feature and set this system property, your runtime is ready to start collecting and exporting logs, metrics, and traces from the application and the runtime. For more information, see <>. === Enabling OpenTelemetry for multiple applications in the same Open Liberty runtime @@ -89,10 +80,7 @@ When your Liberty runtime hosts multiple applications, you can enable OpenTeleme * Set `otel.sdk.disabled=false` as an application-level property in the `microprofile-config.properties` file of each application. + -You can also set the `otel.service.name` property in each application to assign a service name to the telemetry data that is collected. This service name helps you identify the source of the data from each application when you send your data to monitoring and analytics tools. -+ -The following examples show an application scenario where two applications on the same Open Liberty runtime are configured to collect and export telemetry data at the application level. The data from each application is assigned a unique service name to clarify which application the data comes from. - +The following examples show an application scenario where two applications on the same Open Liberty runtime are configured to collect and export telemetry data at the application level. These examples also set the `otel.service.name` property in each application to assign a service name to the telemetry data that is collected. This service name helps you identify the source of the data from each application when you send your data to monitoring and analytics tools. + Application 1 `microprofile-config.properties` file: + @@ -110,9 +98,7 @@ otel.service.name=A2 + This configuration creates all telemetry from Application 1 with the service name `A1`, and from Application 2 with the service name `A2`. -* You can also use a combination of runtime-level and application-level configuration, so that some settings apply to all applications on the runtime, while others are specific to each application. This strategy can save you from having to duplicate general configuration settings in multiple applications on the same runtime. -+ -Any configuration in the system properties and server environment variables takes precedence over application-level configuration. Therefore, you can enable OpenTelemetry and assign a service name individually for each application, but specify other settings at the runtime level to apply globally to all applications on the runtime. +* You can also use a combination of runtime-level and application-level configuration, so that some settings apply to all applications on the runtime, while others are specific to each application. This strategy can save you from having to duplicate general configuration settings in multiple applications on the same runtime. Any runtime-level configuration takes precedence over application-level configuration. Therefore, you can enable OpenTelemetry and assign a service name individually for each application, but specify other settings at the runtime level to apply globally to all applications on the runtime. + For example, you might want to collect a unique set of telemetry data for each application in the runtime, but have all applications share the same OpenTelemetry exporter. You can set the OpenTelemetry exporter at the runtime-level in the `bootstrap.properties` file: + @@ -129,23 +115,18 @@ otel.service.name= + This configuration enables an application-level telemetry with a unique service name for each application, while all applications in the runtime use the `myExporter` OpenTelemetry exporter. -After you enable the MicroProfile Telemetry feature and set the `otel.sdk.disabled=false` property for each application on the runtime, your applications are ready to start collecting and exporting logs, metrics, and traces. For more information, see the individual sections for logs, metrics, and traces. +After you enable the MicroProfile Telemetry feature and set the `otel.sdk.disabled=false` property for each application on the runtime, your applications are ready to start collecting and exporting logs, metrics, and traces. +[#config] == OpenTelemetry settings and configuration -When you enable OpenTelemetry for Open Liberty, by default, all telemetry data is exported to the Open Telemetry Protocol (OTLP) at the `\http://localhost:4317` endpoint. You can configure alternative global or data-specific exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. - -Open Liberty supports all link:https://opentelemetry.io/docs/languages/java/configuration/#environment-variables-and-system-properties[OpenTelemtry Java configuration properties]. +When you enable OpenTelemetry for Open Liberty, by default, all telemetry data is exported to the Open Telemetry Protocol (OTLP) at the `\http://localhost:4317` endpoint. You can configure alternative global or data-specific exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. Open Liberty supports all link:https://opentelemetry.io/docs/languages/java/configuration/#environment-variables-and-system-properties[OpenTelemtry Java configuration properties]. -For information about commonly-used configuration properties, see xref:reference:microprofile-config-properties.adoc#telemetry[MicroPRofile Config properties: MicroPRofile Telemetry]. - -For common configuration examples, see the feature:mptelemtry[display=MicroProfile Telemetry] feature page. +For information about commonly-used configuration properties, see xref:reference:microprofile-config-properties.adoc#telemetry[MicroPRofile Config properties: MicroPRofile Telemetry]. For common configuration examples, see the feature:mptelemtry[display=MicroProfile Telemetry] feature page. [#traces] == Trace -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 about what happens during a transaction. - When you enable OpenTelemetry for Open Liberty, Jakarta RESTful Web Services and JAX-RS applications are instrumented for trace by default. Spans are automatically generated for incoming HTTP requests, including static files, servlets, and JSPs. These spans are automatically exported according to the configured OpenTelemetry settings. 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 OpenTelemetry API. Alternatively, you can attach the OpenTelemetry Java agent to any Java 8+ application. For more information about these options, see xref:telemetry-trace.adoc#t[Code instrumentation for MicroProfile Telemetry tracing]. @@ -163,10 +144,9 @@ By default, the OpenTelemetry Simple logRecord Processor is enabled, so the reco [#metrics] == Metrics -By default, OpenTelemetry exports metric data at an interval of 60 seconds. You can modify the export interval and other default settings by using MicroProfile config properties. - For a list of metrics that are available for Open Liberty when you enable the MicroProfile Telemetry feature 2.0 or later, see xref:mptelemetry-metrics-list.adoc[MicroProfile Telemetry metrics reference list]. +By default, OpenTelemetry exports metric data at an interval of 60 seconds. You can modify the export interval and other default settings by using MicroProfile config properties. == See also From 7a03f48d0642779616f2e7e0329a84f676af34db Mon Sep 17 00:00:00 2001 From: David Mueller Date: Fri, 8 Nov 2024 15:06:24 -0500 Subject: [PATCH 17/81] edits 2 #7655 --- .../ROOT/pages/microprofile-telemetry.adoc | 8 ++++---- .../feature/mpTelemetry-2.0/examples.adoc | 20 ++++++++++++++++++- 2 files changed, 23 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/microprofile-telemetry.adoc b/modules/ROOT/pages/microprofile-telemetry.adoc index 4a1d39d18..25e899d20 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -14,7 +14,7 @@ The OpenTelemetry project is a collection of open source, vendor-independent resources for collecting and managing application telemetry data. With Open Liberty and MicroProfile Telemetry 2.0 and later, you can manage this data in a standardized way by using the OpenTelemetry protocol. -OpenTelemetry provides a link:https://opentelemetry.io/docs/collector/[Collector] component that can receive telemetry data from your applications export it to backend services of your choice for visualization and monitoring. By default, all OpenTelemetry data is exported to the Open Telemetry Protocol (OTLP). OTLP defines the encoding of telemetry data and the protocol that is used to exchange data between a client and server. Many backend services accept OTLP data without requiring conversion, but OpenTelemtry also provides a collection of service-specific exporters for popular open source and commercial services, such as Jaeger, Zipkin, and Prometheus. You can configure global or data-specific exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. +OpenTelemetry provides a link:https://opentelemetry.io/docs/collector/[collector] component that can receive telemetry data from your applications and export it to backend services of your choice for visualization and monitoring. By default, all OpenTelemetry data is exported to the Open Telemetry Protocol (OTLP). OTLP defines the encoding of telemetry data and the protocol that is used to exchange data between a client and server. Many backend services accept OTLP data without requiring conversion, but OpenTelemtry also provides a collection of service-specific exporters for popular open source and commercial services, such as Jaeger, Zipkin, and Prometheus. You can configure global or data-specific exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. OpenTelemetry is implemented in Open Liberty through the feature:mptelemtry[display=MicroProfile Telemetry] feature, which enables a collector that you can configure with MicroProfile Config properties and other system properties or environment variables. When you enable the MicroProfile Telemetry feature 2.0 or later and specify the required configuration property, Open Liberty automatically collects and exports logs, traces, and metrics at the application or runtime level. For many common application scenarios, no changes are needed in your application code to collect this data. MicroProfile Telemetry1.1 and earlier enables only the collection of traces and only at the application level. @@ -125,14 +125,14 @@ When you enable OpenTelemetry for Open Liberty, by default, all telemetry data i For information about commonly-used configuration properties, see xref:reference:microprofile-config-properties.adoc#telemetry[MicroPRofile Config properties: MicroPRofile Telemetry]. For common configuration examples, see the feature:mptelemtry[display=MicroProfile Telemetry] feature page. [#traces] -== Trace +=== Trace When you enable OpenTelemetry for Open Liberty, Jakarta RESTful Web Services and JAX-RS applications are instrumented for trace by default. Spans are automatically generated for incoming HTTP requests, including static files, servlets, and JSPs. These spans are automatically exported according to the configured OpenTelemetry settings. 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 OpenTelemetry API. Alternatively, you can attach the OpenTelemetry Java agent to any Java 8+ application. For more information about these options, see xref:telemetry-trace.adoc#t[Code instrumentation for MicroProfile Telemetry tracing]. [#logs] -== Logs +=== Logs OpenTelemetry automatically collects any logs that are sent to the `java.util.logging` API. Any messages that are logged at a `java.util.logging.Level` log level of `INFO` and above are considered messages. Levels below `INFO` are considered trace. By default, OpenTelemetry automatically collects messages, but you can configure the sources that it collects from in your `server.xml` file. For more information, see link:/docs/latest/reference/feature/mpTelemetry-2.0.html#_collect_logs_from_a_specified_source[Collect logs from a specified source]. @@ -142,7 +142,7 @@ By default, the OpenTelemetry Simple logRecord Processor is enabled, so the reco [#metrics] -== Metrics +=== Metrics For a list of metrics that are available for Open Liberty when you enable the MicroProfile Telemetry feature 2.0 or later, see xref:mptelemetry-metrics-list.adoc[MicroProfile Telemetry metrics reference list]. diff --git a/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc b/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc index d048f3e3e..a901baeee 100644 --- a/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc +++ b/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc @@ -1,7 +1,14 @@ == Examples +=== Enable Open Telemetry + +=== Prepare your development environment for Open Telemetry + [#logs] -=== Collect logs from a specified source +=== Log settings +The following examples show common optional settings to configure the collection and export of OpenTelemetry log data. + +==== Collect logs from a specified source To enable the MicroProfile Telemetry feature to collect logs from different sources in the Open Liberty runtime environment, configure the `source` attribute for the `mpTelemetry` element with a comma-separated list of comma-separated log sources. @@ -15,3 +22,14 @@ To enable the MicroProfile Telemetry feature to collect logs from different sour * If the source attribute is empty (`source=“”`), no sources are collected, and nothing is routed to the configured OpenTelemetry logs exporter. * The attributes and values are case insensitive. + +[#metrics] +=== Metrics settings +The following examples show common optional settings to configure the collection and export of OpenTelemetry metrics data. + +[#trace] +=== Trace settings +The following examples show common optional settings to configure the collection and export of OpenTelemetry trace data. + + +=== From c8e2974b5e84d1945ab87c47890494c7860f0d3d Mon Sep 17 00:00:00 2001 From: David Mueller Date: Mon, 11 Nov 2024 15:14:38 -0500 Subject: [PATCH 18/81] edits #7655 --- .../ROOT/pages/microprofile-telemetry.adoc | 5 +- .../feature/mpTelemetry-2.0/examples.adoc | 59 +++++++++++++++---- 2 files changed, 51 insertions(+), 13 deletions(-) diff --git a/modules/ROOT/pages/microprofile-telemetry.adoc b/modules/ROOT/pages/microprofile-telemetry.adoc index 25e899d20..197a0e938 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -122,7 +122,7 @@ After you enable the MicroProfile Telemetry feature and set the `otel.sdk.disabl When you enable OpenTelemetry for Open Liberty, by default, all telemetry data is exported to the Open Telemetry Protocol (OTLP) at the `\http://localhost:4317` endpoint. You can configure alternative global or data-specific exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. Open Liberty supports all link:https://opentelemetry.io/docs/languages/java/configuration/#environment-variables-and-system-properties[OpenTelemtry Java configuration properties]. -For information about commonly-used configuration properties, see xref:reference:microprofile-config-properties.adoc#telemetry[MicroPRofile Config properties: MicroPRofile Telemetry]. For common configuration examples, see the feature:mptelemtry[display=MicroProfile Telemetry] feature page. +For information about commonly-used configuration properties for global, logs, metrics, and trace settings, see xref:reference:microprofile-config-properties.adoc#telemetry[MicroProfile Config properties: MicroProfile Telemetry]. [#traces] === Trace @@ -144,9 +144,8 @@ By default, the OpenTelemetry Simple logRecord Processor is enabled, so the reco [#metrics] === Metrics -For a list of metrics that are available for Open Liberty when you enable the MicroProfile Telemetry feature 2.0 or later, see xref:mptelemetry-metrics-list.adoc[MicroProfile Telemetry metrics reference list]. +For a list of metrics that are available for Open Liberty when you enable the MicroProfile Telemetry feature 2.0 or later, see xref:mptelemetry-metrics-list.adoc[MicroProfile Telemetry metrics reference list]. You can also xref:custom-mptelemetry-metrics.adoc[define custom metrics in your application code]. -By default, OpenTelemetry exports metric data at an interval of 60 seconds. You can modify the export interval and other default settings by using MicroProfile config properties. == See also diff --git a/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc b/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc index a901baeee..63feaa5eb 100644 --- a/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc +++ b/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc @@ -1,13 +1,55 @@ == Examples -=== Enable Open Telemetry +=== Enable OpenTelemetry -=== Prepare your development environment for Open Telemetry +In addition to enabling the MicroProfile Telemetry feature, you must also set the `otel.sdk.disabled=false` system property in one of the valid configuration sources. Depending on your application scenario, you can set this property at the runtime level, or the application level. For more information see xref:ROOT:microprofile-telemetry.adoc#global[Collecting and exporting logs, metrics, and traces with OpenTelemetry.] -[#logs] +The following example demonstrates how to enable OpenTelemetry at the runtime level,by setting the property in your `bootstrap.properties` file: + +---- +otel.sdk.disabled=false +---- + +When you enable the MicroProfile Telemetry feature and set this property, your system is ready to collect and export logs, metrics, and traces. + +[#dev] +=== Prepare your development environment for OpenTelemetry + +If you need to xref:ROOT:telemetry-trace.adoc[manually instrument your code to collect traces] or xref:ROOT:custom-mptelemetry-metrics.adoc[define custom metrics], complete the following prerequisites to enable MicroProfile Telemetry in your development environment: + +. 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] +---- + + + +---- + +. 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] +---- + + io.opentelemetry + opentelemetry-api + 1.39.0 + provided + + + io.opentelemetry.instrumentation + opentelemetry-instrumentation-annotations + 1.39.0-alpha + provided + +---- + + +[#logs-settings] === Log settings The following examples show common optional settings to configure the collection and export of OpenTelemetry log data. +[#logs] ==== Collect logs from a specified source To enable the MicroProfile Telemetry feature to collect logs from different sources in the Open Liberty runtime environment, configure the `source` attribute for the `mpTelemetry` element with a comma-separated list of comma-separated log sources. @@ -17,19 +59,16 @@ To enable the MicroProfile Telemetry feature to collect logs from different sour ---- -* The `mpTelemetry` configuration element is optional. If you do not specify ity or the `source` attribute, the default configuration source is `message`. +* The `mpTelemetry` configuration element is optional. If you do not specify it or the `source` attribute, the default configuration source is `message`. * If the source attribute is empty (`source=“”`), no sources are collected, and nothing is routed to the configured OpenTelemetry logs exporter. * The attributes and values are case insensitive. -[#metrics] -=== Metrics settings -The following examples show common optional settings to configure the collection and export of OpenTelemetry metrics data. -[#trace] -=== Trace settings -The following examples show common optional settings to configure the collection and export of OpenTelemetry trace data. +[#blrp] +==== Configure the OpenTelemetry Batch LogRecord Processor + === From 36ce7c1995a01001bb0b0837e58659b72c0cffd5 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Mon, 11 Nov 2024 15:21:43 -0500 Subject: [PATCH 19/81] Update microprofile-config-properties.adoc --- .../pages/microprofile-config-properties.adoc | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/modules/reference/pages/microprofile-config-properties.adoc b/modules/reference/pages/microprofile-config-properties.adoc index a8a14e77d..afc38fe2b 100644 --- a/modules/reference/pages/microprofile-config-properties.adoc +++ b/modules/reference/pages/microprofile-config-properties.adoc @@ -663,7 +663,17 @@ For more information about collecting Open Liberty logs, metrics, and traces, se |`otel.exporter.zipkin.endpoint` |Sets the endpoint for the Zipkin exporter. The default is \http://localhost:9411/api/v2/spans. |Application startup or runtime startup -|`otel.exporter.zipkin.endpoint=http://localhost:9411/api/v2/spans` +|`otel.exporter.zipkin.endpoint=http://localhost:9412/api/v2/spans` + +|`otel.metric.export.interval` +|By default, metric data is exported at an interval of 60000 milliseconds (one minute). To modify the export interval, specify the new value in milliseconds. For more information, see link:https://opentelemetry.io/docs/specs/otel/metrics/sdk/#periodic-exporting-metricreader[Periodic exporting MetricReader] in the OpenTelemetry documentation. +|Application startup or runtime startup +|`otel.metric.export.interval=120000` + +|`otel.metric.export.timeout` +|By default, the maximum allowed time to export data is 30000 milliseconds (30 seconds). To modify the timeout value, specify a new value in milliseconds +|Application startup or runtime startup +|`otel.metric.export.timeout=60000` |`otel.sdk.disabled` |Enables logs, metrics, and traces to be sent to OpenTelemetry. The default is `true`. From 997badc34c0c9a89c79bf548808b1d73f58df9a0 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Wed, 13 Nov 2024 18:13:02 +0530 Subject: [PATCH 20/81] 7654-Documentation-MicroProfile-OpenAPI-4.0-3 7654-Documentation-MicroProfile-OpenAPI-4.0-3 #7654 --- modules/ROOT/pages/documentation-openapi.adoc | 31 +++++++++++-------- 1 file changed, 18 insertions(+), 13 deletions(-) diff --git a/modules/ROOT/pages/documentation-openapi.adoc b/modules/ROOT/pages/documentation-openapi.adoc index 12f6ca9fe..b8a723699 100644 --- a/modules/ROOT/pages/documentation-openapi.adoc +++ b/modules/ROOT/pages/documentation-openapi.adoc @@ -131,6 +131,8 @@ For more information, see https://openliberty.io/guides/microprofile-openapi.htm The MicroProfile OpenAPI feature generates structured documentation based on the OpenAPI specification. Each new version of the OpenAPI specification updates the documentation format, and different versions of MicroProfile OpenAPI support different OpenAPI specification versions. +.Supported OpenAPI versions +[cols="1,2", options="header"] |=== |Feature | OpenAPI versions supported @@ -167,6 +169,9 @@ For example, you can select OpenAPI v3.0 when using `mpOpenAPI-4.0`. When multiple applications, or applications with more than one web module are deployed to the same Open Liberty server, the behavior differs between MicroProfile OpenAPI feature versions. + +.Multiple application and multi-module application support with MicroProfile OpenAPI +[cols="1,2", options="header"] |=== |Feature |Behavior @@ -180,7 +185,10 @@ When multiple applications, or applications with more than one web module are de |Only the first web module of the first application deployed is included in the structured documentation. This cannot be changed. |=== -For MicroProfile OpenAPI 2.0 and later, you can control the applications and modules that are included in the structured documentation by using the ``, ``, ``, and `` elements within the `` configuration element. +[#serverxml] +== Configuring multiple application and multi-module support using server.xml + +For MicroProfile OpenAPI 2.0 and later, you can control the applications and modules that are included in the structured documentation by using the ``, ``, ``, and `` elements within the `` xref:reference:config/mpOpenAPI.adoc[configuration element]. For example, to include all deployed applications and modules in the generated structured documentation when using `mpOpenAPI-2.0`, add the following configuration to your `server.xml` file. @@ -201,21 +209,21 @@ For example, to include all deployed applications and modules except the `admin` ---- -==== Key Points: +**Notes:** - The application name is determined by the value of the `name` attribute when the application is deployed in `server.xml` using ``, ``, or ``. For example: - ++ [source,xml] ---- ---- - ++ If the application is deployed in the `dropins` directory or if the `name` attribute is not specified, the name defaults to the archive filename with the extension removed. - ++ - The module name is specified in the web module's `web.xml` file. If there is no `web.xml` file or if it does not specify a name, the module name defaults to the filename with the extension removed. - ++ You can also override the `info` section of the OpenAPI document using the following configuration: - ++ [source,xml] ---- @@ -224,7 +232,7 @@ You can also override the `info` section of the OpenAPI document using the follo description="This is an example API"/> ---- - ++ This override may be useful when documenting multiple modules or applications. Without it, the `info` section would be replaced with a standard one indicating that documentation from several modules was merged. @@ -268,16 +276,13 @@ This value excludes no applications or web modules. |=== -- The default behavior varies between versions and has been explained earlier. - -==== Key Points: +**Notes:** - When you configure support for multiple applications and multi-module environments by using MicroProfile Config, the application name is taken from the application's deployment descriptor (application.xml or web.xml). If there is no deployment descriptor or if it does not specify a name, the name defaults to the application archive filename with the extension removed. - ++ - The module name follows the same rules as described for the server.xml configuration. == See also -- - Guide: link:/guides/microprofile-config-intro.html[Separating configuration from code in microservices] From b4346edc6a556c3b882c7414bca5dd01d9d08e88 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Wed, 13 Nov 2024 18:53:51 +0530 Subject: [PATCH 21/81] 7610-MicroProfile 7.0 ID-2 7610-MicroProfile 7.0 ID-2 #7610 --- .../reference/pages/diff/mp-61-70-diff.adoc | 58 ++++++++++--------- 1 file changed, 32 insertions(+), 26 deletions(-) diff --git a/modules/reference/pages/diff/mp-61-70-diff.adoc b/modules/reference/pages/diff/mp-61-70-diff.adoc index a78db3db9..b006dbe4d 100644 --- a/modules/reference/pages/diff/mp-61-70-diff.adoc +++ b/modules/reference/pages/diff/mp-61-70-diff.adoc @@ -28,21 +28,36 @@ This release includes several significant changes. If you are updating your application from using MicroProfile 6.1 features to using link:https://github.com/eclipse/microprofile/releases/tag/7.0[MicroProfile 7.0] features, the changes in API behavior might require you to update your application code. The following sections provide details about migrating your applications from MicroProfile 6.1 to MicroProfile 7.0: +- <<#mp, MicroProfile 7.0 vs. MicroProfile 6.1>> - <<#rc, Differences between MicroProfile REST Client 4.0 and 3.0>> - <<#openapi, Differences between MicroProfile OpenAPI 3.1 and 4.0>> - <<#ft, Fault Tolerance Version Updated to 4.1>> -- <<#mp, MicroProfile 7.0 vs. MicroProfile 6.1>> - <<#tm, Telemetry Version Updated to 2.0>> +[#mp] +== MicroProfile 7.0 vs. MicroProfile 6.1 + +link:https://download.eclipse.org/microprofile/microprofile-7.0/microprofile-spec-7.0.html[MicroProfile 7.0] is a major release that includes backward-incompatible changes. One significant update is the replacement of MicroProfile Metrics with MicroProfile Telemetry 2.0, which offers Metrics capabilities in addition to support for logs and tracing. + +If you are using MicroProfile Metrics from MicroProfile 6.1, you will need to add the following in your `server.xml` file when upgrading to MicroProfile 7.0. + +[source,xml] +---- +mpMetrics-5.1 +---- + +If your application does not use any APIs from MicroProfile Metrics, your application will have the Metrics from MicroProfile Telemetry 2.0, and no migration effort is required. + +In Open Liberty, the Jakarta EE 10 Core Profile features are automatically included with the `microProfile-7.0` feature to provide a smoother upgrade experience from `microProfile-6.1`. + + [#rc] == Differences between MicroProfile REST Client 4.0 and 3.0 With the release of the feature:mpRestClient-4.0[display=MicroProfile REST Client 4.0] feature, the underlying MicroProfile REST Client implementation for Open Liberty is now compatible with Jakarta EE 10 and is designed to tolerate Jakarta EE 11. -If you are updating your server from a version of the MicroProfile REST Client feature prior to version 3.0, you may need to update your application code due to changes in API behavior. For more information, see xref:reference:diff/mp-41-50-diff.adoc#rc[Differences between MicroProfile REST Client 3.0 and 2.0]. - The following sections provide details about changes in behavior between the feature:mpRestClient-3.0[display=mpRestClient-3.0] and feature:mpRestClient-4.0[display=mpRestClient-4.0] features. @@ -70,6 +85,9 @@ RestClientBuilder.newBuilder() .build(SomeClient.class) ---- +=== Processing Multipart Data + +Information and example code are added to the link:https://download.eclipse.org/microprofile/microprofile-rest-client-4.0/microprofile-rest-client-spec-4.0.html#_processing_multipart_data[MicroProfile Rest Client 4.0 specification] for processing multipart data, introduced as part of RESTful Web Services version 3.1 in EE10. [#openapi] @@ -83,6 +101,8 @@ OpenAPI 3.1 introduces the ability to capture more detail, including the use of New APIs and annotation parameters are added to MicroProfile OpenAPI 4.0, to allow users to take advantage of the new OpenAPI 3.1 features. For more information on new APIs, see the link:https://download.eclipse.org/microprofile/microprofile-open-api-4.0.2/microprofile-openapi-spec-4.0.2.html#release_notes_40[MicroProfile OpenAPI 4.0 release notes]. +If you use the new APIs and annotations corresponding to OpenAPI 3.1 features, the additional information they provide is not be included when the feature is configured to generate OpenAPI 3.0 documents. + However, these changes mean that OpenAPI 3.1 is not fully backward compatible with OpenAPI 3.0, and existing tools may not work with it. To maintain compatibility with existing tools, you can configure `mpOpenAPI-4.0` to produce OpenAPI 3.0 documentation. [source,xml] @@ -90,8 +110,6 @@ However, these changes mean that OpenAPI 3.1 is not fully backward compatible wi ---- -If you use the new APIs and annotations corresponding to OpenAPI 3.1 features, the additional information they provide is not be included when the feature is configured to generate OpenAPI 3.0 documents. - === All Deployed Applications Are Documented by Default In this update, all deployed applications are included in the OpenAPI documentation by default. In previous versions of mpOpenAPI, only the first module of the first deployed application was documented by default. @@ -208,25 +226,6 @@ If `mpFaultTolerance-4.1` is enabled alongside both `mpTelemetry-2.0` and `mpMet |=== - -[#mp] -== MicroProfile 7.0 vs. MicroProfile 6.1 - -link:https://download.eclipse.org/microprofile/microprofile-7.0/microprofile-spec-7.0.html[MicroProfile 7.0] is a major release that includes backward-incompatible changes. One significant update is the replacement of MicroProfile Metrics with MicroProfile Telemetry 2.0, which offers Metrics capabilities in addition to support for logs and tracing. - -If you are using MicroProfile Metrics from MicroProfile 6.1, you will need to add the following in your `server.xml` file when upgrading to MicroProfile 7.0. - -[source,xml] ----- -mpMetrics-5.1 ----- - -If your application does not use any APIs from MicroProfile Metrics, your application will have the Metrics from MicroProfile Telemetry 2.0, and no migration effort is required. - -In Open Liberty, the Jakarta EE 10 Core Profile features are automatically included with the `microProfile-7.0` feature to provide a smoother upgrade experience from `microProfile-6.1`. - - - [#tm] == Telemetry Version Updated to 2.0 @@ -247,9 +246,9 @@ To enable MicroProfile Telemetry, add the following to your `server.xml` file. mpTelemetry-2.0 ---- -MicroProfile Telemetry 2.0 provides runtime-level telemetry. To enable this, you must add the MicroProfile Telemetry feature to your `server.xml` file and enable the OpenTelemetry SDK using system properties or environment variables. Once enabled, you can configure how MicroProfile Telemetry collects and exports traces, metrics, and logs. +MicroProfile Telemetry 2.0 provides runtime-level telemetry. To enable this, you must add the MicroProfile Telemetry feature to your `server.xml` file and enable the OpenTelemetry SDK by using system properties or environment variables. Once enabled, you can configure how MicroProfile Telemetry collects and exports traces, metrics, and logs. This is different from MicroProfile Telemetry 1.1, which provided full functionality by using only MicroProfile Config for configuration. -This is significantly different from MicroProfile Telemetry 1.1, which provided full functionality using only MicroProfile Config for configuration. If you do not use system properties or environment variables for configuration, runtime-level metrics and logs cannot be collected. +If you do not use system properties or environment variables for configuration, runtime-level metrics and logs cannot be collected. Using other available MicroProfile Config properties cannot enable the collection of these metrics and logs. To enable the OpenTelemetry SDK, use the following configuration. @@ -258,6 +257,13 @@ To enable the OpenTelemetry SDK, use the following configuration. otel.sdk.disabled=false ---- +To set the name of the service, use the following configuration. +[source,properties] +---- +otel.service.name=app1 +---- + + === Accessing the Metrics API You can use the OpenTelemetry Metrics API to define custom metrics within your application code. By enabling the MicroProfile Telemetry feature version 2.0 or later, you can collect and emit these custom metrics to customize the observability of your application. From 4f5c7fb8c5ab8aae34f1383bb385f9ff73226f75 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Wed, 13 Nov 2024 23:11:27 +0530 Subject: [PATCH 22/81] 7654-Documentation-MicroProfile-OpenAPI-4.0-4 7654-Documentation-MicroProfile-OpenAPI-4.0-4 #7654 --- modules/ROOT/pages/documentation-openapi.adoc | 6 +++--- modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/documentation-openapi.adoc b/modules/ROOT/pages/documentation-openapi.adoc index b8a723699..9796256d9 100644 --- a/modules/ROOT/pages/documentation-openapi.adoc +++ b/modules/ROOT/pages/documentation-openapi.adoc @@ -221,9 +221,9 @@ For example, to include all deployed applications and modules except the `admin` If the application is deployed in the `dropins` directory or if the `name` attribute is not specified, the name defaults to the archive filename with the extension removed. + - The module name is specified in the web module's `web.xml` file. If there is no `web.xml` file or if it does not specify a name, the module name defaults to the filename with the extension removed. -+ + You can also override the `info` section of the OpenAPI document using the following configuration: -+ + [source,xml] ---- @@ -232,7 +232,7 @@ You can also override the `info` section of the OpenAPI document using the follo description="This is an example API"/> ---- -+ + This override may be useful when documenting multiple modules or applications. Without it, the `info` section would be replaced with a standard one indicating that documentation from several modules was merged. diff --git a/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc b/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc index 79956a5dc..c4f02784b 100644 --- a/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc +++ b/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc @@ -37,7 +37,7 @@ For example, the following configuration is for the `sample_app` application, wh For more information, see xref:ROOT:documentation-openapi.adoc#multi-module[Multiple application and multi-module application support with MicroProfile OpenAPI] -== mpOpenAPI-4.0 - Will be placed in another doc (Placed here for REVIEW) +=== mpOpenAPI-4.0 - Will be placed in another doc (Placed here for REVIEW) By default, all deployed applications and modules are included in the OpenAPI documentation. However, you can configure which applications and modules should be included. From c765d89ae5f3fe621f3534becedd725da837f314 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Thu, 14 Nov 2024 13:03:52 +0530 Subject: [PATCH 23/81] 7610-MicroProfile 7.0 ID-3 7610-MicroProfile 7.0 ID-3 #7610 --- modules/reference/pages/diff/mp-61-70-diff.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/reference/pages/diff/mp-61-70-diff.adoc b/modules/reference/pages/diff/mp-61-70-diff.adoc index b006dbe4d..91747b7cc 100644 --- a/modules/reference/pages/diff/mp-61-70-diff.adoc +++ b/modules/reference/pages/diff/mp-61-70-diff.adoc @@ -123,7 +123,7 @@ You can control which applications are included in the documentation using the f ---- -For more information, see . +For more information on this configuration, see feature:mpOpenAPI-3.1[display=MicroProfile OpenAPI 3.1] feature. @@ -283,9 +283,9 @@ To make the APIs accessible, you must enable third-party APIs for your applicati You can enable MicroProfile Telemetry to collect logs from various sources within the Open Liberty runtime environment. MicroProfile Telemetry can collect the following types of events: -- xref:mptel-log-events-list.adoc#me[Message events] -- xref:mptel-log-events-list.adoc#te[Trace events] -- xref:mptel-log-events-list.adoc#ffdce[FFDC events] +- xref:ROOT:mptel-log-events-list.adoc#me[Message events] +- xref:ROOT:mptel-log-events-list.adoc#te[Trace events] +- xref:ROOT:mptel-log-events-list.adoc#ffdce[FFDC events] To enable these log sources, configure the source attribute for the mpTelemetry element with a comma-separated list of the desired log sources: From e839f15ef012093e229b69bc9e26444c78fece79 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Thu, 14 Nov 2024 15:24:44 -0500 Subject: [PATCH 24/81] revert 240012 changes --- modules/ROOT/pages/password-encryption.adoc | 2 +- modules/reference/pages/command/securityUtility-encode.adoc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/password-encryption.adoc b/modules/ROOT/pages/password-encryption.adoc index 61fe3132e..dd7575680 100644 --- a/modules/ROOT/pages/password-encryption.adoc +++ b/modules/ROOT/pages/password-encryption.adoc @@ -18,7 +18,7 @@ Open Liberty supports Advanced Encryption Standard (AES) encryption for passwords that are stored in the `server.xml` file. When you use this option for protecting passwords in the Open Liberty configuration, understand the limitations to the protection that AES encryption provides. -The Open Liberty `securityUtility encode` command uses AES-256 encryption when the `--encoding` option is set to `aes`. The default value for this option is `xor`. For AES decryption, Open Liberty supports both AES-128 and AES-256. +The Open Liberty `securityUtility encode` command uses AES-128 encryption when the `--encoding` option is set to `aes`. The default value for this option is `xor`. For AES decryption, Open Liberty supports AES-128. Encrypting a password in the Open Liberty configuration does not guarantee that the password is secure or protected. Encrypting a password means that someone who can see the encrypted password cannot easily recover the password unless they know the encryption key. diff --git a/modules/reference/pages/command/securityUtility-encode.adoc b/modules/reference/pages/command/securityUtility-encode.adoc index a40ab9cf8..6a71e7801 100644 --- a/modules/reference/pages/command/securityUtility-encode.adoc +++ b/modules/reference/pages/command/securityUtility-encode.adoc @@ -61,7 +61,7 @@ securityUtility encode [options] |Specifies how to encode the password. Supported encodings types are `xor`, `aes`, and `hash`. The default value for this option is `xor`. -The `aes` type uses AES-256 encryption. +The `aes` type uses AES-128 encryption. {empty} + {empty} + You can use the `hash` encoding type to encode passwords for a xref:ROOT:user-registries-application-security.adoc[basic user registry] or passwords for the xref:config/quickStartSecurity.adoc[quickStartSecurity element]. From 74a4ed1f955080461594aef45e2c55e5c36c7c40 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Thu, 14 Nov 2024 16:15:00 -0500 Subject: [PATCH 25/81] add no proxy #7442 --- modules/reference/pages/command/featureUtility-commands.adoc | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/modules/reference/pages/command/featureUtility-commands.adoc b/modules/reference/pages/command/featureUtility-commands.adoc index b32deb954..91c9d4cad 100644 --- a/modules/reference/pages/command/featureUtility-commands.adoc +++ b/modules/reference/pages/command/featureUtility-commands.adoc @@ -64,6 +64,10 @@ The following table lists the environment variables and their corresponding prop a|Specifies how features must be verified during a process or an installation. Supported values are `enforce`, `skip`, `all`, and `warn`. If this option is not specified, the default value is `enforce`. +|`NO_PROXY` +|`http.nonProxyHosts` +|Specifies a list of patterns separated by the `|` and `,``.` delimiters. The patterns can start or end with an asterisk (`*`) for wildcards. Any host that matches one of these patterns is reached through a direct connection instead of going through a proxy. + * `enforce`: Verifies the signatures of all Liberty features except for user features. It checks the integrity and authenticity of the features that are provided by the Liberty framework. * `skip`: Choosing this option skips the verification process altogether. No feature signatures are downloaded or checked. It expedites the installation process but must be used with caution, as it bypasses an important security step. * `all`: Verifies both the Liberty features and the user features. The features that are provided by the Liberty framework and any additional user features or components are checked for integrity. From 6cc91ced261e9b18e6bd71e1e1df985cdb058feb Mon Sep 17 00:00:00 2001 From: David Mueller Date: Thu, 14 Nov 2024 16:17:56 -0500 Subject: [PATCH 26/81] Update featureUtility-commands.adoc --- modules/reference/pages/command/featureUtility-commands.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/reference/pages/command/featureUtility-commands.adoc b/modules/reference/pages/command/featureUtility-commands.adoc index 91c9d4cad..854dcb75e 100644 --- a/modules/reference/pages/command/featureUtility-commands.adoc +++ b/modules/reference/pages/command/featureUtility-commands.adoc @@ -66,7 +66,7 @@ Supported values are `enforce`, `skip`, `all`, and `warn`. If this option is not |`NO_PROXY` |`http.nonProxyHosts` -|Specifies a list of patterns separated by the `|` and `,``.` delimiters. The patterns can start or end with an asterisk (`*`) for wildcards. Any host that matches one of these patterns is reached through a direct connection instead of going through a proxy. +|Specifies a list of patterns separated by pipe (`|`), comma (`,`), or period (`.`) delimiters. Patterns can start or end with an asterisk (`*`) for wildcards. Open Liberty connects to any host that matches one of these patterns through a direct connection instead of going through a proxy. * `enforce`: Verifies the signatures of all Liberty features except for user features. It checks the integrity and authenticity of the features that are provided by the Liberty framework. * `skip`: Choosing this option skips the verification process altogether. No feature signatures are downloaded or checked. It expedites the installation process but must be used with caution, as it bypasses an important security step. From 7caec2a14604aa5a0facbecf623ccaded7b1898d Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Fri, 15 Nov 2024 15:15:26 +0530 Subject: [PATCH 27/81] 7654-Documentation-MicroProfile-OpenAPI-4.0-5 7654-Documentation-MicroProfile-OpenAPI-4.0-5 #7654 --- modules/reference/pages/feature/mpOpenAPI-2.0/examples.adoc | 2 -- modules/reference/pages/feature/mpOpenAPI-3.0/examples.adoc | 2 -- modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc | 2 -- modules/reference/pages/feature/mpOpenAPI-4.0/examples.adoc | 1 - 4 files changed, 7 deletions(-) diff --git a/modules/reference/pages/feature/mpOpenAPI-2.0/examples.adoc b/modules/reference/pages/feature/mpOpenAPI-2.0/examples.adoc index 7fb328ef1..4bf454f5d 100644 --- a/modules/reference/pages/feature/mpOpenAPI-2.0/examples.adoc +++ b/modules/reference/pages/feature/mpOpenAPI-2.0/examples.adoc @@ -1,6 +1,4 @@ -== Examples - === Configure OpenAPI documentation for a multi-module application // This example only applies to 2.0 forward, and so the file and directory must be manually copied and applied to any new versions. Copy the directory and file and change the directory name to reflect the new feature version, for example `mpOpenAPI-3.2`. diff --git a/modules/reference/pages/feature/mpOpenAPI-3.0/examples.adoc b/modules/reference/pages/feature/mpOpenAPI-3.0/examples.adoc index 1de816747..5d185557c 100644 --- a/modules/reference/pages/feature/mpOpenAPI-3.0/examples.adoc +++ b/modules/reference/pages/feature/mpOpenAPI-3.0/examples.adoc @@ -1,6 +1,4 @@ -== Examples - === Configure OpenAPI documentation for a multi-module application // This example only applies to 2.0 forward, and so the file and directory must be manually copied and applied to any new versions. Copy the directory and file and change the directory name to reflect the new feature version, for example `mpOpenAPI-3.2`. diff --git a/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc b/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc index c4f02784b..c527d1fd3 100644 --- a/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc +++ b/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc @@ -1,6 +1,4 @@ -== Examples - === Configure OpenAPI documentation for a multi-module application // This example only applies to 2.0 forward, and so the file and directory must be manually copied and applied to any new versions. Copy the directory and file and change the directory name to reflect the new feature version, for example `mpOpenAPI-3.2`. diff --git a/modules/reference/pages/feature/mpOpenAPI-4.0/examples.adoc b/modules/reference/pages/feature/mpOpenAPI-4.0/examples.adoc index 67154cd09..cc3d7831c 100644 --- a/modules/reference/pages/feature/mpOpenAPI-4.0/examples.adoc +++ b/modules/reference/pages/feature/mpOpenAPI-4.0/examples.adoc @@ -1,5 +1,4 @@ -== Examples === Configure OpenAPI documentation for a multi-module application From 6263006cee3e30ff85b8fd9627970b09cc9cbff2 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Fri, 15 Nov 2024 15:21:17 +0530 Subject: [PATCH 28/81] 7610-MicroProfile 7.0 ID-4 7610-MicroProfile 7.0 ID-4 #7610 --- modules/reference/pages/diff/mp-61-70-diff.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/reference/pages/diff/mp-61-70-diff.adoc b/modules/reference/pages/diff/mp-61-70-diff.adoc index 91747b7cc..b205260c8 100644 --- a/modules/reference/pages/diff/mp-61-70-diff.adoc +++ b/modules/reference/pages/diff/mp-61-70-diff.adoc @@ -123,7 +123,7 @@ You can control which applications are included in the documentation using the f ---- -For more information on this configuration, see feature:mpOpenAPI-3.1[display=MicroProfile OpenAPI 3.1] feature. +For more information on this configuration, see feature:mpOpenAPI-4.0[display=MicroProfile OpenAPI 4.0] feature. From 801e9f840b49d2a15d7ae677de626e8721363066 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Fri, 15 Nov 2024 10:47:47 -0500 Subject: [PATCH 29/81] edits --- .../reference/pages/command/featureUtility-commands.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/reference/pages/command/featureUtility-commands.adoc b/modules/reference/pages/command/featureUtility-commands.adoc index 854dcb75e..9c5f38e8a 100644 --- a/modules/reference/pages/command/featureUtility-commands.adoc +++ b/modules/reference/pages/command/featureUtility-commands.adoc @@ -64,15 +64,15 @@ The following table lists the environment variables and their corresponding prop a|Specifies how features must be verified during a process or an installation. Supported values are `enforce`, `skip`, `all`, and `warn`. If this option is not specified, the default value is `enforce`. -|`NO_PROXY` -|`http.nonProxyHosts` -|Specifies a list of patterns separated by pipe (`|`), comma (`,`), or period (`.`) delimiters. Patterns can start or end with an asterisk (`*`) for wildcards. Open Liberty connects to any host that matches one of these patterns through a direct connection instead of going through a proxy. - * `enforce`: Verifies the signatures of all Liberty features except for user features. It checks the integrity and authenticity of the features that are provided by the Liberty framework. * `skip`: Choosing this option skips the verification process altogether. No feature signatures are downloaded or checked. It expedites the installation process but must be used with caution, as it bypasses an important security step. * `all`: Verifies both the Liberty features and the user features. The features that are provided by the Liberty framework and any additional user features or components are checked for integrity. * `warn`: Similar to the `all` option, warn also verifies both the Liberty features and user features. This option allows the process to continue, even if some feature signatures cannot be validated. A verification failure does not immediately end the installation process, but it results in a warning message. +|`NO_PROXY` +|`http.nonProxyHosts` +|Requires Open Liberty to use a direct connection instead of a proxy for certain hosts. Specify a list of hostname patterns separated by pipe (`\|`), comma (`,`), or period (`.`) delimiters. Patterns can start or end with an asterisk (`*`) for wildcards. For any hostname that matches a specified pattern, Open Liberty connects to the host directly instead of going through a proxy. + |`http_proxy` |`proxyHost`, `proxyPort`, `proxyUser`, and `proxyPassword` a|Configures the outbound HTTP proxy. From a57f3fa161ac799e5bbedf944addae0d99b04b95 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Fri, 15 Nov 2024 12:16:37 -0500 Subject: [PATCH 30/81] edits #7655 --- .../introduction-monitoring-metrics.adoc | 12 +++---- .../ROOT/pages/microprofile-telemetry.adoc | 31 ++++++++++--------- .../ROOT/pages/mptelemetry-metrics-list.adoc | 4 +-- 3 files changed, 23 insertions(+), 24 deletions(-) diff --git a/modules/ROOT/pages/introduction-monitoring-metrics.adoc b/modules/ROOT/pages/introduction-monitoring-metrics.adoc index eabc13614..a7ccaf023 100644 --- a/modules/ROOT/pages/introduction-monitoring-metrics.adoc +++ b/modules/ROOT/pages/introduction-monitoring-metrics.adoc @@ -10,20 +10,18 @@ :page-type: general :page-description: With Open Liberty, three types of metrics are available to monitor your applications: OpenTelemetry metrics provided by MicroProfile Telemetry, REST endpoint-style metrics that are provided by MicroProfile Metrics, and Java Management Extensions (JMX) metrics. :seo-title: Monitoring with metrics - OpenLiberty.io -:seo-description: With Open Liberty, three types of metrics are available to monitor your applications: OpenTelemetry metrics provided by MicroProfile Telemetry, REST endpoint-style metrics that are provided by MicroProfile Metrics, and Java Management Extensions (JMX) metrics.. +:seo-description: With Open Liberty, three types of metrics are available to monitor your applications: OpenTelemetry metrics provided by MicroProfile Telemetry, REST endpoint-style metrics that are provided by MicroProfile Metrics, and Java Management Extensions (JMX) metrics..\ = Monitoring with metrics -Three kinds of metrics are available to monitor your Open Liberty applications: OpenTelemetry metrics from MicroProfile Telemetry, REST endpoint-style metrics from MicroProfile Metrics, and Java Management Extensions (JMX) metrics. MicroProfile Metrics and JMX metrics can be used separately or in conjunction to improve the observability of your application systems. +Three kinds of metrics are available to monitor your Open Liberty applications: OpenTelemetry metrics from MicroProfile Telemetry, REST endpoint-style metrics from MicroProfile Metrics, and Java Management Extensions (JMX) metrics. OpenTelemetry provides a standardized solution to manage metrics, logs, and traces.MicroProfile Metrics and JMX metrics can be used separately or in conjunction to improve the observability of your application systems. -MicroProfile Telemetry 2.0 and later exports metrics to OTLP or another configured OpenTelemetry metrics exporter. You might prefer this option if you also use MicroProfile Telemetry to manage your logs and traces. +MicroProfile Telemetry 2.0 and later exports metrics to the configured OpenTelemetry metrics exporter, which can send metrics to the backend service of your choice. You might prefer this option if you also use MicroProfile Telemetry to manage your logs and traces. The following information pertains to MicroProfile Metrics and JMX Metrics. For information about using OpenTelemetry and MicroProfile Telemetry to collect and export metrics, see xref:microprofile-telemetry.adoc[OpenTelemetry]. + MicroProfile Metrics can be accessed by monitoring tools, such as Prometheus, or by any client that can make REST requests. <<#jmx,JMX metrics>> are suitable for use by Java-based monitoring tools that can communicate with JMX servers, or by custom JMX clients. -[#mptelem] -== Collect and export metrics with MicroProfile Telemetry -When you enable the MicroProfile Telemetry feature version 2.0 and later, you can manage your logs, metrics, and traces in a standardized way with the OpenTelemetry protocol. For more information, see xref:microprofile-telemetry.adoc[Enable observability with MicroProfile Telemetry]. - + the [#endpoint] == MicroProfile Metrics and the metrics endpoint Open Liberty uses MicroProfile Metrics to expose metrics that describe the internal state of many Open Liberty components. Developers can also use the MicroProfile Metrics API to expose metrics from their applications. diff --git a/modules/ROOT/pages/microprofile-telemetry.adoc b/modules/ROOT/pages/microprofile-telemetry.adoc index 197a0e938..e632e4deb 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -12,31 +12,31 @@ :page-type: general = OpenTelemetry -The OpenTelemetry project is a collection of open source, vendor-independent resources for collecting and managing application telemetry data. With Open Liberty and MicroProfile Telemetry 2.0 and later, you can manage this data in a standardized way by using the OpenTelemetry protocol. +The OpenTelemetry project is a collection of open source, vendor-independent resources for collecting and managing application telemetry data. With Open Liberty and MicroProfile Telemetry 2.0 and later, you can manage logs, metrics, and traces in a standardized way by using the OpenTelemetry protocol. -OpenTelemetry provides a link:https://opentelemetry.io/docs/collector/[collector] component that can receive telemetry data from your applications and export it to backend services of your choice for visualization and monitoring. By default, all OpenTelemetry data is exported to the Open Telemetry Protocol (OTLP). OTLP defines the encoding of telemetry data and the protocol that is used to exchange data between a client and server. Many backend services accept OTLP data without requiring conversion, but OpenTelemtry also provides a collection of service-specific exporters for popular open source and commercial services, such as Jaeger, Zipkin, and Prometheus. You can configure global or data-specific exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. +OpenTelemetry provides a link:https://opentelemetry.io/docs/collector/[collector] component that can receive telemetry data from your applications and export it to backend services of your choice for monitoring and analysis. By default, all OpenTelemetry data is exported to the Open Telemetry Protocol (OTLP). OTLP defines the encoding of telemetry data and the protocol that is used to exchange data between a client and server. Many backend services accept OTLP data without requiring conversion, but OpenTelemtry also provides a collection of service-specific exporters for popular open source and commercial services, such as https://www.elastic.co/observability/log-monitoring[Elastic], link:https://zipkin.io/[Zipkin], and link:https://prometheus.io/[Prometheus]. You can configure global or data-specific exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. -OpenTelemetry is implemented in Open Liberty through the feature:mptelemtry[display=MicroProfile Telemetry] feature, which enables a collector that you can configure with MicroProfile Config properties and other system properties or environment variables. When you enable the MicroProfile Telemetry feature 2.0 or later and specify the required configuration property, Open Liberty automatically collects and exports logs, traces, and metrics at the application or runtime level. For many common application scenarios, no changes are needed in your application code to collect this data. MicroProfile Telemetry1.1 and earlier enables only the collection of traces and only at the application level. +OpenTelemetry is implemented in Open Liberty through the feature:mptelemtry[display=MicroProfile Telemetry] feature. When you enable the MicroProfile Telemetry feature 2.0 or later and specify the required configuration property, Open Liberty automatically collects and exports logs, traces, and metrics at the application or runtime level. For many common application scenarios, no changes are needed in your application code to collect this data. MicroProfile Telemetry1.1 and earlier enables only the collection of traces and only at the application level. [#global] == Collecting and exporting logs, metrics, and traces with OpenTelemetry -To collect and export logs, metrics, and traces with OpenTelemetry in your Open Liberty runtime, you must add the MicroProfile Telemetry feature to your `server.xml` file and specify the `otel.sdk.disabled=false` system property in one of the valid configuration sources. Depending on whether your runtime hosts a single application or multiple applications, you can specify this property at the runtime level or the application level. In most cases, runtime-level configuration is preferred as it includes both runtime-level telemetry and application-specific telemetry. The following table summarizes the benefits and use cases for each option. +To collect and export logs, metrics, and traces with OpenTelemetry in your Open Liberty runtime, you must add the MicroProfile Telemetry feature to your `server.xml` file and specify the `otel.sdk.disabled=false` system property in one of the valid configuration sources. Depending on whether your runtime hosts a single application or multiple applications, you can specify this property at the runtime level or the application level. In most cases, runtime-level configuration is preferred because it includes both runtime-level telemetry and application-specific telemetry. The following table summarizes the benefits and use cases for each option. .OpenTelemetry configuration options [options="header"cols="4,2,6a,3a"] |=== -|Use case| Configuration level | Description | Configuration sources +|Configuration level | Use case | Description | Configuration sources -| One application per Liberty runtime | Runtime level +| One application per Liberty runtime | Collects and emits telemetry from both the runtime and the application. | * `bootstrap.properties` file * `jvm.options` file * `server.env` file -| Multiple applications in the same Liberty runtime | Application level +| Multiple applications in the same Liberty runtime | Collects and emits telemetry for a single application and does not include runtime-level data. Provides fine-grained control over data collection for each application. | * `microprofile-config.properties` file * `appProperties` attribute for the config:application[] element in the `server.xml` file. @@ -66,7 +66,7 @@ After you enable the MicroProfile Telemetry feature and set this system property === Enabling OpenTelemetry for multiple applications in the same Open Liberty runtime -When your Liberty runtime hosts multiple applications, you can enable OpenTelemetry to collect logs, metrics, and traces at the application level for each application. Although this option does not collect runtime-level telemetry, it gives you fine-grained control of the data you collect for each application. +When your Liberty runtime hosts multiple applications, you might choose to enable OpenTelemetry to collect logs, metrics, and traces at the application level for each application. Although this option does not collect runtime-level telemetry, it gives you fine-grained control of the data you collect for each application. * Enable the feature:mpTelemetry[display=MicroProfile Telemetry] feature version 2.0 or later in the `featureManager` element of the `server.xml` file of each application that you want to collect telemetry for. + @@ -120,31 +120,32 @@ After you enable the MicroProfile Telemetry feature and set the `otel.sdk.disabl [#config] == OpenTelemetry settings and configuration -When you enable OpenTelemetry for Open Liberty, by default, all telemetry data is exported to the Open Telemetry Protocol (OTLP) at the `\http://localhost:4317` endpoint. You can configure alternative global or data-specific exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. Open Liberty supports all link:https://opentelemetry.io/docs/languages/java/configuration/#environment-variables-and-system-properties[OpenTelemtry Java configuration properties]. +When you enable OpenTelemetry for Open Liberty, by default, all telemetry data is to the link:https://github.com/open-telemetry/oteps/blob/main/text/0035-opentelemetry-protocol.md[Open Telemetry Protocol] (OTLP) at the `\http://localhost:4317` endpoint. You can configure alternative global or data-specific exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. Open Liberty supports all link:https://opentelemetry.io/docs/languages/java/configuration/#environment-variables-and-system-properties[OpenTelemtry Java configuration properties]. -For information about commonly-used configuration properties for global, logs, metrics, and trace settings, see xref:reference:microprofile-config-properties.adoc#telemetry[MicroProfile Config properties: MicroProfile Telemetry]. +For information about commonly-used configuration properties for logs, metrics, and trace settings, see xref:reference:microprofile-config-properties.adoc#telemetry[MicroProfile Config properties: MicroProfile Telemetry]. [#traces] === Trace When you enable OpenTelemetry for Open Liberty, Jakarta RESTful Web Services and JAX-RS applications are instrumented for trace by default. Spans are automatically generated for incoming HTTP requests, including static files, servlets, and JSPs. These spans are automatically exported according to the configured OpenTelemetry settings. -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 OpenTelemetry API. Alternatively, you can attach the OpenTelemetry Java agent to any Java 8+ application. For more information about these options, see xref:telemetry-trace.adoc#t[Code instrumentation for MicroProfile Telemetry tracing]. +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 OpenTelemetry API. Alternatively, you can attach the OpenTelemetry Java agent to any Java 8+ application. For more information about these options, see xref:telemetry-trace.adoc[Code instrumentation for MicroProfile Telemetry tracing]. [#logs] === Logs -OpenTelemetry automatically collects any logs that are sent to the `java.util.logging` API. Any messages that are logged at a `java.util.logging.Level` log level of `INFO` and above are considered messages. Levels below `INFO` are considered trace. By default, OpenTelemetry automatically collects messages, but you can configure the sources that it collects from in your `server.xml` file. For more information, see link:/docs/latest/reference/feature/mpTelemetry-2.0.html#_collect_logs_from_a_specified_source[Collect logs from a specified source]. +OpenTelemetry automatically collects any logs that are sent to the `java.util.logging` API. Any messages that are logged at a `java.util.logging.Level` log level of `INFO` and above are considered messages. Levels below `INFO` are considered trace. By default, OpenTelemetry logging automatically collects messages, but you can configure it to collect from other sources in your `server.xml` file. For more information, see link:/docs/latest/reference/feature/mpTelemetry-2.0.html#_collect_logs_from_a_specified_source[Collect logs from a specified source]. -For information about Liberty message event fields for OpenTelemetry, see xref:mptel-log-events-list.adoc[MicroProfile Telemetry log events reference list]. +For information about Liberty log event fields for OpenTelemetry, see xref:mptel-log-events-list.adoc[MicroProfile Telemetry log events reference list]. +//// By default, the OpenTelemetry Simple logRecord Processor is enabled, so the records are sent immediately. However, if you want to send the records in batches, you can also configure the logging-specific Batch LogRecord Processor properties. - +//// [#metrics] === Metrics -For a list of metrics that are available for Open Liberty when you enable the MicroProfile Telemetry feature 2.0 or later, see xref:mptelemetry-metrics-list.adoc[MicroProfile Telemetry metrics reference list]. You can also xref:custom-mptelemetry-metrics.adoc[define custom metrics in your application code]. +When you enable OpenTelemetry for Open Liberty, a default set of metrics is automatically collected and exported according to the configured OpenTelemetry settings. For more information about these metrics, see xref:mptelemetry-metrics-list.adoc[MicroProfile Telemetry metrics reference list]. You can also define additional xref:custom-mptelemetry-metrics.adoc[custom metrics] in your application code. == See also diff --git a/modules/ROOT/pages/mptelemetry-metrics-list.adoc b/modules/ROOT/pages/mptelemetry-metrics-list.adoc index 79b23d104..4bc962ec7 100644 --- a/modules/ROOT/pages/mptelemetry-metrics-list.adoc +++ b/modules/ROOT/pages/mptelemetry-metrics-list.adoc @@ -32,7 +32,7 @@ Use metric data to effectively monitor the status of your microservice systems. You can obtain metrics from applications, the Open Liberty runtime, and the Java virtual machine (JVM). They can be gathered and stored in database tools, such as link:https://prometheus.io/[Prometheus], and displayed on dashboards, such as link:https://grafana.com/[Grafana]. -When you enable the feature:mpTelemetry-2.0[display=MicroProfile Telemetry] feature version 2.0 and later, you can manage your logs, metrics, and traces in a standardized way with the OpenTelemetry protocol. For more information, see xref:microprofile-telemetry[Enable observability with MicroProfile Telemetry]. +When you enable the feature:mpTelemetry-2.0[display=MicroProfile Telemetry] feature version 2.0 and later, you can manage your logs, metrics, and traces in a standardized way with the OpenTelemetry protocol. For more information, see xref:microprofile-telemetry[OpenTelemetry]. == Filter metrics to gather only the data you need @@ -62,7 +62,7 @@ To disable all monitoring components, add the following code to your `server.xml == MicroProfile Telemetry 2.0 and later metrics reference -When the MicroProfile Telemetry feature 2.0 and later is enabled, Open Liberty can send metric data to compatible OpenTelemetry protocol (OTLP) receivers. For more information, see xref:microprofile-telemetry[Enable observability with MicroProfile Telemetry]. +When the MicroProfile Telemetry feature 2.0 and later is enabled, Open Liberty can send metric data to compatible OpenTelemetry protocol (OTLP) receivers. The table lists the metric types, descriptions and attributes that are available for Open Liberty. Where applicable, the associated monitoring component that you can use to filter the metric is also included. The **Features required** column of the table includes the feature or features that must be enabled to obtain that metric data. From b6f620cad62b9d8e5662f25ea4333cbc4dd83402 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Fri, 15 Nov 2024 15:26:34 -0500 Subject: [PATCH 31/81] edits #7655 --- .../pages/custom-mptelemetry-metrics.adoc | 4 +-- .../ROOT/pages/microprofile-telemetry.adoc | 18 +++++----- modules/ROOT/pages/microprofile.adoc | 2 +- modules/ROOT/pages/mptel-log-events-list.adoc | 2 +- modules/ROOT/pages/mptelemetry-logging.adoc | 2 +- modules/ROOT/pages/observability.adoc | 2 +- modules/ROOT/pages/telemetry-trace.adoc | 4 +-- .../ROOT/pages/telemetry-troubleshooting.adoc | 34 +++++++++++++++++-- .../reference/pages/diff/mp-50-60-diff.adoc | 4 +-- .../feature/mpTelemetry-2.0/examples.adoc | 9 ++--- .../feature/mpTelemetry/description.adoc | 2 +- .../pages/microprofile-config-properties.adoc | 21 +++++++----- 12 files changed, 68 insertions(+), 36 deletions(-) diff --git a/modules/ROOT/pages/custom-mptelemetry-metrics.adoc b/modules/ROOT/pages/custom-mptelemetry-metrics.adoc index d92a5bbf3..76ceae8c4 100644 --- a/modules/ROOT/pages/custom-mptelemetry-metrics.adoc +++ b/modules/ROOT/pages/custom-mptelemetry-metrics.adoc @@ -14,11 +14,11 @@ You can use the OpenTelemetry metrics API to define custom metrics in your application code. When you enable the MicroProfile Telemetry feature 2.0 or later, you can then collect and emit these metrics to customize the observability of your application. -For more information about collecting and emitting metrics with MicroProfile Telemetry, see xref:microprofile-telemetry.adoc#metrics[Configuring Open Liberty to use MicroProfile Telemetry to collect metrics]. +For more information about collecting and emitting metrics with MicroProfile Telemetry, see xref:microprofile-telemetry.adoc[OpenTelemetry]. For more information about OpenTelemetry metrics, see the link:https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/1.39.0/io/opentelemetry/api/metrics/package-summary.html[OpenTelemetry metrics API documentation]. -Before you can use MicroProfile Telemetry to define custom metrics metrics, you must enable MicroProfile Telemetry in your development environment by editing your runtime configuration. You must also add the OpenTelemetry API and annotations as a dependency on your build path. For more information, see xref:prepare-mptelemetry.adoc[Prepare your development environment for MicroProfile Telemetry]. +Before you can use MicroProfile Telemetry to define custom metrics metrics, you must enable MicroProfile Telemetry in your development environment by editing your runtime configuration. You must also add the OpenTelemetry API and annotations as a dependency on your build path. For more information, see link:{url-prefix}/docs/latest/reference/feature/mpTelemetry-2.0.html#dev[Prepare your development environment for MicroProfile Telemetry]. The following example defines a custom counter metric: diff --git a/modules/ROOT/pages/microprofile-telemetry.adoc b/modules/ROOT/pages/microprofile-telemetry.adoc index e632e4deb..320a796b7 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -1,4 +1,4 @@ -// Copyright (c) 2022 IBM Corporation and others. +// Copyright (c) 2024 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/ @@ -14,7 +14,7 @@ The OpenTelemetry project is a collection of open source, vendor-independent resources for collecting and managing application telemetry data. With Open Liberty and MicroProfile Telemetry 2.0 and later, you can manage logs, metrics, and traces in a standardized way by using the OpenTelemetry protocol. -OpenTelemetry provides a link:https://opentelemetry.io/docs/collector/[collector] component that can receive telemetry data from your applications and export it to backend services of your choice for monitoring and analysis. By default, all OpenTelemetry data is exported to the Open Telemetry Protocol (OTLP). OTLP defines the encoding of telemetry data and the protocol that is used to exchange data between a client and server. Many backend services accept OTLP data without requiring conversion, but OpenTelemtry also provides a collection of service-specific exporters for popular open source and commercial services, such as https://www.elastic.co/observability/log-monitoring[Elastic], link:https://zipkin.io/[Zipkin], and link:https://prometheus.io/[Prometheus]. You can configure global or data-specific exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. +OpenTelemetry provides a link:https://opentelemetry.io/docs/collector/[collector] component that can receive telemetry data from your applications and export it to backend services of your choice for monitoring and analysis. By default, all OpenTelemetry data is exported to the Open Telemetry Protocol (OTLP). OTLP defines the encoding of telemetry data and the protocol that is used to exchange data between a client and server. Many backend services accept OTLP data without requiring conversion, but OpenTelemtry also provides a collection of service-specific exporters for popular open source and commercial services, such as link:https://zipkin.io/[Zipkin] and link:https://prometheus.io/[Prometheus]. You can configure global or data-specific exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. OpenTelemetry is implemented in Open Liberty through the feature:mptelemtry[display=MicroProfile Telemetry] feature. When you enable the MicroProfile Telemetry feature 2.0 or later and specify the required configuration property, Open Liberty automatically collects and exports logs, traces, and metrics at the application or runtime level. For many common application scenarios, no changes are needed in your application code to collect this data. MicroProfile Telemetry1.1 and earlier enables only the collection of traces and only at the application level. @@ -34,6 +34,8 @@ To collect and export logs, metrics, and traces with OpenTelemetry in your Open | * `bootstrap.properties` file * `jvm.options` file * `server.env` file ++ +If you choose to use the `server.env` file, specify the `OTEL_SDK_DISABLED=false` enviroment variable instead of the configuration property. | Application level | Multiple applications in the same Liberty runtime @@ -120,20 +122,19 @@ After you enable the MicroProfile Telemetry feature and set the `otel.sdk.disabl [#config] == OpenTelemetry settings and configuration -When you enable OpenTelemetry for Open Liberty, by default, all telemetry data is to the link:https://github.com/open-telemetry/oteps/blob/main/text/0035-opentelemetry-protocol.md[Open Telemetry Protocol] (OTLP) at the `\http://localhost:4317` endpoint. You can configure alternative global or data-specific exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. Open Liberty supports all link:https://opentelemetry.io/docs/languages/java/configuration/#environment-variables-and-system-properties[OpenTelemtry Java configuration properties]. +By default, all OpenTelemetry data is exported to the link:https://github.com/open-telemetry/oteps/blob/main/text/0035-opentelemetry-protocol.md[Open Telemetry Protocol] (OTLP) at the `\http://localhost:4317` endpoint. You can configure alternative global or data-specific exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. Open Liberty supports all link:https://opentelemetry.io/docs/languages/java/configuration/#environment-variables-and-system-properties[OpenTelemtry Java configuration properties]. For information about commonly-used configuration properties for logs, metrics, and trace settings, see xref:reference:microprofile-config-properties.adoc#telemetry[MicroProfile Config properties: MicroProfile Telemetry]. [#traces] -=== Trace +=== Trace defaults When you enable OpenTelemetry for Open Liberty, Jakarta RESTful Web Services and JAX-RS applications are instrumented for trace by default. Spans are automatically generated for incoming HTTP requests, including static files, servlets, and JSPs. These spans are automatically exported according to the configured OpenTelemetry settings. 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 OpenTelemetry API. Alternatively, you can attach the OpenTelemetry Java agent to any Java 8+ application. For more information about these options, see xref:telemetry-trace.adoc[Code instrumentation for MicroProfile Telemetry tracing]. [#logs] -=== Logs - +=== Logs defaults OpenTelemetry automatically collects any logs that are sent to the `java.util.logging` API. Any messages that are logged at a `java.util.logging.Level` log level of `INFO` and above are considered messages. Levels below `INFO` are considered trace. By default, OpenTelemetry logging automatically collects messages, but you can configure it to collect from other sources in your `server.xml` file. For more information, see link:/docs/latest/reference/feature/mpTelemetry-2.0.html#_collect_logs_from_a_specified_source[Collect logs from a specified source]. For information about Liberty log event fields for OpenTelemetry, see xref:mptel-log-events-list.adoc[MicroProfile Telemetry log events reference list]. @@ -143,11 +144,12 @@ By default, the OpenTelemetry Simple logRecord Processor is enabled, so the reco //// [#metrics] -=== Metrics +=== Metrics defaults When you enable OpenTelemetry for Open Liberty, a default set of metrics is automatically collected and exported according to the configured OpenTelemetry settings. For more information about these metrics, see xref:mptelemetry-metrics-list.adoc[MicroProfile Telemetry metrics reference list]. You can also define additional xref:custom-mptelemetry-metrics.adoc[custom metrics] in your application code. == See also -https://opentelemetry.io/[OpenTelemetry project] +* xref:telemetry-troubleshooting.adoc[Troubleshooting OpenTelemetry] +* https://opentelemetry.io/[OpenTelemetry project] diff --git a/modules/ROOT/pages/microprofile.adoc b/modules/ROOT/pages/microprofile.adoc index d9ebe3281..5543b68d4 100644 --- a/modules/ROOT/pages/microprofile.adoc +++ b/modules/ROOT/pages/microprofile.adoc @@ -122,7 +122,7 @@ For more information, see xref:microservice-observability-metrics.adoc[Microserv === Enable distributed tracing of your microservices 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. -In Open Liberty, MicroProfile Telemetry is supported by the feature:mpTelemetry[display=MicroProfile Telemetry] feature. You can export the data that this feature collects to tracing systems such as Jaeger or Zipkin. For more information, see xref:microprofile-telemetry.adoc[Enable observability with MicroProfile Telemetry]. +In Open Liberty, MicroProfile Telemetry is supported by the feature:mpTelemetry[display=MicroProfile Telemetry] feature. You can export the data that this feature collects to tracing systems such as Jaeger or Zipkin. For more information, see xref:microprofile-telemetry.adoc[OpenTelemetry]. 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]. diff --git a/modules/ROOT/pages/mptel-log-events-list.adoc b/modules/ROOT/pages/mptel-log-events-list.adoc index 6778871dc..47f7aa9da 100644 --- a/modules/ROOT/pages/mptel-log-events-list.adoc +++ b/modules/ROOT/pages/mptel-log-events-list.adoc @@ -14,7 +14,7 @@ MicroProfile Telemetry can collect logging events from the server runtime and applications. You can use these events to gather and analyze data that can help to better understand the behavior of applications. -For more information, see xref:microprofile-telemetry.adoc[Enable observability with MicroProfile Telemetry]. +For more information, see xref:microprofile-telemetry.adoc[OpenTelemetry]. MicroProfile Telemetry can collect the following types of events: diff --git a/modules/ROOT/pages/mptelemetry-logging.adoc b/modules/ROOT/pages/mptelemetry-logging.adoc index fc33ea12c..f6ff5490f 100644 --- a/modules/ROOT/pages/mptelemetry-logging.adoc +++ b/modules/ROOT/pages/mptelemetry-logging.adoc @@ -16,4 +16,4 @@ You can use MicroProfile Telemetry to mange your logs, along with traces and met Any messages that are logged at a `java.util.logging.Level` log level of `INFO` and above are considered messages. Levels below `INFO` are considered trace. By default, MicroProfile Telemetry automatically collects messages, but you can configure the sources that it collects from in your `server.xml` file. For more information, see link:/docs/latest/reference/feature/mpTelemetry-2.0.html#_collect_logs_from_a_specified_source[Collect logs from a specified source]. -For more information about configuring MicroProfile Telemetry to collect and emit logs, metrics, and trace, see xref:microprofile-telemetry.adoc[Enable observability with MicroProfile Telemetry]. +For more information about configuring MicroProfile Telemetry to collect and emit logs, metrics, and trace, see xref:microprofile-telemetry.adoc[OpenTelemetry]. diff --git a/modules/ROOT/pages/observability.adoc b/modules/ROOT/pages/observability.adoc index fc71f777f..004b959cd 100644 --- a/modules/ROOT/pages/observability.adoc +++ b/modules/ROOT/pages/observability.adoc @@ -15,7 +15,7 @@ When applications are observable, operations teams can identify and understand the root causes of bugs, bottlenecks, and other inefficiencies. Open Liberty provides a robust framework for developing observable applications and integrates with numerous third-party monitoring tools. -With MicroProfile Telemetry 2.0 and later, you can manage logs, metrics, and traces in a standardized way by using the OpenTelemetry protocol. For more information, see xref:microprofile-telemetry.adoc[Enable observability with MicroProfile Telemetry]. +With MicroProfile Telemetry 2.0 and later, you can manage logs, metrics, and traces in a standardized way by using the OpenTelemetry protocol. For more information, see xref:microprofile-telemetry.adoc[OpenTelemetry]. The following topics provide information to help you develop observable applications with Open Liberty. diff --git a/modules/ROOT/pages/telemetry-trace.adoc b/modules/ROOT/pages/telemetry-trace.adoc index e0532f670..ad4f5cd30 100644 --- a/modules/ROOT/pages/telemetry-trace.adoc +++ b/modules/ROOT/pages/telemetry-trace.adoc @@ -21,7 +21,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 that you need to do is configure runtime as described in xref:microprofile-telemetry.adoc#traces[Configuring Open Liberty to use MicroProfile Telemetry to collect traces]. 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 that you need to do is configure runtime as described in xref:microprofile-telemetry.adoc[OpenTelemetry]. 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. @@ -30,7 +30,7 @@ In Open Liberty version 23.0.0.11 and later, spans are automatically generated f 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.39.0/io/opentelemetry/api/trace/package-summary.html[OpenTelemetry API]. -However, before you manually instrument your code, you must enable MicroProfile Telemetry in your development environment by editing your runtime configuration. You must also add the OpenTelemetry API and annotations as a dependency on your build path. For more information, see xref:prepare-mptelemetry.adoc[Prepare your development environment for MicroProfile Telemetry]. +However, before you manually instrument your code, you must enable MicroProfile Telemetry in your development environment by editing your runtime configuration. You must also add the OpenTelemetry API and annotations as a dependency on your build path. For more information, see link:{url-prefix}/docs/latest/reference/feature/mpTelemetry-2.0.html#dev[Prepare your development environment for MicroProfile Telemetry]. After you complete those prerequisites, you're ready to instrument your code. The following examples show configuration options with the OpenTelemetry API. diff --git a/modules/ROOT/pages/telemetry-troubleshooting.adoc b/modules/ROOT/pages/telemetry-troubleshooting.adoc index 5fa36ea47..432f7a069 100644 --- a/modules/ROOT/pages/telemetry-troubleshooting.adoc +++ b/modules/ROOT/pages/telemetry-troubleshooting.adoc @@ -1,4 +1,4 @@ -// Copyright (c) 2022 IBM Corporation and others. +// Copyright (c) 2024 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/ @@ -12,7 +12,37 @@ :page-type: general = Troubleshooting OpenTelemetry -The following information can help you determine the cause of common problems and error messages that are associated with OpenTelemetry logs, metrics, and tracing. +The following information can help you determine the cause of common problems and error messages that are associated with OpenTelemetry logs, metrics, and tracing. To debug issues with your OpenTelemetry logs, metrics, or traces, you can configure this data to export to the console. + + +== Exporting logs, metrics, or traces to the console for debugging purposes + +By default, all OpenTelemetry data is exported to the `otlp` exporter. For debugging purposes, you can temporarily change the export destination to the `console.log` file by setting the `otel.<_signal_>.exporter=console` property at the application or the runtime level. + +For example, to send all application and runtime traces to the `console.log` file, you might set the following property in the `bootstrap.properties` file: + +[source,properties] +---- +otel.traces.exporter=console +---- + +Similarly, to send all application and runtime logs to the `console.log` file, set the following property in the `bootstrap.properties` file: + +[source,properties] +---- +otel.logs.exporter=console +---- + +To send all application and runtime metrics to the `console.log` file, set the following property in the `bootstrap.properties` file: + +[source,properties] +---- +otel.metrics.exporter=console +---- + + +If you enabled OpenTelemetry at the application level, and you want to send only the logs, metrics, or traces for a particular application to the console, set the corresponding property in the `microprofile-config.properties` file for the application. + Previous spans are incorrectly shown as current or parent spans:: diff --git a/modules/reference/pages/diff/mp-50-60-diff.adoc b/modules/reference/pages/diff/mp-50-60-diff.adoc index 49da09bff..98294075c 100644 --- a/modules/reference/pages/diff/mp-50-60-diff.adoc +++ b/modules/reference/pages/diff/mp-50-60-diff.adoc @@ -130,7 +130,7 @@ In MicroProfile 6.0, MicroProfile Telemetry 1.0 replaces MicroProfile OpenTracin === Configuration changes -In addition to replacing the `mpOpenTracing-3.0` feature with the `mpTelemtry-1.0` feature in your `server.xml` file, you must provide configuration to allow the MicroProfile Telemetry feature to connect to your distributed trace service. For more information, see xref:ROOT:microprofile-telemetry.adoc[Enable observability with MicroProfile Telemetry]. +In addition to replacing the `mpOpenTracing-3.0` feature with the `mpTelemtry-1.0` feature in your `server.xml` file, you must provide configuration to allow the MicroProfile Telemetry feature to connect to your distributed trace service. For more information, see xref:ROOT:microprofile-telemetry.adoc[OpenTelemetry]. You do not need to package a client for your particular tracing service. MicroProfile Telemetry includes exporters for Zipkin, the OpenTelemetry Protocol (OTLP) (which is used by Jaeger since v1.35), and the older Jaeger protocol. If you need to export to a different service, you can provide a custom exporter by using the link:https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-sdk-extension-autoconfigure-spi/1.19.0/io/opentelemetry/sdk/autoconfigure/spi/traces/ConfigurableSpanExporterProvider.html[ConfigurableSpanExporterProvider service provider interface (SPI)]. @@ -188,7 +188,7 @@ Update your application dependencies to remove the OpenTracing API and add the O ---- -Just like the MicroProfile OpenTracing 3.0 feature (`mpOpenTracing-3.0`), the MicroProfile Telemetry 1.0 feature (`mpTelemetry-1.0`) feature requires that you xref:ROOT:microprofile-telemetry.adoc#manual[enable third-party APIs] to use the API classes in your application. +Just like the MicroProfile OpenTracing 3.0 feature (`mpOpenTracing-3.0`), the MicroProfile Telemetry 1.0 feature (`mpTelemetry-1.0`) feature requires that you enable third-party APIs to use the API classes in your application. The shim converts most calls to the OpenTracing API into calls to the OpenTelemetry API, but it doesn't make the OpenTracing `Tracer` class available for injection. To enable injection of the OpenTracing `Tracer` class, you also need to add a CDI Producer Method that uses the shim to provide instances of the class for injection. If CDI discovery is enabled, you can add the following class to your application: diff --git a/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc b/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc index 63feaa5eb..c99488860 100644 --- a/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc +++ b/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc @@ -45,12 +45,8 @@ If you need to xref:ROOT:telemetry-trace.adoc[manually instrument your code to c ---- -[#logs-settings] -=== Log settings -The following examples show common optional settings to configure the collection and export of OpenTelemetry log data. - [#logs] -==== Collect logs from a specified source +=== Collect logs from a specified source To enable the MicroProfile Telemetry feature to collect logs from different sources in the Open Liberty runtime environment, configure the `source` attribute for the `mpTelemetry` element with a comma-separated list of comma-separated log sources. @@ -66,8 +62,7 @@ To enable the MicroProfile Telemetry feature to collect logs from different sour * The attributes and values are case insensitive. -[#blrp] -==== Configure the OpenTelemetry Batch LogRecord Processor + diff --git a/modules/reference/pages/feature/mpTelemetry/description.adoc b/modules/reference/pages/feature/mpTelemetry/description.adoc index 37849acb5..fcdc56efb 100644 --- a/modules/reference/pages/feature/mpTelemetry/description.adoc +++ b/modules/reference/pages/feature/mpTelemetry/description.adoc @@ -1,3 +1,3 @@ For information about migrating from MicroProfile Open Tracing to MicroProfile Open Telemetry, see xref:diff/mp-50-60-diff.adoc#telemetry[Differences between MicroProfile Telemetry 1.0 and MicroProfile OpenTracing 3.0]. -For information about configuring MicroProfile Telemetry, see xref:ROOT:microprofile-telemetry.adoc[Enable observability with MicroProfile Telemetry]. +For information about configuring MicroProfile Telemetry, see xref:ROOT:microprofile-telemetry.adoc[OpenTelemetry]. diff --git a/modules/reference/pages/microprofile-config-properties.adoc b/modules/reference/pages/microprofile-config-properties.adoc index afc38fe2b..6f337706f 100644 --- a/modules/reference/pages/microprofile-config-properties.adoc +++ b/modules/reference/pages/microprofile-config-properties.adoc @@ -614,11 +614,11 @@ This property or `*/mp-rest/url` is considered required. However, some implement [#telemetry] == MicroProfile Telemetry -The following MicroProfile Config properties can be specified when MicroProfile Telemetry is enabled. This table lists the most important properties. For the full list, see the https://download.eclipse.org/microprofile/microprofile-telemetry-1.0/tracing/microprofile-telemetry-tracing-spec-1.0.html#_configuration[MicroProfile Telemetry specification]. +The following MicroProfile Config properties can be specified when MicroProfile Telemetry is enabled. This table lists the most important properties. For the full list, see the link:https://opentelemetry.io/docs/languages/java/configuration/#environment-variables-and-system-properties[OpenTelemtry Java configuration properties]. The runtime reads properties in the following table at either application startup or runtime startup, depending on when the OpenTelemetry instance initializes. In cases where each application is configured to use a separate OpenTelemetry instance, the runtime reads the properties at application startup. In cases where all applications on the runtime share a single OpenTelemetry instance, the runtime reads the properties at runtime startup. -For more information about collecting Open Liberty logs, metrics, and traces, see xref:ROOT:microprofile-telemetry.adoc[Enable observability with MicroProfile Telemetry]. +For more information about collecting Open Liberty logs, metrics, and traces, see xref:ROOT:microprofile-telemetry.adoc[OpenTelemetry]. .MicroProfile Config properties for MicroProfile Telemetry [options="header"] @@ -648,22 +648,22 @@ For more information about collecting Open Liberty logs, metrics, and traces, se |`otel.exporter.jaeger.endpoint` |Sets the endpoint for the Jaeger exporter. The default is \http://localhost:14250. |Application startup or runtime startup -|`otel.exporter.jaeger.endpoint=http://localhost:14250` +|`otel.exporter.jaeger.endpoint=http://localhost:14251` |`otel.exporter.jaeger.timeout` |Sets the maximum time, in milliseconds, that the Jaeger exporter waits for each batch export. The default is `10000`. |Application startup or runtime startup -|`otel.exporter.jaeger.timeout=10000` +|`otel.exporter.jaeger.timeout=20000` |`otel.exporter.otlp.endpoint` |Sets the endpoint for the OpenTelemetry Protocol (otlp) exporter. The default is \http://localhost:4317 |Application startup or runtime startup -|`otel.exporter.otlp.endpoint=http://localhost:4317` +|`otel.exporter.otlp.endpoint=http://localhost:4319` |`otel.exporter.zipkin.endpoint` |Sets the endpoint for the Zipkin exporter. The default is \http://localhost:9411/api/v2/spans. |Application startup or runtime startup -|`otel.exporter.zipkin.endpoint=http://localhost:9412/api/v2/spans` +|`otel.exporter.zipkin.endpoint=http://localhost:9413/api/v2/spans` |`otel.metric.export.interval` |By default, metric data is exported at an interval of 60000 milliseconds (one minute). To modify the export interval, specify the new value in milliseconds. For more information, see link:https://opentelemetry.io/docs/specs/otel/metrics/sdk/#periodic-exporting-metricreader[Periodic exporting MetricReader] in the OpenTelemetry documentation. @@ -686,13 +686,18 @@ For more information about collecting Open Liberty logs, metrics, and traces, se |`otel.service.name=system` |`otel.logs.exporter` -|You can use this property to change where the logs that MicroProfile Telemetry collects are exported. For more information, see xref:ROOT:microprofile-telemetry.adoc#logs[Configuring Open Liberty to use MicroProfile Telemetry to collect logs] +|You can use this property to change where the logs that MicroProfile Telemetry collects are exported. |Application startup or runtime startup |`otel.traces.exporter=console` +|`otel.metrics.exporter` +|You can use this property to change where the metrics that MicroProfile Telemetry collects are exported. +|Application startup or runtime startup +|`otel.metrics.exporter=prometheus` + |`otel.traces.exporter` |Sets the exporter that is used to collect traces. Possible values are `otlp`, `zipkin`, `jaeger`, or `logging`. The default value is `otlp`. For the Jaeger trace service versions 1.35 and later, the `otlp` exporter value is recommended, rather than `jaeger`. |Application startup or runtime startup -|`otel.traces.exporter=otlp` +|`otel.traces.exporter=zipkin` |=== From 81d535089f12b3f271cadd4e09d3770a662ced32 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Fri, 15 Nov 2024 15:28:46 -0500 Subject: [PATCH 32/81] Update custom-mptelemetry-metrics.adoc --- modules/ROOT/pages/custom-mptelemetry-metrics.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/custom-mptelemetry-metrics.adoc b/modules/ROOT/pages/custom-mptelemetry-metrics.adoc index 76ceae8c4..02557500b 100644 --- a/modules/ROOT/pages/custom-mptelemetry-metrics.adoc +++ b/modules/ROOT/pages/custom-mptelemetry-metrics.adoc @@ -18,7 +18,7 @@ For more information about collecting and emitting metrics with MicroProfile Tel For more information about OpenTelemetry metrics, see the link:https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/1.39.0/io/opentelemetry/api/metrics/package-summary.html[OpenTelemetry metrics API documentation]. -Before you can use MicroProfile Telemetry to define custom metrics metrics, you must enable MicroProfile Telemetry in your development environment by editing your runtime configuration. You must also add the OpenTelemetry API and annotations as a dependency on your build path. For more information, see link:{url-prefix}/docs/latest/reference/feature/mpTelemetry-2.0.html#dev[Prepare your development environment for MicroProfile Telemetry]. +Before you can use MicroProfile Telemetry to define custom metrics, you must enable MicroProfile Telemetry in your development environment by editing your runtime configuration. You must also add the OpenTelemetry API and annotations as a dependency on your build path. For more information, see xref:prepare-mptelemetry.adoc[Prepare your development environment for MicroProfile Telemetry]. The following example defines a custom counter metric: From e9e51a2363c16bb5692d84b7c6203cc8a657bff1 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Fri, 15 Nov 2024 15:29:18 -0500 Subject: [PATCH 33/81] Update custom-mptelemetry-metrics.adoc --- modules/ROOT/pages/custom-mptelemetry-metrics.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/custom-mptelemetry-metrics.adoc b/modules/ROOT/pages/custom-mptelemetry-metrics.adoc index 02557500b..76ceae8c4 100644 --- a/modules/ROOT/pages/custom-mptelemetry-metrics.adoc +++ b/modules/ROOT/pages/custom-mptelemetry-metrics.adoc @@ -18,7 +18,7 @@ For more information about collecting and emitting metrics with MicroProfile Tel For more information about OpenTelemetry metrics, see the link:https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/1.39.0/io/opentelemetry/api/metrics/package-summary.html[OpenTelemetry metrics API documentation]. -Before you can use MicroProfile Telemetry to define custom metrics, you must enable MicroProfile Telemetry in your development environment by editing your runtime configuration. You must also add the OpenTelemetry API and annotations as a dependency on your build path. For more information, see xref:prepare-mptelemetry.adoc[Prepare your development environment for MicroProfile Telemetry]. +Before you can use MicroProfile Telemetry to define custom metrics metrics, you must enable MicroProfile Telemetry in your development environment by editing your runtime configuration. You must also add the OpenTelemetry API and annotations as a dependency on your build path. For more information, see link:{url-prefix}/docs/latest/reference/feature/mpTelemetry-2.0.html#dev[Prepare your development environment for MicroProfile Telemetry]. The following example defines a custom counter metric: From cb3eb1c1255ec920827221747c7cf64850e4cb73 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Fri, 15 Nov 2024 15:39:48 -0500 Subject: [PATCH 34/81] Update featureUtility-commands.adoc --- modules/reference/pages/command/featureUtility-commands.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/reference/pages/command/featureUtility-commands.adoc b/modules/reference/pages/command/featureUtility-commands.adoc index 9c5f38e8a..7a45a1d0d 100644 --- a/modules/reference/pages/command/featureUtility-commands.adoc +++ b/modules/reference/pages/command/featureUtility-commands.adoc @@ -69,7 +69,7 @@ Supported values are `enforce`, `skip`, `all`, and `warn`. If this option is not * `all`: Verifies both the Liberty features and the user features. The features that are provided by the Liberty framework and any additional user features or components are checked for integrity. * `warn`: Similar to the `all` option, warn also verifies both the Liberty features and user features. This option allows the process to continue, even if some feature signatures cannot be validated. A verification failure does not immediately end the installation process, but it results in a warning message. -|`NO_PROXY` +|`no_proxy` |`http.nonProxyHosts` |Requires Open Liberty to use a direct connection instead of a proxy for certain hosts. Specify a list of hostname patterns separated by pipe (`\|`), comma (`,`), or period (`.`) delimiters. Patterns can start or end with an asterisk (`*`) for wildcards. For any hostname that matches a specified pattern, Open Liberty connects to the host directly instead of going through a proxy. From cdb4bdf83767bd41f533c49ee3bde5c531be0c08 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Mon, 18 Nov 2024 12:56:02 -0500 Subject: [PATCH 35/81] edits --- .../ROOT/pages/microprofile-telemetry.adoc | 24 +++++++++++++++---- .../feature/mpTelemetry-2.0/examples.adoc | 9 +------ .../pages/microprofile-config-properties.adoc | 22 ++++++++--------- 3 files changed, 31 insertions(+), 24 deletions(-) diff --git a/modules/ROOT/pages/microprofile-telemetry.adoc b/modules/ROOT/pages/microprofile-telemetry.adoc index 320a796b7..6e221780f 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -35,7 +35,7 @@ To collect and export logs, metrics, and traces with OpenTelemetry in your Open * `jvm.options` file * `server.env` file + -If you choose to use the `server.env` file, specify the `OTEL_SDK_DISABLED=false` enviroment variable instead of the configuration property. +If you choose to use the `server.env` file, specify the `OTEL_SDK_DISABLED=false` environment variable instead of the `otel.sdk.disabled=false` configuration property. | Application level | Multiple applications in the same Liberty runtime @@ -102,7 +102,7 @@ This configuration creates all telemetry from Application 1 with the service nam * You can also use a combination of runtime-level and application-level configuration, so that some settings apply to all applications on the runtime, while others are specific to each application. This strategy can save you from having to duplicate general configuration settings in multiple applications on the same runtime. Any runtime-level configuration takes precedence over application-level configuration. Therefore, you can enable OpenTelemetry and assign a service name individually for each application, but specify other settings at the runtime level to apply globally to all applications on the runtime. + -For example, you might want to collect a unique set of telemetry data for each application in the runtime, but have all applications share the same OpenTelemetry exporter. You can set the OpenTelemetry exporter at the runtime-level in the `bootstrap.properties` file: +For example, you might want to collect a unique set of telemetry data for each application in the runtime, but have all applications share the same OpenTelemetry logs exporter. You can set the OpenTelemetry logs exporter at the runtime-level in the `bootstrap.properties` file: + ---- otel.logs.exporter=myExporter @@ -115,7 +115,7 @@ otel.sdk.disabled=false otel.service.name= ---- + -This configuration enables an application-level telemetry with a unique service name for each application, while all applications in the runtime use the `myExporter` OpenTelemetry exporter. +This configuration enables an application-level telemetry with a unique service name for each application, while all applications in the runtime use the `myExporter` logs exporter. After you enable the MicroProfile Telemetry feature and set the `otel.sdk.disabled=false` property for each application on the runtime, your applications are ready to start collecting and exporting logs, metrics, and traces. @@ -124,12 +124,26 @@ After you enable the MicroProfile Telemetry feature and set the `otel.sdk.disabl By default, all OpenTelemetry data is exported to the link:https://github.com/open-telemetry/oteps/blob/main/text/0035-opentelemetry-protocol.md[Open Telemetry Protocol] (OTLP) at the `\http://localhost:4317` endpoint. You can configure alternative global or data-specific exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. Open Liberty supports all link:https://opentelemetry.io/docs/languages/java/configuration/#environment-variables-and-system-properties[OpenTelemtry Java configuration properties]. +If you want to change the exporter that OpenTelemetry uses for logs, metrics, or traces, set the `otel.<_signal_>.exporter` property, where <_signal_> is the type of data that you want to change the exporter for: logs, metrics or traces. For example, to export your application and runtime traces to a configured Zipkin server, you can set the following property in the `bootstrap.properties` file: + +[source,properties] +---- +otel.traces.exporter=zipkin +---- + +To change the default endpoint that data is exported to, set the `otel.exporter.otlp.endpoint`. For example, you can set the following property in the `bootstrap.properties` file to change the endpoint from the `\http://localhost:4317` to `\http://localhost:9080` : + +[source,properties] +---- +otel.exporter.otlp.endpoint=http://localhost:9080 +---- + For information about commonly-used configuration properties for logs, metrics, and trace settings, see xref:reference:microprofile-config-properties.adoc#telemetry[MicroProfile Config properties: MicroProfile Telemetry]. [#traces] === Trace defaults -When you enable OpenTelemetry for Open Liberty, Jakarta RESTful Web Services and JAX-RS applications are instrumented for trace by default. Spans are automatically generated for incoming HTTP requests, including static files, servlets, and JSPs. These spans are automatically exported according to the configured OpenTelemetry settings. +When you enable OpenTelemetry for Open Liberty, Jakarta RESTful Web Services and JAX-RS applications are instrumented for trace by default. Spans are automatically generated for incoming HTTP requests, including static files, servlets, and JSPs. These spans are automatically exported according to the configured OpenTelemetry exporter settings. 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 OpenTelemetry API. Alternatively, you can attach the OpenTelemetry Java agent to any Java 8+ application. For more information about these options, see xref:telemetry-trace.adoc[Code instrumentation for MicroProfile Telemetry tracing]. @@ -146,7 +160,7 @@ By default, the OpenTelemetry Simple logRecord Processor is enabled, so the reco [#metrics] === Metrics defaults -When you enable OpenTelemetry for Open Liberty, a default set of metrics is automatically collected and exported according to the configured OpenTelemetry settings. For more information about these metrics, see xref:mptelemetry-metrics-list.adoc[MicroProfile Telemetry metrics reference list]. You can also define additional xref:custom-mptelemetry-metrics.adoc[custom metrics] in your application code. +When you enable OpenTelemetry for Open Liberty, a default set of metrics is automatically collected and exported according to the configured OpenTelemetry exporter settings. For more information about these metrics, see xref:mptelemetry-metrics-list.adoc[MicroProfile Telemetry metrics reference list]. You can also define additional xref:custom-mptelemetry-metrics.adoc[custom metrics] in your application code for OpenTelemetry to collect and export. == See also diff --git a/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc b/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc index c99488860..08fe0b5a1 100644 --- a/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc +++ b/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc @@ -17,7 +17,7 @@ When you enable the MicroProfile Telemetry feature and set this property, your If you need to xref:ROOT:telemetry-trace.adoc[manually instrument your code to collect traces] or xref:ROOT:custom-mptelemetry-metrics.adoc[define custom metrics], complete the following prerequisites to enable MicroProfile Telemetry in your development environment: -. 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: +. xref:ROOT: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] ---- @@ -60,10 +60,3 @@ To enable the MicroProfile Telemetry feature to collect logs from different sour * If the source attribute is empty (`source=“”`), no sources are collected, and nothing is routed to the configured OpenTelemetry logs exporter. * The attributes and values are case insensitive. - - - - - - -=== diff --git a/modules/reference/pages/microprofile-config-properties.adoc b/modules/reference/pages/microprofile-config-properties.adoc index 6f337706f..3eee3814d 100644 --- a/modules/reference/pages/microprofile-config-properties.adoc +++ b/modules/reference/pages/microprofile-config-properties.adoc @@ -665,6 +665,11 @@ For more information about collecting Open Liberty logs, metrics, and traces, se |Application startup or runtime startup |`otel.exporter.zipkin.endpoint=http://localhost:9413/api/v2/spans` +|`otel.logs.exporter` +|You can use this property to change where the logs that OpenTelemetry collects are exported. +|Application startup or runtime startup +|`otel.traces.exporter=console` + |`otel.metric.export.interval` |By default, metric data is exported at an interval of 60000 milliseconds (one minute). To modify the export interval, specify the new value in milliseconds. For more information, see link:https://opentelemetry.io/docs/specs/otel/metrics/sdk/#periodic-exporting-metricreader[Periodic exporting MetricReader] in the OpenTelemetry documentation. |Application startup or runtime startup @@ -675,26 +680,21 @@ For more information about collecting Open Liberty logs, metrics, and traces, se |Application startup or runtime startup |`otel.metric.export.timeout=60000` +|`otel.metrics.exporter` +|You can use this property to change where the metrics that OpenTelemetry collects are exported. +|Application startup or runtime startup +|`otel.metrics.exporter=prometheus` + |`otel.sdk.disabled` |Enables logs, metrics, and traces to be sent to OpenTelemetry. The default is `true`. |Application startup or runtime startup |`otel.sdk.disabled=false` |`otel.service.name` -|Sets of the name of the service that MicroProfile Telemetry is tracing. +|Sets of the name of the service that OpenTelemetry is tracing. |Application startup or runtime startup |`otel.service.name=system` -|`otel.logs.exporter` -|You can use this property to change where the logs that MicroProfile Telemetry collects are exported. -|Application startup or runtime startup -|`otel.traces.exporter=console` - -|`otel.metrics.exporter` -|You can use this property to change where the metrics that MicroProfile Telemetry collects are exported. -|Application startup or runtime startup -|`otel.metrics.exporter=prometheus` - |`otel.traces.exporter` |Sets the exporter that is used to collect traces. Possible values are `otlp`, `zipkin`, `jaeger`, or `logging`. The default value is `otlp`. For the Jaeger trace service versions 1.35 and later, the `otlp` exporter value is recommended, rather than `jaeger`. |Application startup or runtime startup From 861fb6c016b2226ab2ef202c7f1d4cb5763c4f8a Mon Sep 17 00:00:00 2001 From: David Mueller Date: Mon, 18 Nov 2024 13:17:45 -0500 Subject: [PATCH 36/81] Update microprofile-telemetry.adoc --- 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 6e221780f..825c673db 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -124,14 +124,14 @@ After you enable the MicroProfile Telemetry feature and set the `otel.sdk.disabl By default, all OpenTelemetry data is exported to the link:https://github.com/open-telemetry/oteps/blob/main/text/0035-opentelemetry-protocol.md[Open Telemetry Protocol] (OTLP) at the `\http://localhost:4317` endpoint. You can configure alternative global or data-specific exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. Open Liberty supports all link:https://opentelemetry.io/docs/languages/java/configuration/#environment-variables-and-system-properties[OpenTelemtry Java configuration properties]. -If you want to change the exporter that OpenTelemetry uses for logs, metrics, or traces, set the `otel.<_signal_>.exporter` property, where <_signal_> is the type of data that you want to change the exporter for: logs, metrics or traces. For example, to export your application and runtime traces to a configured Zipkin server, you can set the following property in the `bootstrap.properties` file: +If you want to change the exporter that OpenTelemetry uses for logs, metrics, or traces, set the `otel.<_signal_>.exporter` property, where <_signal_> is the type of data that you want to change the exporter for: logs, metrics or traces. For example, If you use Zipkin to manage your trace data, you can set the following property in the `bootstrap.properties` file to export your application and runtime traces to a configured Zipkin server: [source,properties] ---- otel.traces.exporter=zipkin ---- -To change the default endpoint that data is exported to, set the `otel.exporter.otlp.endpoint`. For example, you can set the following property in the `bootstrap.properties` file to change the endpoint from the `\http://localhost:4317` to `\http://localhost:9080` : +To change the default endpoint that data is exported to, set the `otel.exporter.otlp.endpoint`. For example, you can set the following property in the `bootstrap.properties` file to change the endpoint for all logs, metrics, and traces from the `\http://localhost:4317` default to `\http://localhost:9080`: [source,properties] ---- From cf6c057ec9ccb64366a98f1cba0e5f3384b9793a Mon Sep 17 00:00:00 2001 From: David Mueller Date: Mon, 18 Nov 2024 13:28:49 -0500 Subject: [PATCH 37/81] Update telemetry-troubleshooting.adoc --- modules/ROOT/pages/telemetry-troubleshooting.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/modules/ROOT/pages/telemetry-troubleshooting.adoc b/modules/ROOT/pages/telemetry-troubleshooting.adoc index 432f7a069..dc45adbe2 100644 --- a/modules/ROOT/pages/telemetry-troubleshooting.adoc +++ b/modules/ROOT/pages/telemetry-troubleshooting.adoc @@ -44,6 +44,8 @@ otel.metrics.exporter=console If you enabled OpenTelemetry at the application level, and you want to send only the logs, metrics, or traces for a particular application to the console, set the corresponding property in the `microprofile-config.properties` file for the application. +== 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 9d6957510c5e92015955f5c3f4e3596d0c92fe30 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Mon, 18 Nov 2024 15:28:21 -0500 Subject: [PATCH 38/81] edits --- .../pages/custom-mptelemetry-metrics.adoc | 2 +- .../ROOT/pages/microprofile-telemetry.adoc | 27 ++++++++++--------- modules/ROOT/pages/telemetry-trace.adoc | 2 +- .../feature/mpTelemetry-2.0/examples.adoc | 4 +-- 4 files changed, 19 insertions(+), 16 deletions(-) diff --git a/modules/ROOT/pages/custom-mptelemetry-metrics.adoc b/modules/ROOT/pages/custom-mptelemetry-metrics.adoc index 76ceae8c4..31dba9d17 100644 --- a/modules/ROOT/pages/custom-mptelemetry-metrics.adoc +++ b/modules/ROOT/pages/custom-mptelemetry-metrics.adoc @@ -18,7 +18,7 @@ For more information about collecting and emitting metrics with MicroProfile Tel For more information about OpenTelemetry metrics, see the link:https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/1.39.0/io/opentelemetry/api/metrics/package-summary.html[OpenTelemetry metrics API documentation]. -Before you can use MicroProfile Telemetry to define custom metrics metrics, you must enable MicroProfile Telemetry in your development environment by editing your runtime configuration. You must also add the OpenTelemetry API and annotations as a dependency on your build path. For more information, see link:{url-prefix}/docs/latest/reference/feature/mpTelemetry-2.0.html#dev[Prepare your development environment for MicroProfile Telemetry]. +Before you can use MicroProfile Telemetry to define custom metrics metrics, you must enable MicroProfile Telemetry in your development environment by editing your runtime configuration. You must also add the OpenTelemetry API and annotations as a dependency on your build path. For more information, see link:/docs/latest/reference/feature/mpTelemetry-2.0.html#dev[Prepare your development environment for MicroProfile Telemetry]. The following example defines a custom counter metric: diff --git a/modules/ROOT/pages/microprofile-telemetry.adoc b/modules/ROOT/pages/microprofile-telemetry.adoc index 825c673db..7dd448b0b 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -14,9 +14,9 @@ The OpenTelemetry project is a collection of open source, vendor-independent resources for collecting and managing application telemetry data. With Open Liberty and MicroProfile Telemetry 2.0 and later, you can manage logs, metrics, and traces in a standardized way by using the OpenTelemetry protocol. -OpenTelemetry provides a link:https://opentelemetry.io/docs/collector/[collector] component that can receive telemetry data from your applications and export it to backend services of your choice for monitoring and analysis. By default, all OpenTelemetry data is exported to the Open Telemetry Protocol (OTLP). OTLP defines the encoding of telemetry data and the protocol that is used to exchange data between a client and server. Many backend services accept OTLP data without requiring conversion, but OpenTelemtry also provides a collection of service-specific exporters for popular open source and commercial services, such as link:https://zipkin.io/[Zipkin] and link:https://prometheus.io/[Prometheus]. You can configure global or data-specific exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. +OpenTelemetry provides a link:https://opentelemetry.io/docs/collector/[collector] component that can receive telemetry data from your runtime and applications and export it to backend services of your choice for monitoring and analysis. By default, all OpenTelemetry data is exported by using the OpenTelemetry Protocol (OTLP). OTLP defines the encoding of telemetry data and the protocol that is used to exchange data between a client and server. Many backend services accept OTLP data without requiring conversion, but OpenTelemetry also provides a collection of service-specific exporters for popular open source and commercial services, such as link:https://zipkin.io/[Zipkin] and link:https://prometheus.io/[Prometheus]. You can configure exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. -OpenTelemetry is implemented in Open Liberty through the feature:mptelemtry[display=MicroProfile Telemetry] feature. When you enable the MicroProfile Telemetry feature 2.0 or later and specify the required configuration property, Open Liberty automatically collects and exports logs, traces, and metrics at the application or runtime level. For many common application scenarios, no changes are needed in your application code to collect this data. MicroProfile Telemetry1.1 and earlier enables only the collection of traces and only at the application level. +OpenTelemetry is implemented in Open Liberty through the feature:mptelemtry[display=MicroProfile Telemetry] feature. When you enable the MicroProfile Telemetry feature 2.0 or later and specify the required configuration property, Open Liberty automatically collects and exports logs, traces, and metrics at the application or runtime level. For many common application scenarios, no changes are needed in your application code to collect this data. MicroProfile Telemetry 1.1 and earlier enables only the collection of traces and only at the application level. [#global] == Collecting and exporting logs, metrics, and traces with OpenTelemetry @@ -46,7 +46,7 @@ If you choose to use the `server.env` file, specify the `OTEL_SDK_DISABLED=false === Enabling OpenTelemetry for an Open Liberty runtime with a single application -When your Open Liberty runtime hosts only one application, you can enable Open Telemetry at the runtime level to collect and export logs, metrics, and traces for both the runtime and the application. +When your Open Liberty runtime hosts only one application, you can enable OpenTelemetry at the runtime level to collect and export logs, metrics, and traces for both the runtime and the application. * Enable the feature:mpTelemetry[display=MicroProfile Telemetry] feature version 2.0 or later in the `featureManager` element of your `server.xml` file. + @@ -102,7 +102,7 @@ This configuration creates all telemetry from Application 1 with the service nam * You can also use a combination of runtime-level and application-level configuration, so that some settings apply to all applications on the runtime, while others are specific to each application. This strategy can save you from having to duplicate general configuration settings in multiple applications on the same runtime. Any runtime-level configuration takes precedence over application-level configuration. Therefore, you can enable OpenTelemetry and assign a service name individually for each application, but specify other settings at the runtime level to apply globally to all applications on the runtime. + -For example, you might want to collect a unique set of telemetry data for each application in the runtime, but have all applications share the same OpenTelemetry logs exporter. You can set the OpenTelemetry logs exporter at the runtime-level in the `bootstrap.properties` file: +For example, you might want to collect a unique set of telemetry data for each application in the runtime, but have all applications share the same OpenTelemetry logs exporter. You can set the OpenTelemetry logs exporter at the runtime-level by adding th following property in the `bootstrap.properties` file: + ---- otel.logs.exporter=myExporter @@ -122,22 +122,24 @@ After you enable the MicroProfile Telemetry feature and set the `otel.sdk.disabl [#config] == OpenTelemetry settings and configuration -By default, all OpenTelemetry data is exported to the link:https://github.com/open-telemetry/oteps/blob/main/text/0035-opentelemetry-protocol.md[Open Telemetry Protocol] (OTLP) at the `\http://localhost:4317` endpoint. You can configure alternative global or data-specific exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. Open Liberty supports all link:https://opentelemetry.io/docs/languages/java/configuration/#environment-variables-and-system-properties[OpenTelemtry Java configuration properties]. +By default, all OpenTelemetry data is exported byb using the link:https://github.com/open-telemetry/oteps/blob/main/text/0035-opentelemetry-protocol.md[OpenTelemetry Protocol] (OTLP) at the `\http://localhost:4317` endpoint. You can configure alternative exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. Open Liberty supports all link:https://opentelemetry.io/docs/languages/java/configuration/#environment-variables-and-system-properties[OpenTelemtry Java configuration properties]. -If you want to change the exporter that OpenTelemetry uses for logs, metrics, or traces, set the `otel.<_signal_>.exporter` property, where <_signal_> is the type of data that you want to change the exporter for: logs, metrics or traces. For example, If you use Zipkin to manage your trace data, you can set the following property in the `bootstrap.properties` file to export your application and runtime traces to a configured Zipkin server: +To change the default endpoint that data is exported to, set the `otel.exporter.otlp.endpoint`. For example, you can set the following property in the `bootstrap.properties` file to change the endpoint for all logs, metrics, and traces from the `\http://localhost:4317` default to `\http://localhost:9080`: [source,properties] ---- -otel.traces.exporter=zipkin +otel.exporter.otlp.endpoint=http://localhost:9080 ---- -To change the default endpoint that data is exported to, set the `otel.exporter.otlp.endpoint`. For example, you can set the following property in the `bootstrap.properties` file to change the endpoint for all logs, metrics, and traces from the `\http://localhost:4317` default to `\http://localhost:9080`: +If you want to change the exporter that OpenTelemetry uses for logs, metrics, or traces, set the `otel.< _signal_ >.exporter` property, where _signal_ is the type of data that you want to change the exporter for: logs, metrics or traces. For example, If you use Zipkin to manage your trace data, you can set the following property in the `bootstrap.properties` file to export your application and runtime traces to a configured Zipkin server: [source,properties] ---- -otel.exporter.otlp.endpoint=http://localhost:9080 +otel.traces.exporter=zipkin ---- +When you change the exporter value to `zipkin`, OpenTelemetry exports traces to the `\http://localhost:9411/api/v2/spans` endpoint instead of the OTLP default endpoint. You can configure a different endpoint by setting the `otel.exporter.zipkin.endpoint` property value to your chosen endpoint. + For information about commonly-used configuration properties for logs, metrics, and trace settings, see xref:reference:microprofile-config-properties.adoc#telemetry[MicroProfile Config properties: MicroProfile Telemetry]. [#traces] @@ -153,15 +155,16 @@ OpenTelemetry automatically collects any logs that are sent to the `java.util.lo For information about Liberty log event fields for OpenTelemetry, see xref:mptel-log-events-list.adoc[MicroProfile Telemetry log events reference list]. -//// -By default, the OpenTelemetry Simple logRecord Processor is enabled, so the records are sent immediately. However, if you want to send the records in batches, you can also configure the logging-specific Batch LogRecord Processor properties. -//// + +When you use the `otlp` default log exporter, the OpenTelemetry Batch LogRecord Processor (BLRP) is enabled and log records are exported in batches according to BLRP default settings. You can can adjust these settings with `otel.blrp.*` properties. For more information about the available properties and their default settings, see see xref:reference:microprofile-config-properties.adoc#telemetry[MicroProfile Config properties: MicroProfile Telemetry]. [#metrics] === Metrics defaults When you enable OpenTelemetry for Open Liberty, a default set of metrics is automatically collected and exported according to the configured OpenTelemetry exporter settings. For more information about these metrics, see xref:mptelemetry-metrics-list.adoc[MicroProfile Telemetry metrics reference list]. You can also define additional xref:custom-mptelemetry-metrics.adoc[custom metrics] in your application code for OpenTelemetry to collect and export. +You can configure the metrics exporter settings, including the export interval and timeout values, by setting system properties. For more information, see see xref:reference:microprofile-config-properties.adoc#telemetry[MicroProfile Config properties: MicroProfile Telemetry]. + == See also diff --git a/modules/ROOT/pages/telemetry-trace.adoc b/modules/ROOT/pages/telemetry-trace.adoc index ad4f5cd30..a87ca8ab8 100644 --- a/modules/ROOT/pages/telemetry-trace.adoc +++ b/modules/ROOT/pages/telemetry-trace.adoc @@ -30,7 +30,7 @@ In Open Liberty version 23.0.0.11 and later, spans are automatically generated f 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.39.0/io/opentelemetry/api/trace/package-summary.html[OpenTelemetry API]. -However, before you manually instrument your code, you must enable MicroProfile Telemetry in your development environment by editing your runtime configuration. You must also add the OpenTelemetry API and annotations as a dependency on your build path. For more information, see link:{url-prefix}/docs/latest/reference/feature/mpTelemetry-2.0.html#dev[Prepare your development environment for MicroProfile Telemetry]. +However, before you manually instrument your code, you must enable MicroProfile Telemetry in your development environment by editing your runtime configuration. You must also add the OpenTelemetry API and annotations as a dependency on your build path. For more information, see link:/docs/latest/reference/feature/mpTelemetry-2.0.html#dev[Prepare your development environment for MicroProfile Telemetry]. After you complete those prerequisites, you're ready to instrument your code. The following examples show configuration options with the OpenTelemetry API. diff --git a/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc b/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc index 08fe0b5a1..b81878348 100644 --- a/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc +++ b/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc @@ -17,7 +17,7 @@ When you enable the MicroProfile Telemetry feature and set this property, your If you need to xref:ROOT:telemetry-trace.adoc[manually instrument your code to collect traces] or xref:ROOT:custom-mptelemetry-metrics.adoc[define custom metrics], complete the following prerequisites to enable MicroProfile Telemetry in your development environment: -. xref:ROOT:class-loader-library-config.adoc#3rd-party[Enable third-party APIs] for your application by adding the following code in your `server.xml` file: +* xref:ROOT: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] ---- @@ -26,7 +26,7 @@ If you need to xref:ROOT:telemetry-trace.adoc[manually instrument your code to c ---- -. 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] ---- From 20d8f82a04f65437573d04d6b8d742d6c94ed0d3 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Mon, 18 Nov 2024 15:31:36 -0500 Subject: [PATCH 39/81] Update telemetry-troubleshooting.adoc --- modules/ROOT/pages/telemetry-troubleshooting.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/modules/ROOT/pages/telemetry-troubleshooting.adoc b/modules/ROOT/pages/telemetry-troubleshooting.adoc index dc45adbe2..45c4c8ec4 100644 --- a/modules/ROOT/pages/telemetry-troubleshooting.adoc +++ b/modules/ROOT/pages/telemetry-troubleshooting.adoc @@ -33,6 +33,8 @@ Similarly, to send all application and runtime logs to the `console.log` file, s otel.logs.exporter=console ---- +When you configure the logs exporter to `console`, log records are sent immediately, instead of in batches like they are when the default `otlp` exporter is used. + To send all application and runtime metrics to the `console.log` file, set the following property in the `bootstrap.properties` file: [source,properties] From 710507a148f2a4793047a68ddd36f6eb2f4ee6c5 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Tue, 19 Nov 2024 09:01:36 -0500 Subject: [PATCH 40/81] edits #7655 --- .../ROOT/pages/microprofile-telemetry.adoc | 20 +++++++++++-------- modules/ROOT/pages/observability.adoc | 4 ++++ .../ROOT/pages/telemetry-troubleshooting.adoc | 2 +- 3 files changed, 17 insertions(+), 9 deletions(-) diff --git a/modules/ROOT/pages/microprofile-telemetry.adoc b/modules/ROOT/pages/microprofile-telemetry.adoc index 7dd448b0b..50597b93f 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -24,11 +24,11 @@ OpenTelemetry is implemented in Open Liberty through the feature:mptelemtry[disp To collect and export logs, metrics, and traces with OpenTelemetry in your Open Liberty runtime, you must add the MicroProfile Telemetry feature to your `server.xml` file and specify the `otel.sdk.disabled=false` system property in one of the valid configuration sources. Depending on whether your runtime hosts a single application or multiple applications, you can specify this property at the runtime level or the application level. In most cases, runtime-level configuration is preferred because it includes both runtime-level telemetry and application-specific telemetry. The following table summarizes the benefits and use cases for each option. .OpenTelemetry configuration options -[options="header"cols="4,2,6a,3a"] +[options="header"cols="2,2,6a,6a"] |=== |Configuration level | Use case | Description | Configuration sources -| Runtime level +| <<#runtime, Runtime level>> | One application per Liberty runtime | Collects and emits telemetry from both the runtime and the application. | * `bootstrap.properties` file @@ -37,13 +37,14 @@ To collect and export logs, metrics, and traces with OpenTelemetry in your Open + If you choose to use the `server.env` file, specify the `OTEL_SDK_DISABLED=false` environment variable instead of the `otel.sdk.disabled=false` configuration property. -| Application level +| <<#app, Application level>> | Multiple applications in the same Liberty runtime | Collects and emits telemetry for a single application and does not include runtime-level data. Provides fine-grained control over data collection for each application. | * `microprofile-config.properties` file * `appProperties` attribute for the config:application[] element in the `server.xml` file. |=== +[#runtime] === Enabling OpenTelemetry for an Open Liberty runtime with a single application When your Open Liberty runtime hosts only one application, you can enable OpenTelemetry at the runtime level to collect and export logs, metrics, and traces for both the runtime and the application. @@ -66,6 +67,7 @@ otel.sdk.disabled=false After you enable the MicroProfile Telemetry feature and set this system property, your runtime is ready to start collecting and exporting logs, metrics, and traces from the application and the runtime. For more information, see <>. +[#app] === Enabling OpenTelemetry for multiple applications in the same Open Liberty runtime When your Liberty runtime hosts multiple applications, you might choose to enable OpenTelemetry to collect logs, metrics, and traces at the application level for each application. Although this option does not collect runtime-level telemetry, it gives you fine-grained control of the data you collect for each application. @@ -122,16 +124,16 @@ After you enable the MicroProfile Telemetry feature and set the `otel.sdk.disabl [#config] == OpenTelemetry settings and configuration -By default, all OpenTelemetry data is exported byb using the link:https://github.com/open-telemetry/oteps/blob/main/text/0035-opentelemetry-protocol.md[OpenTelemetry Protocol] (OTLP) at the `\http://localhost:4317` endpoint. You can configure alternative exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. Open Liberty supports all link:https://opentelemetry.io/docs/languages/java/configuration/#environment-variables-and-system-properties[OpenTelemtry Java configuration properties]. +By default, all OpenTelemetry data is exported by using the link:https://github.com/open-telemetry/oteps/blob/main/text/0035-opentelemetry-protocol.md[OpenTelemetry Protocol] (OTLP) at the `\http://localhost:4317` endpoint. You can configure alternative exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. Open Liberty supports all link:https://opentelemetry.io/docs/languages/java/configuration/#environment-variables-and-system-properties[OpenTelemtry Java configuration properties]. -To change the default endpoint that data is exported to, set the `otel.exporter.otlp.endpoint`. For example, you can set the following property in the `bootstrap.properties` file to change the endpoint for all logs, metrics, and traces from the `\http://localhost:4317` default to `\http://localhost:9080`: +To change the default endpoint that data is exported to, set the `otel.exporter.otlp.endpoint` property. For example, you can set the following property in the `bootstrap.properties` file to change the endpoint for all logs, metrics, and traces from the `\http://localhost:4317` default to `\http://localhost:9080`: [source,properties] ---- otel.exporter.otlp.endpoint=http://localhost:9080 ---- -If you want to change the exporter that OpenTelemetry uses for logs, metrics, or traces, set the `otel.< _signal_ >.exporter` property, where _signal_ is the type of data that you want to change the exporter for: logs, metrics or traces. For example, If you use Zipkin to manage your trace data, you can set the following property in the `bootstrap.properties` file to export your application and runtime traces to a configured Zipkin server: +If you want to change the exporter that OpenTelemetry uses for logs, metrics, or traces, set the `otel.< _signal_ >.exporter` property, where `_signal_` is the type of data that you want to change the exporter for: logs, metrics or traces. For example, If you use Zipkin to manage your trace data, you can set the following property in the `bootstrap.properties` file to export your application and runtime traces to a configured Zipkin server: [source,properties] ---- @@ -140,6 +142,8 @@ otel.traces.exporter=zipkin When you change the exporter value to `zipkin`, OpenTelemetry exports traces to the `\http://localhost:9411/api/v2/spans` endpoint instead of the OTLP default endpoint. You can configure a different endpoint by setting the `otel.exporter.zipkin.endpoint` property value to your chosen endpoint. +For debugging purposes, you can also temporarily configure your logs, metrics, or traces to be exported to the `console.log` file. For more information, see xref:telemetry-troubleshooting.adoc#console[Exporting logs, metrics, or traces to the console for debugging purposes]. + For information about commonly-used configuration properties for logs, metrics, and trace settings, see xref:reference:microprofile-config-properties.adoc#telemetry[MicroProfile Config properties: MicroProfile Telemetry]. [#traces] @@ -151,7 +155,7 @@ Automatic instrumentation is available only for JAX-RS and Jakarta RESTful web s [#logs] === Logs defaults -OpenTelemetry automatically collects any logs that are sent to the `java.util.logging` API. Any messages that are logged at a `java.util.logging.Level` log level of `INFO` and above are considered messages. Levels below `INFO` are considered trace. By default, OpenTelemetry logging automatically collects messages, but you can configure it to collect from other sources in your `server.xml` file. For more information, see link:/docs/latest/reference/feature/mpTelemetry-2.0.html#_collect_logs_from_a_specified_source[Collect logs from a specified source]. +OpenTelemetry automatically collects runtime and application logs that are sent to the `java.util.logging` API. Any events that are logged at a `java.util.logging.Level` log level of `INFO` and above are considered messages. Levels below `INFO` are considered trace. By default, OpenTelemetry logging automatically collects messages, but you can configure it to collect from other sources in your `server.xml` file. For more information, see link:/docs/latest/reference/feature/mpTelemetry-2.0.html#_collect_logs_from_a_specified_source[Collect logs from a specified source]. For information about Liberty log event fields for OpenTelemetry, see xref:mptel-log-events-list.adoc[MicroProfile Telemetry log events reference list]. @@ -161,7 +165,7 @@ When you use the `otlp` default log exporter, the OpenTelemetry Batch LogRecord [#metrics] === Metrics defaults -When you enable OpenTelemetry for Open Liberty, a default set of metrics is automatically collected and exported according to the configured OpenTelemetry exporter settings. For more information about these metrics, see xref:mptelemetry-metrics-list.adoc[MicroProfile Telemetry metrics reference list]. You can also define additional xref:custom-mptelemetry-metrics.adoc[custom metrics] in your application code for OpenTelemetry to collect and export. +When you enable OpenTelemetry for Open Liberty, a default set of metrics is automatically collected and exported according to the configured OpenTelemetry exporter settings. OpenTelemetry collects both JVM runtime-environment metrics and HTTP metrics. For more information about these metrics, see the xref:mptelemetry-metrics-list.adoc[MicroProfile Telemetry metrics reference list]. You can also use the OpenTelemetry API to xref:custom-mptelemetry-metrics.adoc[define custom metrics] in your application code for OpenTelemetry to collect and export. You can configure the metrics exporter settings, including the export interval and timeout values, by setting system properties. For more information, see see xref:reference:microprofile-config-properties.adoc#telemetry[MicroProfile Config properties: MicroProfile Telemetry]. diff --git a/modules/ROOT/pages/observability.adoc b/modules/ROOT/pages/observability.adoc index 004b959cd..4d0a8b852 100644 --- a/modules/ROOT/pages/observability.adoc +++ b/modules/ROOT/pages/observability.adoc @@ -19,8 +19,10 @@ With MicroProfile Telemetry 2.0 and later, you can manage logs, metrics, and tra The following topics provide information to help you develop observable applications with Open Liberty. +//// xref:prepare-mptelemetry.adoc[Prepare your development environment for MicroProfile Telemetry]:: Before you manually instrument your code to use MicroProfile Telemetry to collect metrics and traces, you must enable MicroProfile Telemetry in your development environment by editing your runtime configuration. You must also add the OpenTelemetry API and annotations as a dependency on your build path. +//// xref:custom-mptelemetry-metrics.adoc[Define custom MicroProfile Telemetry metrics]:: You can use the OpenTelemetry metrics API to define custom metrics in your application code. When you enable the MicroProfile Telemetry feature 2.0 or later, you can then collect and emit these metrics to customize the observability of your application. @@ -28,8 +30,10 @@ You can use the OpenTelemetry metrics API to define custom metrics in your appli xref:telemetry-trace.adoc[Code instrumentation for MicroProfile Telemetry tracing]:: After you enable MicroProfile Telemetry and configure a trace server, you can instrument tracing in your application code. You can instrument your code automatically, manually, or by using the Java agent. +//// xref:mptelemetry-logging.adoc[Write logs with MicroProfile Telemetry logging]:: You can use MicroProfile Telemetry to mange your logs, along with traces and metrics. When you enable the MicroProfile Telemetry feature version 2.0 or later, MicroProfile Telemetry automatically collects any logs that are sent to the `java.util.logging` API. +//// xref:microservice-observability-metrics.adoc[Microservice observability with MicroProfile metrics]:: 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 server and deployed applications. diff --git a/modules/ROOT/pages/telemetry-troubleshooting.adoc b/modules/ROOT/pages/telemetry-troubleshooting.adoc index 45c4c8ec4..c0b455a20 100644 --- a/modules/ROOT/pages/telemetry-troubleshooting.adoc +++ b/modules/ROOT/pages/telemetry-troubleshooting.adoc @@ -14,7 +14,7 @@ The following information can help you determine the cause of common problems and error messages that are associated with OpenTelemetry logs, metrics, and tracing. To debug issues with your OpenTelemetry logs, metrics, or traces, you can configure this data to export to the console. - +[#console] == Exporting logs, metrics, or traces to the console for debugging purposes By default, all OpenTelemetry data is exported to the `otlp` exporter. For debugging purposes, you can temporarily change the export destination to the `console.log` file by setting the `otel.<_signal_>.exporter=console` property at the application or the runtime level. From 3fec68d507849dbd157ed764f44e5c7484edfa9a Mon Sep 17 00:00:00 2001 From: David Mueller Date: Tue, 19 Nov 2024 10:08:15 -0500 Subject: [PATCH 41/81] edits --- modules/ROOT/pages/telemetry-troubleshooting.adoc | 4 ++-- modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/telemetry-troubleshooting.adoc b/modules/ROOT/pages/telemetry-troubleshooting.adoc index c0b455a20..7fc9a145c 100644 --- a/modules/ROOT/pages/telemetry-troubleshooting.adoc +++ b/modules/ROOT/pages/telemetry-troubleshooting.adoc @@ -12,7 +12,7 @@ :page-type: general = Troubleshooting OpenTelemetry -The following information can help you determine the cause of common problems and error messages that are associated with OpenTelemetry logs, metrics, and tracing. To debug issues with your OpenTelemetry logs, metrics, or traces, you can configure this data to export to the console. +The following information can help you determine the cause of common problems and error messages that are associated with OpenTelemetry logs, metrics, and tracing. To help debug issues with your OpenTelemetry logs, metrics, or traces, you can export this data to the console for analysis. [#console] == Exporting logs, metrics, or traces to the console for debugging purposes @@ -43,7 +43,7 @@ otel.metrics.exporter=console ---- -If you enabled OpenTelemetry at the application level, and you want to send only the logs, metrics, or traces for a particular application to the console, set the corresponding property in the `microprofile-config.properties` file for the application. +If you enabled OpenTelemetry at the application level and you want to send only the logs, metrics, or traces for a particular application to the console, set the corresponding property in the `microprofile-config.properties` file for the application. == Common problems and error messages diff --git a/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc b/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc index b81878348..70105305f 100644 --- a/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc +++ b/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc @@ -2,9 +2,9 @@ === Enable OpenTelemetry -In addition to enabling the MicroProfile Telemetry feature, you must also set the `otel.sdk.disabled=false` system property in one of the valid configuration sources. Depending on your application scenario, you can set this property at the runtime level, or the application level. For more information see xref:ROOT:microprofile-telemetry.adoc#global[Collecting and exporting logs, metrics, and traces with OpenTelemetry.] +TO enable OpenTelemetry for Open Liberty, in addition to enabling the MicroProfile Telemetry feature, you must also set the `otel.sdk.disabled=false` system property in one of the valid configuration sources. Depending on your application scenario, you can set this property at the runtime level or the application level. For more information, see xref:ROOT:microprofile-telemetry.adoc#global[Collecting and exporting logs, metrics, and traces with OpenTelemetry]. -The following example demonstrates how to enable OpenTelemetry at the runtime level,by setting the property in your `bootstrap.properties` file: +The following example demonstrates how to enable OpenTelemetry at the runtime level by setting the property in your `bootstrap.properties` file: ---- otel.sdk.disabled=false From eac894ce45a85e45b9892eb8750da603093773d2 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Tue, 19 Nov 2024 10:10:35 -0500 Subject: [PATCH 42/81] Update telemetry-troubleshooting.adoc --- modules/ROOT/pages/telemetry-troubleshooting.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/telemetry-troubleshooting.adoc b/modules/ROOT/pages/telemetry-troubleshooting.adoc index 7fc9a145c..93ae3c0ef 100644 --- a/modules/ROOT/pages/telemetry-troubleshooting.adoc +++ b/modules/ROOT/pages/telemetry-troubleshooting.adoc @@ -17,7 +17,7 @@ The following information can help you determine the cause of common problems an [#console] == Exporting logs, metrics, or traces to the console for debugging purposes -By default, all OpenTelemetry data is exported to the `otlp` exporter. For debugging purposes, you can temporarily change the export destination to the `console.log` file by setting the `otel.<_signal_>.exporter=console` property at the application or the runtime level. +By default, all OpenTelemetry data is exported to the `otlp` exporter. For debugging purposes, you can temporarily change the export destination to the `console.log` file by setting the `otel.< _signal_ >.exporter=console` property at the application or the runtime level. For example, to send all application and runtime traces to the `console.log` file, you might set the following property in the `bootstrap.properties` file: From b46852611574fc3bdafd622c347805983fb584a4 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Tue, 19 Nov 2024 10:12:30 -0500 Subject: [PATCH 43/81] Update examples.adoc --- modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc b/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc index 70105305f..9b645f654 100644 --- a/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc +++ b/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc @@ -2,7 +2,7 @@ === Enable OpenTelemetry -TO enable OpenTelemetry for Open Liberty, in addition to enabling the MicroProfile Telemetry feature, you must also set the `otel.sdk.disabled=false` system property in one of the valid configuration sources. Depending on your application scenario, you can set this property at the runtime level or the application level. For more information, see xref:ROOT:microprofile-telemetry.adoc#global[Collecting and exporting logs, metrics, and traces with OpenTelemetry]. +To enable OpenTelemetry for Open Liberty, in addition to enabling the MicroProfile Telemetry feature, you must also set the `otel.sdk.disabled=false` system property in one of the valid configuration sources. Depending on your application scenario, you can set this property at the runtime level or the application level. For more information, see xref:ROOT:microprofile-telemetry.adoc#global[Collecting and exporting logs, metrics, and traces with OpenTelemetry]. The following example demonstrates how to enable OpenTelemetry at the runtime level by setting the property in your `bootstrap.properties` file: @@ -10,7 +10,7 @@ The following example demonstrates how to enable OpenTelemetry at the runtime le otel.sdk.disabled=false ---- -When you enable the MicroProfile Telemetry feature and set this property, your system is ready to collect and export logs, metrics, and traces. +When you enable the MicroProfile Telemetry feature and set this property, your system is ready to collect and export logs, metrics, and traces. [#dev] === Prepare your development environment for OpenTelemetry From 4c1fe68f0ad03625a7c3423a50223805e21374b5 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Tue, 19 Nov 2024 11:34:32 -0500 Subject: [PATCH 44/81] edits --- modules/ROOT/pages/microprofile-telemetry.adoc | 16 ++++++++-------- .../ROOT/pages/telemetry-troubleshooting.adoc | 2 +- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/modules/ROOT/pages/microprofile-telemetry.adoc b/modules/ROOT/pages/microprofile-telemetry.adoc index 50597b93f..6c024dfb9 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -16,7 +16,7 @@ The OpenTelemetry project is a collection of open source, vendor-independent res OpenTelemetry provides a link:https://opentelemetry.io/docs/collector/[collector] component that can receive telemetry data from your runtime and applications and export it to backend services of your choice for monitoring and analysis. By default, all OpenTelemetry data is exported by using the OpenTelemetry Protocol (OTLP). OTLP defines the encoding of telemetry data and the protocol that is used to exchange data between a client and server. Many backend services accept OTLP data without requiring conversion, but OpenTelemetry also provides a collection of service-specific exporters for popular open source and commercial services, such as link:https://zipkin.io/[Zipkin] and link:https://prometheus.io/[Prometheus]. You can configure exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. -OpenTelemetry is implemented in Open Liberty through the feature:mptelemtry[display=MicroProfile Telemetry] feature. When you enable the MicroProfile Telemetry feature 2.0 or later and specify the required configuration property, Open Liberty automatically collects and exports logs, traces, and metrics at the application or runtime level. For many common application scenarios, no changes are needed in your application code to collect this data. MicroProfile Telemetry 1.1 and earlier enables only the collection of traces and only at the application level. +OpenTelemetry is implemented in Open Liberty through the feature:mpTelemetry[display=MicroProfile Telemetry] feature. When you enable the MicroProfile Telemetry feature 2.0 or later and specify the required configuration property, Open Liberty automatically collects and exports logs, traces, and metrics at the application or runtime level. For many common application scenarios, no changes are needed in your application code to collect this data. MicroProfile Telemetry 1.1 and earlier enables only the collection of traces and only at the application level. [#global] == Collecting and exporting logs, metrics, and traces with OpenTelemetry @@ -104,7 +104,7 @@ This configuration creates all telemetry from Application 1 with the service nam * You can also use a combination of runtime-level and application-level configuration, so that some settings apply to all applications on the runtime, while others are specific to each application. This strategy can save you from having to duplicate general configuration settings in multiple applications on the same runtime. Any runtime-level configuration takes precedence over application-level configuration. Therefore, you can enable OpenTelemetry and assign a service name individually for each application, but specify other settings at the runtime level to apply globally to all applications on the runtime. + -For example, you might want to collect a unique set of telemetry data for each application in the runtime, but have all applications share the same OpenTelemetry logs exporter. You can set the OpenTelemetry logs exporter at the runtime-level by adding th following property in the `bootstrap.properties` file: +For example, you might want to collect a unique set of telemetry data for each application in the runtime, but have all applications use the same OpenTelemetry logs exporter. You can set the OpenTelemetry logs exporter at the runtime-level by adding th following property in the `bootstrap.properties` file: + ---- otel.logs.exporter=myExporter @@ -126,16 +126,16 @@ After you enable the MicroProfile Telemetry feature and set the `otel.sdk.disabl By default, all OpenTelemetry data is exported by using the link:https://github.com/open-telemetry/oteps/blob/main/text/0035-opentelemetry-protocol.md[OpenTelemetry Protocol] (OTLP) at the `\http://localhost:4317` endpoint. You can configure alternative exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. Open Liberty supports all link:https://opentelemetry.io/docs/languages/java/configuration/#environment-variables-and-system-properties[OpenTelemtry Java configuration properties]. -To change the default endpoint that data is exported to, set the `otel.exporter.otlp.endpoint` property. For example, you can set the following property in the `bootstrap.properties` file to change the endpoint for all logs, metrics, and traces from the `\http://localhost:4317` default to `\http://localhost:9080`: +To change the endpoint that the default `otlp` exporter uses, set the `otel.exporter.otlp.endpoint` property. For example, you can set the following property in the `bootstrap.properties` file to change the endpoint for all `otlp` logs, metrics, and traces from the `\http://localhost:4317` default to `\http://localhost:9080`: [source,properties] ---- otel.exporter.otlp.endpoint=http://localhost:9080 ---- -If you want to change the exporter that OpenTelemetry uses for logs, metrics, or traces, set the `otel.< _signal_ >.exporter` property, where `_signal_` is the type of data that you want to change the exporter for: logs, metrics or traces. For example, If you use Zipkin to manage your trace data, you can set the following property in the `bootstrap.properties` file to export your application and runtime traces to a configured Zipkin server: +If you want to change the exporter that OpenTelemetry uses for logs, metrics, or traces, set the `otel.< _signal_ >.exporter` property, where `_signal_` is the type of data that you want to change the exporter for: logs, metrics, or traces. For example, if you use Zipkin to manage your trace data, you can set the following property in the `bootstrap.properties` file to export your application and runtime traces to a configured Zipkin server: -[source,properties] +[source, properties] ---- otel.traces.exporter=zipkin ---- @@ -160,14 +160,14 @@ OpenTelemetry automatically collects runtime and application logs that are sent For information about Liberty log event fields for OpenTelemetry, see xref:mptel-log-events-list.adoc[MicroProfile Telemetry log events reference list]. -When you use the `otlp` default log exporter, the OpenTelemetry Batch LogRecord Processor (BLRP) is enabled and log records are exported in batches according to BLRP default settings. You can can adjust these settings with `otel.blrp.*` properties. For more information about the available properties and their default settings, see see xref:reference:microprofile-config-properties.adoc#telemetry[MicroProfile Config properties: MicroProfile Telemetry]. +When you use the `otlp` default log exporter, the OpenTelemetry Batch LogRecord Processor (BLRP) is enabled and log records are exported in batches according to BLRP default settings. You can adjust these settings with `otel.blrp.*` properties. For more information about the available properties and their default settings, see xref:reference:microprofile-config-properties.adoc#telemetry[MicroProfile Config properties: MicroProfile Telemetry]. [#metrics] === Metrics defaults -When you enable OpenTelemetry for Open Liberty, a default set of metrics is automatically collected and exported according to the configured OpenTelemetry exporter settings. OpenTelemetry collects both JVM runtime-environment metrics and HTTP metrics. For more information about these metrics, see the xref:mptelemetry-metrics-list.adoc[MicroProfile Telemetry metrics reference list]. You can also use the OpenTelemetry API to xref:custom-mptelemetry-metrics.adoc[define custom metrics] in your application code for OpenTelemetry to collect and export. +When you enable OpenTelemetry for Open Liberty, a default set of metrics is automatically collected and exported according to the configured OpenTelemetry exporter settings. OpenTelemetry collects both JVM runtime-environment metrics and HTTP metrics. For more information about these metrics, see the xref:mptelemetry-metrics-list.adoc[MicroProfile Telemetry metrics reference list]. You can also use the OpenTelemetry API to xref:custom-mptelemetry-metrics.adoc[define custom metrics] in your application code for OpenTelemetry to collect and export. -You can configure the metrics exporter settings, including the export interval and timeout values, by setting system properties. For more information, see see xref:reference:microprofile-config-properties.adoc#telemetry[MicroProfile Config properties: MicroProfile Telemetry]. +You can configure the metrics exporter settings, including the export interval and timeout values, by setting system properties. For more information, see xref:reference:microprofile-config-properties.adoc#telemetry[MicroProfile Config properties: MicroProfile Telemetry]. == See also diff --git a/modules/ROOT/pages/telemetry-troubleshooting.adoc b/modules/ROOT/pages/telemetry-troubleshooting.adoc index 93ae3c0ef..b1e286b99 100644 --- a/modules/ROOT/pages/telemetry-troubleshooting.adoc +++ b/modules/ROOT/pages/telemetry-troubleshooting.adoc @@ -50,7 +50,7 @@ If you enabled OpenTelemetry at the application level and you want to send only 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. +If the `Scope` instance is not closed correctly, the context and baggage values of previous spans might remain when the next operation runs. Alternatively, the current span might remain and be picked up as the parent of the next operation that runs. + 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: + From e1e353527ec067d62e964ac4b3d8610a41e7a5f8 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Tue, 19 Nov 2024 22:43:21 +0530 Subject: [PATCH 45/81] 7654-Documentation-MicroProfile-OpenAPI-4.0-6 7654-Documentation-MicroProfile-OpenAPI-4.0-6 #7654 --- modules/ROOT/pages/documentation-openapi.adoc | 30 +++++++++++++------ 1 file changed, 21 insertions(+), 9 deletions(-) diff --git a/modules/ROOT/pages/documentation-openapi.adoc b/modules/ROOT/pages/documentation-openapi.adoc index 9796256d9..d97b20c1d 100644 --- a/modules/ROOT/pages/documentation-openapi.adoc +++ b/modules/ROOT/pages/documentation-openapi.adoc @@ -185,10 +185,20 @@ When multiple applications, or applications with more than one web module are de |Only the first web module of the first application deployed is included in the structured documentation. This cannot be changed. |=== + +== Configuring multiple application and multi-module support + +Open Liberty offers two main ways to configure support for multiple applications and multi-module projects. + +- <<#serverxml, Configure using the `server.xml` file:>> This method involves configuring your server to deploy multiple applications by specifying the applications and modules within the `server.xml` file. + +- <<#mpconfigs, Configure using the MicroProfile Config:>> Alternatively, you can use the MicroProfile Config to adjust deployment settings more flexibly, allowing for easy updates and changes without needing to modify XML files. + + [#serverxml] -== Configuring multiple application and multi-module support using server.xml +=== Configure using the server.xml file -For MicroProfile OpenAPI 2.0 and later, you can control the applications and modules that are included in the structured documentation by using the ``, ``, ``, and `` elements within the `` xref:reference:config/mpOpenAPI.adoc[configuration element]. +For MicroProfile OpenAPI 2.0 and later, you can control the applications and modules that are included in the structured documentation by using the `includeApplication`, `excludeApplication`, `includeModule`, and `excludeModule` elements within the `mpOpenAPI` xref:reference:config/mpOpenAPI.adoc[configuration element]. For example, to include all deployed applications and modules in the generated structured documentation when using `mpOpenAPI-2.0`, add the following configuration to your `server.xml` file. @@ -209,9 +219,9 @@ For example, to include all deployed applications and modules except the `admin` ---- -**Notes:** +==== Naming applications and modules -- The application name is determined by the value of the `name` attribute when the application is deployed in `server.xml` using ``, ``, or ``. For example: +- The application name is determined by the value of the `name` attribute when the application is deployed in `server.xml` using `application`, `webApplication`, or `enterpriseApplication`. For example: + [source,xml] ---- @@ -236,16 +246,18 @@ You can also override the `info` section of the OpenAPI document using the follo This override may be useful when documenting multiple modules or applications. Without it, the `info` section would be replaced with a standard one indicating that documentation from several modules was merged. -=== Configuring multiple application and multi-module support using MicroProfile Config +[#mpconfigs] +=== Configure using the MicroProfile Config You can configure the modules and applications to be included in the structured documentation by using MicroProfile Config, with the following limitations: - If conflicting configuration is found in the `server.xml` file, the MicroProfile Config settings are ignored. -- The configuration properties must be set by using a configuration source that is not specific to an application. For example, you can use system properties, environment variables, or `` elements in the `server.xml` file. +- The configuration properties must be set by using a configuration source that is not specific to an application. For example, you can use system properties, environment variables, or `variable` elements in the `server.xml` file. The following table lists the MicroProfile Config properties that can be specified to configure which modules or applications are included in the generated OpenAPI documentation. + .Configuration properties for multiple application and multi-module application support [%header,cols="3,6,6a"] |=== @@ -276,11 +288,11 @@ This value excludes no applications or web modules. |=== -**Notes:** +==== Multi-module naming rules -- When you configure support for multiple applications and multi-module environments by using MicroProfile Config, the application name is taken from the application's deployment descriptor (application.xml or web.xml). If there is no deployment descriptor or if it does not specify a name, the name defaults to the application archive filename with the extension removed. +- When you configure support for multiple applications and multi-module environments by using MicroProfile Config, the application name is taken from the application's deployment descriptor (`application.xml` or `web.xml`). If there is no deployment descriptor or if it does not specify a name, the name defaults to the application archive filename with the extension removed. + -- The module name follows the same rules as described for the server.xml configuration. +- The module name follows the same rules as described for the `server.xml` configuration. == See also From 0f1c4ab6522942993067bd77585e87ecff981d6d Mon Sep 17 00:00:00 2001 From: David Mueller Date: Tue, 19 Nov 2024 13:40:59 -0500 Subject: [PATCH 46/81] Edits per dons review #7655 --- modules/ROOT/pages/microprofile-telemetry.adoc | 16 ++++++++-------- .../pages/microprofile-config-properties.adoc | 11 ++++++----- 2 files changed, 14 insertions(+), 13 deletions(-) diff --git a/modules/ROOT/pages/microprofile-telemetry.adoc b/modules/ROOT/pages/microprofile-telemetry.adoc index 6c024dfb9..2c0960ddc 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -14,7 +14,7 @@ The OpenTelemetry project is a collection of open source, vendor-independent resources for collecting and managing application telemetry data. With Open Liberty and MicroProfile Telemetry 2.0 and later, you can manage logs, metrics, and traces in a standardized way by using the OpenTelemetry protocol. -OpenTelemetry provides a link:https://opentelemetry.io/docs/collector/[collector] component that can receive telemetry data from your runtime and applications and export it to backend services of your choice for monitoring and analysis. By default, all OpenTelemetry data is exported by using the OpenTelemetry Protocol (OTLP). OTLP defines the encoding of telemetry data and the protocol that is used to exchange data between a client and server. Many backend services accept OTLP data without requiring conversion, but OpenTelemetry also provides a collection of service-specific exporters for popular open source and commercial services, such as link:https://zipkin.io/[Zipkin] and link:https://prometheus.io/[Prometheus]. You can configure exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. +OpenTelemetry provides a link:https://opentelemetry.io/docs/collector/[collector] component that can receive telemetry data from your runtime and applications and export it to backend services of your choice for monitoring and analysis. By default, all OpenTelemetry data is exported by using the OpenTelemetry Protocol (OTLP). OTLP defines the encoding of telemetry data and the protocol that is used to exchange data between a client and server. Many backend services accept OTLP data without requiring conversion, but OpenTelemetry also provides a collection of service-specific exporters for popular open source and commercial services, such as link:https://zipkin.io/[Zipkin] and link:https://prometheus.io/[Prometheus]. You can configure exporter settings by specifying system properties or environment variables. OpenTelemetry is implemented in Open Liberty through the feature:mpTelemetry[display=MicroProfile Telemetry] feature. When you enable the MicroProfile Telemetry feature 2.0 or later and specify the required configuration property, Open Liberty automatically collects and exports logs, traces, and metrics at the application or runtime level. For many common application scenarios, no changes are needed in your application code to collect this data. MicroProfile Telemetry 1.1 and earlier enables only the collection of traces and only at the application level. @@ -102,9 +102,9 @@ otel.service.name=A2 + This configuration creates all telemetry from Application 1 with the service name `A1`, and from Application 2 with the service name `A2`. -* You can also use a combination of runtime-level and application-level configuration, so that some settings apply to all applications on the runtime, while others are specific to each application. This strategy can save you from having to duplicate general configuration settings in multiple applications on the same runtime. Any runtime-level configuration takes precedence over application-level configuration. Therefore, you can enable OpenTelemetry and assign a service name individually for each application, but specify other settings at the runtime level to apply globally to all applications on the runtime. +* You can also use a combination of runtime-level and application-level configuration, so that some settings apply to all applications on the runtime, while others are specific to each application. This strategy can save you from having to duplicate general configuration settings in multiple applications on the same runtime. Any runtime-level configuration takes precedence over application-level configuration. Therefore, you can enable OpenTelemetry and assign a service name individually for each application, but specify other settings at the runtime level to apply globally to all applications on the runtime. To combine runtime and application-level configuration, you must set the `otel.sdk.disabled=false` at the application level and not in a runtime-level configuration source. + -For example, you might want to collect a unique set of telemetry data for each application in the runtime, but have all applications use the same OpenTelemetry logs exporter. You can set the OpenTelemetry logs exporter at the runtime-level by adding th following property in the `bootstrap.properties` file: +For example, you might want to collect a unique set of telemetry data for each application in the runtime, but have all applications use the same OpenTelemetry logs exporter. You can set the OpenTelemetry logs exporter at the runtime-level by adding the following property in the `bootstrap.properties` file: + ---- otel.logs.exporter=myExporter @@ -124,7 +124,7 @@ After you enable the MicroProfile Telemetry feature and set the `otel.sdk.disabl [#config] == OpenTelemetry settings and configuration -By default, all OpenTelemetry data is exported by using the link:https://github.com/open-telemetry/oteps/blob/main/text/0035-opentelemetry-protocol.md[OpenTelemetry Protocol] (OTLP) at the `\http://localhost:4317` endpoint. You can configure alternative exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. Open Liberty supports all link:https://opentelemetry.io/docs/languages/java/configuration/#environment-variables-and-system-properties[OpenTelemtry Java configuration properties]. +By default, all OpenTelemetry data is exported by using the link:https://github.com/open-telemetry/oteps/blob/main/text/0035-opentelemetry-protocol.md[OpenTelemetry Protocol] (OTLP) at the `\http://localhost:4317` endpoint. You can configure alternative exporter settings by specifying system properties or environment variables. Open Liberty supports all link:https://opentelemetry.io/docs/languages/java/configuration/#environment-variables-and-system-properties[OpenTelemetry Java configuration properties]. To change the endpoint that the default `otlp` exporter uses, set the `otel.exporter.otlp.endpoint` property. For example, you can set the following property in the `bootstrap.properties` file to change the endpoint for all `otlp` logs, metrics, and traces from the `\http://localhost:4317` default to `\http://localhost:9080`: @@ -144,7 +144,7 @@ When you change the exporter value to `zipkin`, OpenTelemetry exports traces to For debugging purposes, you can also temporarily configure your logs, metrics, or traces to be exported to the `console.log` file. For more information, see xref:telemetry-troubleshooting.adoc#console[Exporting logs, metrics, or traces to the console for debugging purposes]. -For information about commonly-used configuration properties for logs, metrics, and trace settings, see xref:reference:microprofile-config-properties.adoc#telemetry[MicroProfile Config properties: MicroProfile Telemetry]. +For information about commonly-used configuration properties for logs, metrics, and trace settings, see xref:reference:microprofile-config-properties.adoc#telemetry[MicroProfile Telemetry: OpenTelemetry properties]. [#traces] === Trace defaults @@ -160,14 +160,14 @@ OpenTelemetry automatically collects runtime and application logs that are sent For information about Liberty log event fields for OpenTelemetry, see xref:mptel-log-events-list.adoc[MicroProfile Telemetry log events reference list]. -When you use the `otlp` default log exporter, the OpenTelemetry Batch LogRecord Processor (BLRP) is enabled and log records are exported in batches according to BLRP default settings. You can adjust these settings with `otel.blrp.*` properties. For more information about the available properties and their default settings, see xref:reference:microprofile-config-properties.adoc#telemetry[MicroProfile Config properties: MicroProfile Telemetry]. +When you use the `otlp` default log exporter, the OpenTelemetry Batch LogRecord Processor (BLRP) is enabled and log records are exported in batches according to BLRP default settings. You can adjust these settings with `otel.blrp.*` properties. For more information about the available properties and their default settings, see xref:reference:microprofile-config-properties.adoc#telemetry[MicroProfile Telemetry: OpenTelemetry properties]. [#metrics] === Metrics defaults -When you enable OpenTelemetry for Open Liberty, a default set of metrics is automatically collected and exported according to the configured OpenTelemetry exporter settings. OpenTelemetry collects both JVM runtime-environment metrics and HTTP metrics. For more information about these metrics, see the xref:mptelemetry-metrics-list.adoc[MicroProfile Telemetry metrics reference list]. You can also use the OpenTelemetry API to xref:custom-mptelemetry-metrics.adoc[define custom metrics] in your application code for OpenTelemetry to collect and export. +When you enable OpenTelemetry for Open Liberty, a default set of metrics is automatically collected and exported according to the configured OpenTelemetry exporter settings. For more information about these metrics, see the xref:mptelemetry-metrics-list.adoc[MicroProfile Telemetry metrics reference list]. You can also use the OpenTelemetry API to xref:custom-mptelemetry-metrics.adoc[define custom metrics] in your application code for OpenTelemetry to collect and export. -You can configure the metrics exporter settings, including the export interval and timeout values, by setting system properties. For more information, see xref:reference:microprofile-config-properties.adoc#telemetry[MicroProfile Config properties: MicroProfile Telemetry]. +You can configure the metrics exporter settings, including the export interval and timeout values, by setting system properties. For more information, see xref:reference:microprofile-config-properties.adoc#telemetry[MicroProfile Telemetry: OpenTelemetry properties]. == See also diff --git a/modules/reference/pages/microprofile-config-properties.adoc b/modules/reference/pages/microprofile-config-properties.adoc index 3eee3814d..e7deedc96 100644 --- a/modules/reference/pages/microprofile-config-properties.adoc +++ b/modules/reference/pages/microprofile-config-properties.adoc @@ -29,7 +29,7 @@ The following sections provide tables that list and describe MicroProfile Config - <<#openapi,MicroProfile OpenAPI>> - <<#react,MicroProfile Reactive Messaging>> - <<#rest,MicroProfile Rest Client>> -- <<#telemetry, MicroProfile Telemetry>> +- <<#telemetry, MicroProfile Telemetry: OpenTelemetry properties>> [#context] @@ -612,13 +612,14 @@ This property or `*/mp-rest/url` is considered required. However, some implement |=== [#telemetry] -== MicroProfile Telemetry +== MicroProfile Telemetry: OpenTelemetry properties -The following MicroProfile Config properties can be specified when MicroProfile Telemetry is enabled. This table lists the most important properties. For the full list, see the link:https://opentelemetry.io/docs/languages/java/configuration/#environment-variables-and-system-properties[OpenTelemtry Java configuration properties]. +The following OpenTelemetry properties can be specified when MicroProfile Telemetry is enabled. This table lists the most important properties. For the full list, see the link:https://opentelemetry.io/docs/languages/java/configuration/#environment-variables-and-system-properties[OpenTelemtry Java configuration properties]. + +You can enable OpenTelemetry at the runtime level to gather telemetry data from both the runtime and application. When you choose this option, you specify OpenTelemetry properties in runtime-level configuration sources instead of in application-level `microprofile-config.properties` files. In most cases, runtime-level configuration is preferred because it includes both runtime-level telemetry and application-specific telemetry. Alternatively, if your runtime hosts more tha one application, you can enable OpenTelemetry and and configure OpenTelemetry properties at the application level, for example, in microprofile-config.properties` files for each application. However, this option does not enable runtime telemetry. For more information, see xref:ROOT:microprofile-telemetry.adoc[OpenTelemetry]. -The runtime reads properties in the following table at either application startup or runtime startup, depending on when the OpenTelemetry instance initializes. In cases where each application is configured to use a separate OpenTelemetry instance, the runtime reads the properties at application startup. In cases where all applications on the runtime share a single OpenTelemetry instance, the runtime reads the properties at runtime startup. -For more information about collecting Open Liberty logs, metrics, and traces, see xref:ROOT:microprofile-telemetry.adoc[OpenTelemetry]. +The runtime reads properties in the following table at either application startup or runtime startup, depending on when the OpenTelemetry instance initializes. In cases where each application is configured to use a separate OpenTelemetry instance, the runtime reads the properties at application startup. In cases where all applications on the runtime share a single OpenTelemetry instance, the runtime reads the properties at runtime startup. .MicroProfile Config properties for MicroProfile Telemetry [options="header"] From c9f81e88c78b4f2b7b1c3c9a1815949a17821fd7 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Tue, 19 Nov 2024 15:29:31 -0500 Subject: [PATCH 47/81] Update microprofile-config-properties.adoc --- modules/reference/pages/microprofile-config-properties.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/reference/pages/microprofile-config-properties.adoc b/modules/reference/pages/microprofile-config-properties.adoc index e7deedc96..e91abce80 100644 --- a/modules/reference/pages/microprofile-config-properties.adoc +++ b/modules/reference/pages/microprofile-config-properties.adoc @@ -621,7 +621,7 @@ You can enable OpenTelemetry at the runtime level to gather telemetry data from The runtime reads properties in the following table at either application startup or runtime startup, depending on when the OpenTelemetry instance initializes. In cases where each application is configured to use a separate OpenTelemetry instance, the runtime reads the properties at application startup. In cases where all applications on the runtime share a single OpenTelemetry instance, the runtime reads the properties at runtime startup. -.MicroProfile Config properties for MicroProfile Telemetry +.OpenTelemetry properties enabled by MicroProfile Telemetry [options="header"] |=== |Name |Description |When the runtime reads the property |Example From 18e627760d45872d4c046c849f0a6920a33120f5 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Wed, 20 Nov 2024 12:53:11 +0530 Subject: [PATCH 48/81] 7610-MicroProfile 7.0 ID-5 7610-MicroProfile 7.0 ID-5 #7610 --- .../reference/pages/diff/mp-61-70-diff.adoc | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/modules/reference/pages/diff/mp-61-70-diff.adoc b/modules/reference/pages/diff/mp-61-70-diff.adoc index b205260c8..9d74f16bf 100644 --- a/modules/reference/pages/diff/mp-61-70-diff.adoc +++ b/modules/reference/pages/diff/mp-61-70-diff.adoc @@ -28,15 +28,15 @@ This release includes several significant changes. If you are updating your application from using MicroProfile 6.1 features to using link:https://github.com/eclipse/microprofile/releases/tag/7.0[MicroProfile 7.0] features, the changes in API behavior might require you to update your application code. The following sections provide details about migrating your applications from MicroProfile 6.1 to MicroProfile 7.0: -- <<#mp, MicroProfile 7.0 vs. MicroProfile 6.1>> +- <<#mp, Differences between MicroProfile 7.0 and 6.1>> - <<#rc, Differences between MicroProfile REST Client 4.0 and 3.0>> -- <<#openapi, Differences between MicroProfile OpenAPI 3.1 and 4.0>> -- <<#ft, Fault Tolerance Version Updated to 4.1>> -- <<#tm, Telemetry Version Updated to 2.0>> +- <<#openapi, Differences between MicroProfile OpenAPI 4.0 and 3.1>> +- <<#ft, Differences between Fault Tolerance 4.1 and 4.0>> +- <<#tm, Differences between Telemetry 2.0 and 1.1>> [#mp] -== MicroProfile 7.0 vs. MicroProfile 6.1 +== Differences between MicroProfile 7.0 and 6.1 link:https://download.eclipse.org/microprofile/microprofile-7.0/microprofile-spec-7.0.html[MicroProfile 7.0] is a major release that includes backward-incompatible changes. One significant update is the replacement of MicroProfile Metrics with MicroProfile Telemetry 2.0, which offers Metrics capabilities in addition to support for logs and tracing. @@ -91,9 +91,9 @@ Information and example code are added to the link:https://download.eclipse.org/ [#openapi] -== Differences between MicroProfile OpenAPI 3.1 and 4.0 +== Differences between MicroProfile OpenAPI 4.0 and 3.1 -=== OpenAPI Version Updated to 3.1 +=== OpenAPI version updated to 3.1 The OpenAPI document is now generated in OpenAPI 3.1 format by default, an update from OpenAPI 3.0 in `mpOpenAPI-3.1`. @@ -128,7 +128,7 @@ For more information on this configuration, see feature:mpOpenAPI-4.0[display=Mi [#ft] -== Fault Tolerance Version Updated to 4.1 +== Differences between Fault Tolerance 4.1 and 4.0 MicroProfile Fault Tolerance 4.1, an update to version 4.0, introduces integration with MicroProfile Telemetry 2.0. This allows Fault Tolerance to export metrics directly to MicroProfile Telemetry. The existing integration with `mpMetrics` remains unchanged. @@ -227,7 +227,7 @@ If `mpFaultTolerance-4.1` is enabled alongside both `mpTelemetry-2.0` and `mpMet [#tm] -== Telemetry Version Updated to 2.0 +== Differences between MicroProfile Telemetry 2.0 and 1.1 MicroProfile Telemetry 2.0 is an update to MicroProfile Telemetry 1.1, incorporating the latest OpenTelemetry SDK (version 1.39). Previously, only traces were collected and exported. The updated feature now includes the ability to collect and export metrics and logs. Specifically, the following enhancements are provided: @@ -279,7 +279,7 @@ To make the APIs accessible, you must enable third-party APIs for your applicati ---- -=== Collecting Logs +=== Collecting logs You can enable MicroProfile Telemetry to collect logs from various sources within the Open Liberty runtime environment. MicroProfile Telemetry can collect the following types of events: @@ -296,7 +296,7 @@ To enable these log sources, configure the source attribute for the mpTelemetry The mpTelemetry configuration element is optional. If you do not specify it or omit the source attribute, the default configuration source is message. For more details, see feature:mpTelemetry-2.0[display=Collect logs from a specified source]. -=== Exporting Metrics and Logs +=== Exporting metrics and logs By default, all OpenTelemetry data is exported to link:https://opentelemetry.io/docs/specs/otel/protocol/exporter/[OTLP]. You can change the export settings for metrics by specifying the `otel.metrics.exporter` property or the `OTEL_METRICS_EXPORTER` environment variable. For logs, specify the `otel.logs.exporter` property or the `OTEL_LOGS_EXPORTER` environment variable. From 4d78db24f4d99308272d413b0a8291b14b460a0f Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Wed, 20 Nov 2024 14:54:44 +0530 Subject: [PATCH 49/81] 7610-MicroProfile 7.0 ID-6 7610-MicroProfile 7.0 ID-6 #7610 --- modules/reference/pages/diff/mp-61-70-diff.adoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/modules/reference/pages/diff/mp-61-70-diff.adoc b/modules/reference/pages/diff/mp-61-70-diff.adoc index 9d74f16bf..cffccc8b2 100644 --- a/modules/reference/pages/diff/mp-61-70-diff.adoc +++ b/modules/reference/pages/diff/mp-61-70-diff.adoc @@ -40,16 +40,16 @@ If you are updating your application from using MicroProfile 6.1 features to usi link:https://download.eclipse.org/microprofile/microprofile-7.0/microprofile-spec-7.0.html[MicroProfile 7.0] is a major release that includes backward-incompatible changes. One significant update is the replacement of MicroProfile Metrics with MicroProfile Telemetry 2.0, which offers Metrics capabilities in addition to support for logs and tracing. -If you are using MicroProfile Metrics from MicroProfile 6.1, you will need to add the following in your `server.xml` file when upgrading to MicroProfile 7.0. +If you are using MicroProfile Metrics from MicroProfile 6.1, you need to add the following in your `server.xml` file when upgrading to MicroProfile 7.0. [source,xml] ---- mpMetrics-5.1 ---- -If your application does not use any APIs from MicroProfile Metrics, your application will have the Metrics from MicroProfile Telemetry 2.0, and no migration effort is required. +If your application does not use any APIs from MicroProfile Metrics, your application has the Metrics from MicroProfile Telemetry 2.0, and no migration effort is required. -In Open Liberty, the Jakarta EE 10 Core Profile features are automatically included with the `microProfile-7.0` feature to provide a smoother upgrade experience from `microProfile-6.1`. +In Open Liberty, the feature:jakartaee-10.0[display=Jakarta EE 10 Core Profile] features are automatically included with the `microProfile-7.0` feature to provide a smoother upgrade experience from `microProfile-6.1`. @@ -58,7 +58,7 @@ In Open Liberty, the Jakarta EE 10 Core Profile features are automatically inclu With the release of the feature:mpRestClient-4.0[display=MicroProfile REST Client 4.0] feature, the underlying MicroProfile REST Client implementation for Open Liberty is now compatible with Jakarta EE 10 and is designed to tolerate Jakarta EE 11. -The following sections provide details about changes in behavior between the feature:mpRestClient-3.0[display=mpRestClient-3.0] and feature:mpRestClient-4.0[display=mpRestClient-4.0] features. +The following sections provide details about changes in behavior between the feature:mpRestClient-3.0[display=MicroProfile Rest Client 3.0] and feature:mpRestClient-4.0[display=MicroProfile Rest Client 4.0] features. === Client creation without URI @@ -85,7 +85,7 @@ RestClientBuilder.newBuilder() .build(SomeClient.class) ---- -=== Processing Multipart Data +=== Processing multipart data Information and example code are added to the link:https://download.eclipse.org/microprofile/microprofile-rest-client-4.0/microprofile-rest-client-spec-4.0.html#_processing_multipart_data[MicroProfile Rest Client 4.0 specification] for processing multipart data, introduced as part of RESTful Web Services version 3.1 in EE10. From 6e6bd861f5e4e8a916cd2fa268fa49c082f0cbf1 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Wed, 20 Nov 2024 10:59:16 -0500 Subject: [PATCH 50/81] add 240012 CVE and update links #7719 --- .../ROOT/pages/security-vulnerabilities.adoc | 139 +++++++++--------- 1 file changed, 73 insertions(+), 66 deletions(-) diff --git a/modules/ROOT/pages/security-vulnerabilities.adoc b/modules/ROOT/pages/security-vulnerabilities.adoc index 512e9f656..5c9ed845b 100644 --- a/modules/ROOT/pages/security-vulnerabilities.adoc +++ b/modules/ROOT/pages/security-vulnerabilities.adoc @@ -28,6 +28,13 @@ 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 +|https://www.cve.org/CVERecord?id=CVE-2024-40094[CVE-2024-40094] +|5.3 +|Denial of service +|20.0.0.6 - 24.0.0.11 +|24.0.0.12 +|Affects the feature:mpGraphQL-1.0[] and feature:mpGraphQL-2.0[] features + |https://www.cve.org/CVERecord?id=CVE-2024-7254[CVE-2024-7254] |7.5 |Denial of service @@ -35,462 +42,462 @@ The `CWWKF0012I` message uses the word "installed", but it lists features that a |24.0.0.11 |Affects the feature:grpc-1.0[] and feature:grpcClient-1.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-50314[CVE-2023-50314] +|http://www.cve.org/CVERecord?id=CVE-2023-50314[CVE-2023-50314] |5.3 |Information disclosure |17.0.0.3 - 24.0.0.8 |24.0.0.9 | -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-22354[CVE-2024-22354] +|http://www.cve.org/CVERecord?id=CVE-2024-22354[CVE-2024-22354] |7.0 |XML External Entity (XXE) injection |17.0.0.3 - 24.0.0.5 |24.0.0.6 | -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-27268[CVE-2024-27268] +|http://www.cve.org/CVERecord?id=CVE-2024-27268[CVE-2024-27268] |5.9 |Denial of service |18.0.0.2 - 24.0.0.4 |24.0.0.5 |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-2024-22353[CVE-2024-22353] +|http://www.cve.org/CVERecord?id=CVE-2024-22353[CVE-2024-22353] |5.9 |Denial of service |17.0.0.3 - 24.0.0.4 |24.0.0.5 |Affects the feature:openidConnectClient-1.0[], and feature:socialLogin-1.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-25026[CVE-2024-25026] +|http://www.cve.org/CVERecord?id=CVE-2024-25026[CVE-2024-25026] |5.9 |Denial of service |17.0.0.3 - 24.0.0.4 |24.0.0.5 |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-51775[CVE-2023-51775] +|http://www.cve.org/CVERecord?id=CVE-2023-51775[CVE-2023-51775] |7.5 |Denial of service |21.0.0.3 - 24.0.0.3 |24.0.0.4 |Affects the feature:openidConnectClient-1.0[], feature:socialLogin-1.0[], feature:mpJwt-1.2[], feature:mpJwt-2.0[], feature:mpJwt-2.1[], feature:jwt-1.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-27270[CVE-2024-27270] +|http://www.cve.org/CVERecord?id=CVE-2024-27270[CVE-2024-27270] |4.7 |Cross-site scripting |23.0.0.3 - 24.0.0.3 |24.0.0.4 |Affects the feature:servlet-6.0[] feature -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-50312[CVE-2023-50312] +|http://www.cve.org/CVERecord?id=CVE-2023-50312[CVE-2023-50312] |5.3 |Weaker security |17.0.0.3 - 24.0.0.2 |24.0.0.3 | -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-44487[CVE-2023-44487] +|http://www.cve.org/CVERecord?id=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] +|http://www.cve.org/CVERecord?id=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] +|http://www.cve.org/CVERecord?id=CVE-2023-46158[CVE-2023-46158] |4.9 |Weaker security |23.0.0.9 - 23.0.0.10 |23.0.0.11 |Affects the feature:appSecurity-1.0[], feature:appSecurity-2.0[], feature:appSecurity-3.0[], feature:appSecurity-4.0[] and feature:appSecurity-5.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-38737[CVE-2023-38737] +|http://www.cve.org/CVERecord?id=CVE-2023-38737[CVE-2023-38737] |5.9 |Denial of service |22.0.0.13 - 23.0.0.7 |23.0.0.8 |Affects the feature:restfulWS-3.0[] and feature:restfulWS-3.1[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-28867[CVE-2023-28867] +|http://www.cve.org/CVERecord?id=CVE-2023-28867[CVE-2023-28867] |7.5 |Denial of service |17.0.0.3 - 23.0.0.5 |23.0.0.6 |Affects the feature:mpGraphQL-1.0[] and feature:mpGraphQL-2.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-24998[CVE-2023-24998] +|http://www.cve.org/CVERecord?id=CVE-2023-24998[CVE-2023-24998] |7.5 |Denial of service |17.0.0.3 - 23.0.0.3 |23.0.0.4 |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-0482[CVE-2023-0482] +|http://www.cve.org/CVERecord?id=CVE-2023-0482[CVE-2023-0482] |5.3 |Privilege escalation |21.0.0.12 - 23.0.0.3 |23.0.0.4 |Affects the feature:restfulWS-3.0[] and feature:restfulWS-3.1[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-45787[CVE-2022-45787] +|http://www.cve.org/CVERecord?id=CVE-2022-45787[CVE-2022-45787] |5.5 |Information disclosure |21.0.0.12 - 23.0.0.1 |23.0.0.2 |Affects the feature:restfulWS-3.0[] feature -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-46364[CVE-2022-46364] +|http://www.cve.org/CVERecord?id=CVE-2022-46364[CVE-2022-46364] |9.8 |Server-side request forgery |17.0.0.3 - 23.0.0.1 |23.0.0.2 |Affects the feature:jaxws-2.2[] feature -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-3509[CVE-2022-3509] +|http://www.cve.org/CVERecord?id=CVE-2022-3509[CVE-2022-3509] |5.7 |Denial of service |21.0.0.2 - 22.0.0.12 |22.0.0.13 |Affects the feature:grpc-1.0[] and feature:grpcClient-1.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-3171[CVE-2022-3171] +|http://www.cve.org/CVERecord?id=CVE-2022-3171[CVE-2022-3171] |5.7 |Denial of service |21.0.0.2 - 22.0.0.12 |22.0.0.13 |Affects the feature:grpc-1.0[] and feature:grpcClient-1.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-37734[CVE-2022-37734] +|http://www.cve.org/CVERecord?id=CVE-2022-37734[CVE-2022-37734] |7.5 |Denial of service |17.0.0.3 - 22.0.0.11 |22.0.0.12 |Affects the feature:mpGraphQL-1.0[] and feature:mpGraphQL-2.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-24839[CVE-2022-24839] +|http://www.cve.org/CVERecord?id=CVE-2022-24839[CVE-2022-24839] |7.5 |Denial of service |17.0.0.3 - 22.0.0.10 |22.0.0.11 |Affects the feature:openid-2.0[] feature -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-34165[CVE-2022-34165] +|http://www.cve.org/CVERecord?id=CVE-2022-34165[CVE-2022-34165] |5.4 |HTTP header injection |17.0.0.3 - 22.0.0.9 |22.0.0.10 | -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-22476[CVE-2022-22476] +|http://www.cve.org/CVERecord?id=CVE-2022-22476[CVE-2022-22476] |5 |Identity spoofing |17.0.0.3 - 22.0.0.7 |22.0.0.8 |Affects the feature:appSecurity-1.0[], feature:appSecurity-2.0[], feature:appSecurity-3.0[] and feature:appSecurity-4.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-22475[CVE-2022-22475] +|http://www.cve.org/CVERecord?id=CVE-2022-22475[CVE-2022-22475] |7.1 |Identity spoofing |17.0.0.3 - 22.0.0.5 |22.0.0.6 |Affects the feature:appSecurity-1.0[], feature:appSecurity-2.0[], feature:appSecurity-3.0[] and feature:appSecurity-4.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-22393[CVE-2022-22393] +|http://www.cve.org/CVERecord?id=CVE-2022-22393[CVE-2022-22393] |3.1 |Information disclosure |17.0.0.3 - 22.0.0.5 |22.0.0.6 |Affects the feature:adminCenter-1.0[] feature -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-39038[CVE-2021-39038] +|http://www.cve.org/CVERecord?id=CVE-2021-39038[CVE-2021-39038] |4.4 |Clickjacking vulnerability |17.0.0.3 - 22.0.0.2 |22.0.0.3 |Affects the feature:openapi-3.1[], feature:mpOpenAPI-1.0[], feature:mpOpenAPI-1.1[] and feature:mpOpenAPI-2.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-23450[CVE-2021-23450] +|http://www.cve.org/CVERecord?id=CVE-2021-23450[CVE-2021-23450] |9.8 |Remote code execution |17.0.0.3 - 22.0.0.2 |22.0.0.3 |Affects the feature:admin-Center-1.0[] feature -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-46708[CVE-2021-46708] +|http://www.cve.org/CVERecord?id=CVE-2021-46708[CVE-2021-46708] |4.3 |Clickjacking |21.0.0.12 - 22.0.0.1 |22.0.0.2 |Affects the feature:openapi-3.1[], feature:mpOpenAPI-1.0[], feature:mpOpenAPI-1.1[], feature:mpOpenAPI-2.0[] and feature:mpOpenAPI-3.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-25031[CVE-2018-25031] +|http://www.cve.org/CVERecord?id=CVE-2018-25031[CVE-2018-25031] |5.4 |Spoofing attack |21.0.0.12 - 22.0.0.1 |22.0.0.2 |Affects the feature:openapi-3.1[], feature:mpOpenAPI-1.0[], feature:mpOpenAPI-1.1[], feature:mpOpenAPI-2.0[] and feature:mpOpenAPI-3.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-39031[CVE-2021-39031] +|http://www.cve.org/CVERecord?id=CVE-2021-39031[CVE-2021-39031] |7.5 |LDAP injection |17.0.0.3 - 22.0.0.1 |22.0.0.2 |Affects the feature:ldapRegistry-3.0[] feature -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-22310[CVE-2022-22310] +|http://www.cve.org/CVERecord?id=CVE-2022-22310[CVE-2022-22310] |4.8 |Information disclosure |21.0.0.10 - 21.0.0.12 |22.0.0.1 |Affects the feature:jaxws-2.2[] feature -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-36090[CVE-2021-36090] +|http://www.cve.org/CVERecord?id=CVE-2021-36090[CVE-2021-36090] |7.5 |Denial of service |17.0.0.3 - 21.0.0.9 |21.0.0.10 | -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-35517[CVE-2021-35517] +|http://www.cve.org/CVERecord?id=CVE-2021-35517[CVE-2021-35517] |5.5 |Denial of service |17.0.0.3 - 21.0.0.9 |21.0.0.10 | -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-29842[CVE-2021-29842] +|http://www.cve.org/CVERecord?id=CVE-2021-29842[CVE-2021-29842] |3.7 |Information disclosure |17.0.0.3 - 21.0.0.9 |21.0.0.10 |Affects the feature:federatedRegistry-1.0[] feature -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-26296[CVE-2021-26296] +|http://www.cve.org/CVERecord?id=CVE-2021-26296[CVE-2021-26296] |8.8 |Cross-site request forgery |17.0.0.3 - 21.0.0.3 |21.0.0.4 |Affects the feature:jsf-2.2[] and feature:jsf-2.3[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-10693[CVE-2020-10693] +|http://www.cve.org/CVERecord?id=CVE-2020-10693[CVE-2020-10693] |5.3 |Bypass security |17.0.0.3 - 20.0.0.10 |20.0.0.11 |Affects the feature:beanValidation-2.0[] feature -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-4590[CVE-2020-4590] +|http://www.cve.org/CVERecord?id=CVE-2020-4590[CVE-2020-4590] |5.3 |Denial of service |19.0.0.5 - 20.0.0.9 |20.0.0.10 |Affects the feature:oauth-2.0[] and feature:openidConnectServer-1.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-4421[CVE-2020-4421] +|http://www.cve.org/CVERecord?id=CVE-2020-4421[CVE-2020-4421] |5 |Identity spoofing |19.0.0.5 - 20.0.0.4 |20.0.0.5 |Affects the feature:openidConnectServer-1.0[] feature -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-4329[CVE-2020-4329] +|http://www.cve.org/CVERecord?id=CVE-2020-4329[CVE-2020-4329] |4.3 |Information disclosure |17.0.0.3 - 20.0.0.4 |20.0.0.5 |Affects the feature:servlet-3.1[], feature:servlet-4.0[], feature:appSecurity-2.0[], and feature:appSecurity-3.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-4303[CVE-2020-4303] +|http://www.cve.org/CVERecord?id=CVE-2020-4303[CVE-2020-4303] |6.1 |Cross-site scripting |17.0.0.3 - 20.0.0.3 |20.0.0.4 |Affects the feature:oauth-2.0[], feature:openidConnectClient-1.0[], feature:openidConnectServer-1.0[], and feature:samlWeb-2.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-4304[CVE-2020-4304] +|http://www.cve.org/CVERecord?id=CVE-2020-4304[CVE-2020-4304] |6.1 |Cross-site scripting |17.0.0.3 - 20.0.0.3 |20.0.0.4 |Affects the feature:oauth-2.0[], feature:openidConnectClient-1.0[], feature:openidConnectServer-1.0[], and feature:samlWeb-2.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-17573[CVE-2019-17573] +|http://www.cve.org/CVERecord?id=CVE-2019-17573[CVE-2019-17573] |6.1 |Cross-site scripting |17.0.0.3 - 20.0.0.2 |20.0.0.3 |Affects the feature:jaxws-2.2[] feature -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-12406[CVE-2019-12406] +|http://www.cve.org/CVERecord?id=CVE-2019-12406[CVE-2019-12406] |5.3 |Denial of service |17.0.0.3 - 20.0.0.1 |20.0.0.2 |Affects the feature:jaxrs-2.0[], feature:jaxrs-2.1[], and feature:jaxws-2.2[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-4720[CVE-2019-4720] +|http://www.cve.org/CVERecord?id=CVE-2019-4720[CVE-2019-4720] |7.5 |Denial of service |17.0.0.3 - 20.0.0.1 |20.0.0.2 | -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-17495[CVE-2019-17495] +|http://www.cve.org/CVERecord?id=CVE-2019-17495[CVE-2019-17495] |5.3 |Information disclosure |17.0.0.3 - 19.0.0.12 |20.0.0.1 |Affects the feature:mpOpenAPI-1.0[], feature:mpOpenAPI-1.1[], and feature:openapi-3.1[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-4441[CVE-2019-4441] +|http://www.cve.org/CVERecord?id=CVE-2019-4441[CVE-2019-4441] |5.3 |Information disclosure |17.0.0.3 - 19.0.0.10 |19.0.0.11 |Affects the feature:jsp-2.2[] and feature:jsp-2.3[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-3603[CVE-2014-3603] +|http://www.cve.org/CVERecord?id=CVE-2014-3603[CVE-2014-3603] |6.8 |Spoofing |17.0.0.3 - 19.0.0.10 |19.0.0.11 |Affects the feature:wsSecurity-1.1[] and feature:samlWeb-2.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-9518[CVE-2019-9518] +|http://www.cve.org/CVERecord?id=CVE-2019-9518[CVE-2019-9518] |7.5 |Denial of service |17.0.0.3 - 19.0.0.9 |19.0.0.10 |Affects the feature:servlet-3.1[] and feature:servlet-4.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-9517[CVE-2019-9517] +|http://www.cve.org/CVERecord?id=CVE-2019-9517[CVE-2019-9517] |7.5 |Denial of service |17.0.0.3 - 19.0.0.9 |19.0.0.10 |Affects the feature:servlet-3.1[] and feature:servlet-4.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-9515[CVE-2019-9515] +|http://www.cve.org/CVERecord?id=CVE-2019-9515[CVE-2019-9515] |7.5 |Denial of service |17.0.0.3 - 19.0.0.9 |19.0.0.10 |Affects the feature:servlet-3.1[] and feature:servlet-4.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-9514[CVE-2019-9514] +|http://www.cve.org/CVERecord?id=CVE-2019-9514[CVE-2019-9514] |7.5 |Denial of service |17.0.0.3 - 19.0.0.9 |19.0.0.10 |Affects the feature:servlet-3.1[] and feature:servlet-4.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-9513[CVE-2019-9513] +|http://www.cve.org/CVERecord?id=CVE-2019-9513[CVE-2019-9513] |7.5 |Denial of service |17.0.0.3 - 19.0.0.9 |19.0.0.10 |Affects the feature:servlet-3.1[] and feature:servlet-4.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-9512[CVE-2019-9512] +|http://www.cve.org/CVERecord?id=CVE-2019-9512[CVE-2019-9512] |7.5 |Denial of service |17.0.0.3 - 19.0.0.9 |19.0.0.10 |Affects the feature:servlet-3.1[] and feature:servlet-4.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-4304[CVE-2019-4304] +|http://www.cve.org/CVERecord?id=CVE-2019-4304[CVE-2019-4304] |6.3 |Bypass security |17.0.0.3 - 19.0.0.9 |19.0.0.10 |Affects the feature:appSecurity-1.0[] and feature:appSecurity-2.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-4305[CVE-2019-4305] +|http://www.cve.org/CVERecord?id=CVE-2019-4305[CVE-2019-4305] |5.3 |Information disclosure |17.0.0.3 - 19.0.0.9 |19.0.0.10 |Affects the feature:appSecurity-1.0[] and feature:appSecurity-2.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-3603[CVE-2014-3603] +|http://www.cve.org/CVERecord?id=CVE-2014-3603[CVE-2014-3603] |6.5 |Man-in-the-Middle |17.0.0.3 - 19.0.0.7 |19.0.0.8 |Affects the feature:wsSecurity-1.1[] and feature:samlWeb-2.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-4046[CVE-2019-4046] +|http://www.cve.org/CVERecord?id=CVE-2019-4046[CVE-2019-4046] |5.9 |Denial of service |17.0.0.3 - 19.0.0.3 |19.0.0.4 |Affects the feature:servlet-3.1[] and feature:servlet-4.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-1902[CVE-2018-1902] +|http://www.cve.org/CVERecord?id=CVE-2018-1902[CVE-2018-1902] |3.1 |Spoofing |17.0.0.3 - 19.0.0.2 |19.0.0.3 |Affects the feature:servlet-3.1[] and feature:servlet-4.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-1901[CVE-2018-1901] +|http://www.cve.org/CVERecord?id=CVE-2018-1901[CVE-2018-1901] |5.0 |Privilege escalation |17.0.0.3 - 18.0.0.3 |18.0.0.4 |Affects the feature:ldapRegistry-3.0[] feature -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-7810[CVE-2014-7810] +|http://www.cve.org/CVERecord?id=CVE-2014-7810[CVE-2014-7810] |5.0 |Bypass security |17.0.0.3 - 18.0.0.3 |18.0.0.4 |Affects the feature:jsp-2.2[], feature:jsp-2.3[], and feature:el-3.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-8039[CVE-2018-8039] +|http://www.cve.org/CVERecord?id=CVE-2018-8039[CVE-2018-8039] |7.5 |Man-in-the-Middle |17.0.0.3 - 18.0.0.2 |18.0.0.3 |Affects the feature:jaxws-2.2[], feature:jaxrs-2.0[], and feature:jaxrs-2.1[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-1755[CVE-2018-1755] +|http://www.cve.org/CVERecord?id=CVE-2018-1755[CVE-2018-1755] |5.9 |Information disclosure |17.0.0.3 - 18.0.0.2 |18.0.0.3 |Affects the feature:jaspic-1.1[] feature -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-1683[CVE-2018-1683] +|http://www.cve.org/CVERecord?id=CVE-2018-1683[CVE-2018-1683] |5.9 |Information disclosure |17.0.0.3 - 18.0.0.2 |18.0.0.3 |Affects the feature:ejbRemote-3.2[] feature -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-12624[CVE-2017-12624] +|http://www.cve.org/CVERecord?id=CVE-2017-12624[CVE-2017-12624] |5.3 |Denial of service |17.0.0.3 - 17.0.0.4 |18.0.0.1 |Affects the feature:jaxws-2.2[], feature:jaxrs-2.0[], and feature:jaxrs-2.1[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-1788[CVE-2017-1788] +|http://www.cve.org/CVERecord?id=CVE-2017-1788[CVE-2017-1788] |5.3 |Spoofing |17.0.0.3 - 17.0.0.4 |18.0.0.1 |Affects any feature that enables security, for example, the feature:appSecurity-2.0[], feature:appSecurity-3.0[], and feature:restConnector-2.0[] features -|http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-1000031[CVE-2016-100031] +|http://www.cve.org/CVERecord?id=CVE-2016-1000031[CVE-2016-100031] |9.8 |Execute code |17.0.0.3 - 17.0.0.4 From 9c7b22efc09eb48acf217df8c36f9871f17c512c Mon Sep 17 00:00:00 2001 From: David Mueller Date: Thu, 21 Nov 2024 12:03:04 -0500 Subject: [PATCH 51/81] edits per review #7442 --- modules/reference/pages/command/featureUtility-commands.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/reference/pages/command/featureUtility-commands.adoc b/modules/reference/pages/command/featureUtility-commands.adoc index 7a45a1d0d..7a2014c38 100644 --- a/modules/reference/pages/command/featureUtility-commands.adoc +++ b/modules/reference/pages/command/featureUtility-commands.adoc @@ -71,7 +71,7 @@ Supported values are `enforce`, `skip`, `all`, and `warn`. If this option is not |`no_proxy` |`http.nonProxyHosts` -|Requires Open Liberty to use a direct connection instead of a proxy for certain hosts. Specify a list of hostname patterns separated by pipe (`\|`), comma (`,`), or period (`.`) delimiters. Patterns can start or end with an asterisk (`*`) for wildcards. For any hostname that matches a specified pattern, Open Liberty connects to the host directly instead of going through a proxy. +|Requires Open Liberty to use a direct connection instead of a proxy for certain hosts. Specify a list of hostname patterns separated by pipes (`\|`) or commas (`,`). Patterns can start or end with an asterisk (`*`) for wildcards. For any hostname that matches a specified pattern, Open Liberty connects to the host directly instead of going through a proxy. |`http_proxy` |`proxyHost`, `proxyPort`, `proxyUser`, and `proxyPassword` From 4a6e61d63a6eec4e022af90d81d66e3fe602d28a Mon Sep 17 00:00:00 2001 From: David Mueller Date: Thu, 21 Nov 2024 13:47:47 -0500 Subject: [PATCH 52/81] edits per lauras review #7655 --- .../ROOT/pages/microprofile-telemetry.adoc | 35 ++++++------------- 1 file changed, 11 insertions(+), 24 deletions(-) diff --git a/modules/ROOT/pages/microprofile-telemetry.adoc b/modules/ROOT/pages/microprofile-telemetry.adoc index 2c0960ddc..97b81096a 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -35,7 +35,7 @@ To collect and export logs, metrics, and traces with OpenTelemetry in your Open * `jvm.options` file * `server.env` file + -If you choose to use the `server.env` file, specify the `OTEL_SDK_DISABLED=false` environment variable instead of the `otel.sdk.disabled=false` configuration property. +If you choose to use the `server.env` file, specify the `OTEL_SDK_DISABLED=false` environment variable instead of the configuration property. | <<#app, Application level>> | Multiple applications in the same Liberty runtime @@ -49,17 +49,9 @@ If you choose to use the `server.env` file, specify the `OTEL_SDK_DISABLED=false When your Open Liberty runtime hosts only one application, you can enable OpenTelemetry at the runtime level to collect and export logs, metrics, and traces for both the runtime and the application. -* Enable the feature:mpTelemetry[display=MicroProfile Telemetry] feature version 2.0 or later in the `featureManager` element of your `server.xml` file. -+ -[source,xml] ----- - - mpTelemetry-2.0 - ... - ----- +. Enable the feature:mpTelemetry[display=MicroProfile Telemetry] feature version 2.0 or later in the `featureManager` element of your `server.xml` file. -* Set `otel.sdk.disabled=false` as a runtime-level property, for example, in the xref:reference:config/server-configuration-overview.adoc#bootstrap-properties[bootstrap.properties] file: +. Set `otel.sdk.disabled=false` as a runtime-level property, for example, in the xref:reference:config/server-configuration-overview.adoc#bootstrap-properties[bootstrap.properties] file: + ---- otel.sdk.disabled=false @@ -72,17 +64,9 @@ After you enable the MicroProfile Telemetry feature and set this system property When your Liberty runtime hosts multiple applications, you might choose to enable OpenTelemetry to collect logs, metrics, and traces at the application level for each application. Although this option does not collect runtime-level telemetry, it gives you fine-grained control of the data you collect for each application. -* Enable the feature:mpTelemetry[display=MicroProfile Telemetry] feature version 2.0 or later in the `featureManager` element of the `server.xml` file of each application that you want to collect telemetry for. -+ -[source,xml] ----- - - mpTelemetry-2.0 - ... - ----- +. Enable the feature:mpTelemetry[display=MicroProfile Telemetry] feature version 2.0 or later in the `featureManager` element of the `server.xml` file of each application that you want to collect telemetry for. -* Set `otel.sdk.disabled=false` as an application-level property in the `microprofile-config.properties` file of each application. +. Set `otel.sdk.disabled=false` as an application-level property in the `microprofile-config.properties` file of each application. + The following examples show an application scenario where two applications on the same Open Liberty runtime are configured to collect and export telemetry data at the application level. These examples also set the `otel.service.name` property in each application to assign a service name to the telemetry data that is collected. This service name helps you identify the source of the data from each application when you send your data to monitoring and analytics tools. + @@ -102,8 +86,11 @@ otel.service.name=A2 + This configuration creates all telemetry from Application 1 with the service name `A1`, and from Application 2 with the service name `A2`. -* You can also use a combination of runtime-level and application-level configuration, so that some settings apply to all applications on the runtime, while others are specific to each application. This strategy can save you from having to duplicate general configuration settings in multiple applications on the same runtime. Any runtime-level configuration takes precedence over application-level configuration. Therefore, you can enable OpenTelemetry and assign a service name individually for each application, but specify other settings at the runtime level to apply globally to all applications on the runtime. To combine runtime and application-level configuration, you must set the `otel.sdk.disabled=false` at the application level and not in a runtime-level configuration source. -+ + +You can also use a combination of runtime-level and application-level configuration, so that some settings apply to all applications on the runtime, while others are specific to each application. This strategy can save you from having to duplicate general configuration settings in multiple applications on the same runtime. + +Any runtime-level configuration takes precedence over application-level configuration. Therefore, you can enable OpenTelemetry and assign a service name individually for each application, but specify other settings at the runtime level to apply globally to all applications on the runtime. To combine runtime and application-level configuration, you must set the `otel.sdk.disabled=false` property at the application level and not in a runtime-level configuration source. + For example, you might want to collect a unique set of telemetry data for each application in the runtime, but have all applications use the same OpenTelemetry logs exporter. You can set the OpenTelemetry logs exporter at the runtime-level by adding the following property in the `bootstrap.properties` file: + ---- @@ -119,7 +106,7 @@ otel.service.name= + This configuration enables an application-level telemetry with a unique service name for each application, while all applications in the runtime use the `myExporter` logs exporter. -After you enable the MicroProfile Telemetry feature and set the `otel.sdk.disabled=false` property for each application on the runtime, your applications are ready to start collecting and exporting logs, metrics, and traces. +After you enable the MicroProfile Telemetry feature and set the system properties for each application on the runtime, your applications are ready to start collecting and exporting logs, metrics, and traces. [#config] == OpenTelemetry settings and configuration From 17a1cba4a2ffcdb27f59c4bab355504536b8ccda Mon Sep 17 00:00:00 2001 From: David Mueller Date: Thu, 21 Nov 2024 14:57:09 -0500 Subject: [PATCH 53/81] Update microprofile-telemetry.adoc --- modules/ROOT/pages/microprofile-telemetry.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/microprofile-telemetry.adoc b/modules/ROOT/pages/microprofile-telemetry.adoc index 97b81096a..6ff3a660d 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -92,18 +92,18 @@ You can also use a combination of runtime-level and application-level configurat Any runtime-level configuration takes precedence over application-level configuration. Therefore, you can enable OpenTelemetry and assign a service name individually for each application, but specify other settings at the runtime level to apply globally to all applications on the runtime. To combine runtime and application-level configuration, you must set the `otel.sdk.disabled=false` property at the application level and not in a runtime-level configuration source. For example, you might want to collect a unique set of telemetry data for each application in the runtime, but have all applications use the same OpenTelemetry logs exporter. You can set the OpenTelemetry logs exporter at the runtime-level by adding the following property in the `bootstrap.properties` file: -+ + ---- otel.logs.exporter=myExporter ---- -+ + Then, enable application-level telemetry and specify a service name in the `microprofile-config.properties` file for each application in the runtime: -+ + ---- otel.sdk.disabled=false otel.service.name= ---- -+ + This configuration enables an application-level telemetry with a unique service name for each application, while all applications in the runtime use the `myExporter` logs exporter. After you enable the MicroProfile Telemetry feature and set the system properties for each application on the runtime, your applications are ready to start collecting and exporting logs, metrics, and traces. From 24c44b326f2301d8d376a03949bc62cda7804228 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Thu, 21 Nov 2024 14:59:41 -0500 Subject: [PATCH 54/81] Update microprofile-telemetry.adoc --- modules/ROOT/pages/microprofile-telemetry.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/microprofile-telemetry.adoc b/modules/ROOT/pages/microprofile-telemetry.adoc index 6ff3a660d..27921a89d 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -10,7 +10,7 @@ :seo-description: :page-layout: general-reference :page-type: general -= OpenTelemetry += Collect logs, metrics, and traces with OpenTelemetry The OpenTelemetry project is a collection of open source, vendor-independent resources for collecting and managing application telemetry data. With Open Liberty and MicroProfile Telemetry 2.0 and later, you can manage logs, metrics, and traces in a standardized way by using the OpenTelemetry protocol. From d9f17350a34ad275bbc652e9eb98248ea56d8a08 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Fri, 22 Nov 2024 16:15:03 -0500 Subject: [PATCH 55/81] edits for dev prereqs #7655 --- .../pages/custom-mptelemetry-metrics.adoc | 2 +- modules/ROOT/pages/observability.adoc | 2 +- modules/ROOT/pages/prepare-mptelemetry.adoc | 2 +- modules/ROOT/pages/telemetry-trace.adoc | 2 +- .../feature/mpTelemetry-2.0/examples.adoc | 39 ++++++++++--------- 5 files changed, 25 insertions(+), 22 deletions(-) diff --git a/modules/ROOT/pages/custom-mptelemetry-metrics.adoc b/modules/ROOT/pages/custom-mptelemetry-metrics.adoc index 31dba9d17..0176592ad 100644 --- a/modules/ROOT/pages/custom-mptelemetry-metrics.adoc +++ b/modules/ROOT/pages/custom-mptelemetry-metrics.adoc @@ -18,7 +18,7 @@ For more information about collecting and emitting metrics with MicroProfile Tel For more information about OpenTelemetry metrics, see the link:https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/1.39.0/io/opentelemetry/api/metrics/package-summary.html[OpenTelemetry metrics API documentation]. -Before you can use MicroProfile Telemetry to define custom metrics metrics, you must enable MicroProfile Telemetry in your development environment by editing your runtime configuration. You must also add the OpenTelemetry API and annotations as a dependency on your build path. For more information, see link:/docs/latest/reference/feature/mpTelemetry-2.0.html#dev[Prepare your development environment for MicroProfile Telemetry]. +Before you can use OpenTelemetry to define custom metrics metrics, you must make 3rd party APIs visible in your runtime environment by editing your runtime configuration. You must also add the OpenTelemetry API and annotations as a dependency on your build path. For more information, see link:/docs/latest/reference/feature/mpTelemetry-2.0.html#dev[Customize your application telemetry with the OpenTelemetry API]. The following example defines a custom counter metric: diff --git a/modules/ROOT/pages/observability.adoc b/modules/ROOT/pages/observability.adoc index 4d0a8b852..f63eb1346 100644 --- a/modules/ROOT/pages/observability.adoc +++ b/modules/ROOT/pages/observability.adoc @@ -20,7 +20,7 @@ With MicroProfile Telemetry 2.0 and later, you can manage logs, metrics, and tra The following topics provide information to help you develop observable applications with Open Liberty. //// -xref:prepare-mptelemetry.adoc[Prepare your development environment for MicroProfile Telemetry]:: +xref:prepare-mptelemetry.adoc[Customize your application telemetry with the OpenTelemetry API]:: Before you manually instrument your code to use MicroProfile Telemetry to collect metrics and traces, you must enable MicroProfile Telemetry in your development environment by editing your runtime configuration. You must also add the OpenTelemetry API and annotations as a dependency on your build path. //// diff --git a/modules/ROOT/pages/prepare-mptelemetry.adoc b/modules/ROOT/pages/prepare-mptelemetry.adoc index 208d89dae..f01990f24 100644 --- a/modules/ROOT/pages/prepare-mptelemetry.adoc +++ b/modules/ROOT/pages/prepare-mptelemetry.adoc @@ -10,7 +10,7 @@ :seo-description: :page-layout: general-reference :page-type: general -= Prepare your development environment for MicroProfile Telemetry += Customize your application telemetry with the OpenTelemetry API Before you manually instrument your code to use MicroProfile Telemetry to collect metrics and traces, you must enable MicroProfile Telemetry in your development environment by editing your runtime configuration. You must also add the OpenTelemetry API and annotations as a dependency on your build path. diff --git a/modules/ROOT/pages/telemetry-trace.adoc b/modules/ROOT/pages/telemetry-trace.adoc index a87ca8ab8..456f67f8e 100644 --- a/modules/ROOT/pages/telemetry-trace.adoc +++ b/modules/ROOT/pages/telemetry-trace.adoc @@ -30,7 +30,7 @@ In Open Liberty version 23.0.0.11 and later, spans are automatically generated f 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.39.0/io/opentelemetry/api/trace/package-summary.html[OpenTelemetry API]. -However, before you manually instrument your code, you must enable MicroProfile Telemetry in your development environment by editing your runtime configuration. You must also add the OpenTelemetry API and annotations as a dependency on your build path. For more information, see link:/docs/latest/reference/feature/mpTelemetry-2.0.html#dev[Prepare your development environment for MicroProfile Telemetry]. +However, before you manually instrument your code, you must make 3rd party APIs visible in your runtime environment by editing your runtime configuration. You must also add the OpenTelemetry API and annotations as a dependency on your build path. For more information, see link:/docs/latest/reference/feature/mpTelemetry-2.0.html#dev[Customize your application telemetry with the OpenTelemetry API]. After you complete those prerequisites, you're ready to instrument your code. The following examples show configuration options with the OpenTelemetry API. diff --git a/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc b/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc index 9b645f654..8d0df4d78 100644 --- a/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc +++ b/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc @@ -12,10 +12,28 @@ otel.sdk.disabled=false When you enable the MicroProfile Telemetry feature and set this property, your system is ready to collect and export logs, metrics, and traces. +[#logs] +=== Collect logs from a specified source + +To enable the MicroProfile Telemetry feature to collect logs from different sources in the Open Liberty runtime environment, configure the `source` attribute for the `mpTelemetry` element with a comma-separated list of comma-separated log sources. + +[source,xml] +---- + +---- + +* The `mpTelemetry` configuration element is optional. If you do not specify it or the `source` attribute, the default configuration source is `message`. + +* If the source attribute is empty (`source=“”`), no sources are collected, and nothing is routed to the configured OpenTelemetry logs exporter. + +* The attributes and values are case insensitive. + [#dev] -=== Prepare your development environment for OpenTelemetry +=== Customize your application telemetry with the OpenTelemetry API + +Although OpenTelemetry automatically collects a default set of logs, metrics, and traces, if you need to xref:ROOT:telemetry-trace.adoc[manually instrument your code to collect traces] or xref:ROOT:custom-mptelemetry-metrics.adoc[define custom metrics], you must make the OpenTelemetry API and annotations available in your development environment. -If you need to xref:ROOT:telemetry-trace.adoc[manually instrument your code to collect traces] or xref:ROOT:custom-mptelemetry-metrics.adoc[define custom metrics], complete the following prerequisites to enable MicroProfile Telemetry in your development environment: +Complete the following prerequisites before you configure custom OpenTelemetry traces or metrics in your application code: * xref:ROOT:class-loader-library-config.adoc#3rd-party[Enable third-party APIs] for your application by adding the following code in your `server.xml` file: + @@ -44,19 +62,4 @@ If you need to xref:ROOT:telemetry-trace.adoc[manually instrument your code to c ---- - -[#logs] -=== Collect logs from a specified source - -To enable the MicroProfile Telemetry feature to collect logs from different sources in the Open Liberty runtime environment, configure the `source` attribute for the `mpTelemetry` element with a comma-separated list of comma-separated log sources. - -[source,xml] ----- - ----- - -* The `mpTelemetry` configuration element is optional. If you do not specify it or the `source` attribute, the default configuration source is `message`. - -* If the source attribute is empty (`source=“”`), no sources are collected, and nothing is routed to the configured OpenTelemetry logs exporter. - -* The attributes and values are case insensitive. +Once you complete these prerequisites, you can use the OpenTelemetry API and annotations in your development environment to configure custom application telemetry. From f670f4a7b0b60d2b13b4d4095a5b7207cf4529d6 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Mon, 25 Nov 2024 11:54:01 +0530 Subject: [PATCH 56/81] 7654-Documentation-MicroProfile-OpenAPI-4.0-7 7654-Documentation-MicroProfile-OpenAPI-4.0-7 #7654 --- modules/ROOT/pages/documentation-openapi.adoc | 70 +++++++++---------- 1 file changed, 34 insertions(+), 36 deletions(-) diff --git a/modules/ROOT/pages/documentation-openapi.adoc b/modules/ROOT/pages/documentation-openapi.adoc index d97b20c1d..5f9902379 100644 --- a/modules/ROOT/pages/documentation-openapi.adoc +++ b/modules/ROOT/pages/documentation-openapi.adoc @@ -15,7 +15,15 @@ MicroProfile OpenAPI helps you to generate structured documentation from your Jakarta RESTful Services or JAX-RS applications. This documentation helps other microservices and developers to understand and communicate with your application. Other developers need relevant information to build an application that communicates with the REST API of your application. -MicroProfile OpenAPI facilitates this communication by generating human and machine-readable documentation on a simple interface that doesn’t require access to the source code. +MicroProfile OpenAPI facilitates this communication by generating human and machine-readable documentation on a simple interface that does not require access to the source code. + +The following sections provide more information about the available approaches, supported versions, and configurations for using MicroProfile OpenAPI with Open Liberty. +- <<#code1, The code-first approach>> +- <<#design1, The design-first approach>> +- <<#supp-ver, Supported OpenAPI versions>> +- <<#multi-module, Multiple application and multi-module application support with MicroProfile OpenAPI>> +- <<#conf-mm-supprt, Configuring multiple application and multi-module support>> + You can implement MicroProfile OpenAPI for Open Liberty by enabling the feature:mpOpenAPI[display=MicroProfile OpenAPI] feature. When this feature is enabled, you can view the OpenAPI document in a browser by using the `/openapi` endpoint. For example, if your browser is on the same machine where your server is running, you can view the raw OpenAPI document at the `\http://localhost:9080/openapi` URL or view the OpenAPI document in a user interface at the `\http://localhost:9080/openapi/ui` URL. @@ -29,6 +37,8 @@ The JAX-RS framework handles basic API generation for JAX-RS annotations and gen You can use this treemap as a starting point and augment it with annotations and code to produce a complete OpenAPI document. Additionally, you can use this manually created documentation to generate stubs, or testable versions of code modules, such as client libraries for the API. + +[#code1] == The code-first approach In the code-first approach, you can initially generate basic API documentation of the REST API from annotations that are specified in the source code. @@ -112,12 +122,14 @@ The information that is provided through the OpenAPI annotations augments the ba For more information, see the link:reference/javadoc/microprofile-6.1-javadoc.html?package=org/eclipse/microprofile/openapi/package-frame.html&class=org/eclipse/microprofile/openapi/package-summary.html[MicroProfile OpenAPI Javadoc] for the available annotations. + +[#design1] == The design-first approach -An alternative approach is to design the REST API in an editor, such as the link:https://editor.swagger.io/[Swagger] editor, before you write any code. +An alternative approach is to design the REST API in an editor, such as the link:https://editor.swagger.io/[Swagger] editor before you write any code. With this approach, you can spot and rectify any issues in the design before it is implemented. -In large companies, subject matter experts review the API to ensure it's consistent and usable. -This API design then forms a contract and must be implemented as agreed. +In large companies, subject matter experts review the API to ensure that it is consistent and usable. +The API design then serves as a contract and must be implemented. You can write this API design in YAML or JSON format and place it in the `META-INF` directory of your application. Optionally, you can create stubs for the API code. @@ -126,7 +138,7 @@ You can augment manually created API documents by adding annotations to the code For more information, see https://openliberty.io/guides/microprofile-openapi.html#using-pregenerated-openapi-documents[Using pregenerated OpenAPI documents]. - +[#supp-ver] == Supported OpenAPI versions The MicroProfile OpenAPI feature generates structured documentation based on the OpenAPI specification. Each new version of the OpenAPI specification updates the documentation format, and different versions of MicroProfile OpenAPI support different OpenAPI specification versions. @@ -139,19 +151,7 @@ The MicroProfile OpenAPI feature generates structured documentation based on the |`mpOpenAPI-4.0` | 3.1, 3.0 -|`mpOpenAPI-3.1` -| 3.0 - -|`mpOpenAPI-3.0` -| 3.0 - -|`mpOpenAPI-2.0` -| 3.0 - -|`mpOpenAPI-1.1` -| 3.0 - -|`mpOpenAPI-1.0` +|`mpOpenAPI-3.1` and earlier | 3.0 |=== @@ -167,8 +167,7 @@ For example, you can select OpenAPI v3.0 when using `mpOpenAPI-4.0`. [#multi-module] == Multiple application and multi-module application support with MicroProfile OpenAPI -When multiple applications, or applications with more than one web module are deployed to the same Open Liberty server, the behavior differs between MicroProfile OpenAPI feature versions. - +When multiple applications or applications with more than one web module are deployed to the same Open Liberty server, the structured documentation differs depending on which MicroProfile OpenAPI feature version you use. .Multiple application and multi-module application support with MicroProfile OpenAPI [cols="1,2", options="header"] @@ -176,23 +175,23 @@ When multiple applications, or applications with more than one web module are de |Feature |Behavior |`mpOpenAPI-4.0` -|By default, all deployed applications and modules are included in the structured documentation. This can changed through configuration. +|By default, all deployed applications and modules are included in the structured documentation, and the behavior can be modified through configuration. |`mpOpenAPI-2.0` to `mpOpenAPI-3.1` -|By default, only the first web module of the first application deployed is included in the structured documentation. This can be changed through configuration. +|By default, only the first web module of the first deployed application is included in the structured documentation, but the behavior can be modified through configuration. |`mpOpenAPI-1.0` to `mpOpenAPI-1.1` -|Only the first web module of the first application deployed is included in the structured documentation. This cannot be changed. +|Only the first web module of the first deployed application is included in the structured documentation, and this behavior cannot be modified. |=== - +[#conf-mm-supprt] == Configuring multiple application and multi-module support Open Liberty offers two main ways to configure support for multiple applications and multi-module projects. -- <<#serverxml, Configure using the `server.xml` file:>> This method involves configuring your server to deploy multiple applications by specifying the applications and modules within the `server.xml` file. +- <<#serverxml, Configure using the `server.xml` file:>> You can customize the structured API documentation that is generated for your applications by configuring the `server.xml` file. By using the `includeApplication`, `excludeApplication`, `includeModule`, and `excludeModule` elements within the `mpOpenAPI` configuration, you gain precise control over which applications and modules are included in the OpenAPI documentation. This flexibility is useful for tailoring the documentation to your specific needs, such as excluding sensitive modules or overriding default metadata. The following sections provide examples and explain how to configure these elements effectively. -- <<#mpconfigs, Configure using the MicroProfile Config:>> Alternatively, you can use the MicroProfile Config to adjust deployment settings more flexibly, allowing for easy updates and changes without needing to modify XML files. +- <<#mpconfigs, Configure using MicroProfile Config properties:>> MicroProfile Config provides a way to manage which applications and modules are included in the generated OpenAPI documentation by specifying configuration properties. With these properties, you can set inclusion and exclusion rules and customize the info section of the final OpenAPI document. This method is ideal for dynamic setups, enabling changes without directly modifying the `server.xml` file. However, there are some limitations. Configurations that are defined in the `server.xml` file take priority over those set through MicroProfile Config. Additionally, the properties must be set by using sources that apply to the entire server, such as `jvm.properties`, `server.env`, or environment variables. [#serverxml] @@ -243,17 +242,16 @@ You can also override the `info` section of the OpenAPI document using the follo ---- -This override may be useful when documenting multiple modules or applications. Without it, the `info` section would be replaced with a standard one indicating that documentation from several modules was merged. - +Overriding the `info` section is useful for documenting multiple modules or applications. Without an override, the `info` section can be replaced with a standard version which indicates that documentation from several modules was merged. [#mpconfigs] -=== Configure using the MicroProfile Config +=== Configure using MicroProfile Config properties You can configure the modules and applications to be included in the structured documentation by using MicroProfile Config, with the following limitations: - If conflicting configuration is found in the `server.xml` file, the MicroProfile Config settings are ignored. -- The configuration properties must be set by using a configuration source that is not specific to an application. For example, you can use system properties, environment variables, or `variable` elements in the `server.xml` file. +- The configuration properties must be set by using a configuration source that is not specific to an application. For example, you can use system properties that can be set in the `jvm.properties` file or`bootstrap.properties` file. The environment variables can be set in the `server.env` file`, or `variable` elements in the `server.xml` file. The following table lists the MicroProfile Config properties that can be specified to configure which modules or applications are included in the generated OpenAPI documentation. @@ -267,23 +265,23 @@ The following table lists the MicroProfile Config properties that can be specifi |Valid values |`mp.openapi.extensions.liberty.merged.include` -|This property specifies which modules or applications are included in the generated OpenAPI documentation. +|The property specifies which modules or applications are included in the generated OpenAPI documentation. | * `all` + -This value includes all modules and applications in a deployment. +The value includes all the modules and applications in a deployment. * `first` + -This value includes only the first web module of the first application deployed. +The value includes only the first web module of the first deployed application. * A comma-separated list of `_application_name_` or `_application_name_/_module_name_` includes the named applications and modules. |`mp.openapi.extensions.liberty.merged.exclude` -|This property overrides the `mp.openapi.extensions.liberty.merged.include` property to specify which applications or web modules are excluded from the generated OpenAPI documentation. +|The property overrides the `mp.openapi.extensions.liberty.merged.include` property to specify which applications or web modules are excluded from the generated OpenAPI documentation. | * `none` + -This value excludes no applications or web modules. +The value excludes no applications or web modules. * A comma-separated list of `_application_name_` or `_application_name_/_module_name_` excludes the named applications and modules. |`mp.openapi.extensions.liberty.merged.info` -|This property sets the `info` section of the final Open API document. If it is set, the `info` section in the final OpenAPI document is replaced with the value of the property. This replacement is made after any merging is completed. +|The property is used to define the `info` section of the final Open API document. If it is set, the `info` section in the final OpenAPI document is replaced with the value of the property. The replacement occurs only after any merging is completed. |The value must be https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#infoObject[a valid OpenAPI info section] in JSON format. |=== From e49db24d7bb4afa3ca5365663f3d276412546a06 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Mon, 25 Nov 2024 17:45:37 +0530 Subject: [PATCH 57/81] 7654-Documentation-MicroProfile-OpenAPI-4.0-8 7654-Documentation-MicroProfile-OpenAPI-4.0-8 #7654 --- modules/ROOT/pages/documentation-openapi.adoc | 98 ++----------------- .../pages/feature/mpOpenAPI-2.0/examples.adoc | 28 ++++++ .../pages/feature/mpOpenAPI-3.0/examples.adoc | 28 ++++++ .../pages/feature/mpOpenAPI-3.1/examples.adoc | 38 ++++--- .../pages/feature/mpOpenAPI-4.0/examples.adoc | 29 ++++++ 5 files changed, 110 insertions(+), 111 deletions(-) diff --git a/modules/ROOT/pages/documentation-openapi.adoc b/modules/ROOT/pages/documentation-openapi.adoc index 5f9902379..08486c99b 100644 --- a/modules/ROOT/pages/documentation-openapi.adoc +++ b/modules/ROOT/pages/documentation-openapi.adoc @@ -189,104 +189,20 @@ When multiple applications or applications with more than one web module are dep Open Liberty offers two main ways to configure support for multiple applications and multi-module projects. -- <<#serverxml, Configure using the `server.xml` file:>> You can customize the structured API documentation that is generated for your applications by configuring the `server.xml` file. By using the `includeApplication`, `excludeApplication`, `includeModule`, and `excludeModule` elements within the `mpOpenAPI` configuration, you gain precise control over which applications and modules are included in the OpenAPI documentation. This flexibility is useful for tailoring the documentation to your specific needs, such as excluding sensitive modules or overriding default metadata. The following sections provide examples and explain how to configure these elements effectively. +- Configure using the `server.xml` file -- <<#mpconfigs, Configure using MicroProfile Config properties:>> MicroProfile Config provides a way to manage which applications and modules are included in the generated OpenAPI documentation by specifying configuration properties. With these properties, you can set inclusion and exclusion rules and customize the info section of the final OpenAPI document. This method is ideal for dynamic setups, enabling changes without directly modifying the `server.xml` file. However, there are some limitations. Configurations that are defined in the `server.xml` file take priority over those set through MicroProfile Config. Additionally, the properties must be set by using sources that apply to the entire server, such as `jvm.properties`, `server.env`, or environment variables. +You can customize the structured API documentation that is generated for your applications by configuring the `server.xml` file. By using the `includeApplication`, `excludeApplication`, `includeModule`, and `excludeModule` elements within the `mpOpenAPI` configuration, you gain precise control over which applications and modules are included in the OpenAPI documentation. This flexibility is useful for tailoring the documentation to your specific needs, such as excluding sensitive modules or overriding default metadata. The following sections provide examples and explain how to configure these elements effectively. +for more information, see the feature:mpOpenAPI[display=MicroProfile OpenAPI 4.0] feature. -[#serverxml] -=== Configure using the server.xml file +- Configure using MicroProfile Config properties -For MicroProfile OpenAPI 2.0 and later, you can control the applications and modules that are included in the structured documentation by using the `includeApplication`, `excludeApplication`, `includeModule`, and `excludeModule` elements within the `mpOpenAPI` xref:reference:config/mpOpenAPI.adoc[configuration element]. +MicroProfile Config provides a way to manage which applications and modules are included in the generated OpenAPI documentation by specifying configuration properties. With these properties, you can set inclusion and exclusion rules and customize the info section of the final OpenAPI document. This method is ideal for dynamic setups, enabling changes without directly modifying the `server.xml` file. However, there are some limitations. Configurations that are defined in the `server.xml` file take priority over those set through MicroProfile Config. Additionally, the properties must be set by using sources that apply to the entire server, such as `jvm.properties`, `server.env`, or environment variables. -For example, to include all deployed applications and modules in the generated structured documentation when using `mpOpenAPI-2.0`, add the following configuration to your `server.xml` file. +for more information, see xref:reference:config/mpOpenAPI.adoc[MicroProfile Config properties for MicroProfile OpenAPI]. -[source,xml] ----- - - all - ----- - -For example, to include all deployed applications and modules except the `admin` module of `application1`, add the following configuration to your `server.xml` file. - -[source,xml] ----- - - all - application1/admin - ----- - -==== Naming applications and modules - -- The application name is determined by the value of the `name` attribute when the application is deployed in `server.xml` using `application`, `webApplication`, or `enterpriseApplication`. For example: -+ -[source,xml] ----- - ----- -+ -If the application is deployed in the `dropins` directory or if the `name` attribute is not specified, the name defaults to the archive filename with the extension removed. -+ -- The module name is specified in the web module's `web.xml` file. If there is no `web.xml` file or if it does not specify a name, the module name defaults to the filename with the extension removed. - -You can also override the `info` section of the OpenAPI document using the following configuration: - -[source,xml] ----- - - - ----- - -Overriding the `info` section is useful for documenting multiple modules or applications. Without an override, the `info` section can be replaced with a standard version which indicates that documentation from several modules was merged. - -[#mpconfigs] -=== Configure using MicroProfile Config properties - -You can configure the modules and applications to be included in the structured documentation by using MicroProfile Config, with the following limitations: - -- If conflicting configuration is found in the `server.xml` file, the MicroProfile Config settings are ignored. - -- The configuration properties must be set by using a configuration source that is not specific to an application. For example, you can use system properties that can be set in the `jvm.properties` file or`bootstrap.properties` file. The environment variables can be set in the `server.env` file`, or `variable` elements in the `server.xml` file. - -The following table lists the MicroProfile Config properties that can be specified to configure which modules or applications are included in the generated OpenAPI documentation. - - -.Configuration properties for multiple application and multi-module application support -[%header,cols="3,6,6a"] -|=== - -|Property name -|Description -|Valid values - -|`mp.openapi.extensions.liberty.merged.include` -|The property specifies which modules or applications are included in the generated OpenAPI documentation. -| -* `all` + -The value includes all the modules and applications in a deployment. -* `first` + -The value includes only the first web module of the first deployed application. -* A comma-separated list of `_application_name_` or `_application_name_/_module_name_` includes the named applications and modules. - -|`mp.openapi.extensions.liberty.merged.exclude` -|The property overrides the `mp.openapi.extensions.liberty.merged.include` property to specify which applications or web modules are excluded from the generated OpenAPI documentation. -| -* `none` + -The value excludes no applications or web modules. -* A comma-separated list of `_application_name_` or `_application_name_/_module_name_` excludes the named applications and modules. - -|`mp.openapi.extensions.liberty.merged.info` -|The property is used to define the `info` section of the final Open API document. If it is set, the `info` section in the final OpenAPI document is replaced with the value of the property. The replacement occurs only after any merging is completed. -|The value must be https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#infoObject[a valid OpenAPI info section] in JSON format. - -|=== -==== Multi-module naming rules +=== Multi-module naming rules - When you configure support for multiple applications and multi-module environments by using MicroProfile Config, the application name is taken from the application's deployment descriptor (`application.xml` or `web.xml`). If there is no deployment descriptor or if it does not specify a name, the name defaults to the application archive filename with the extension removed. + diff --git a/modules/reference/pages/feature/mpOpenAPI-2.0/examples.adoc b/modules/reference/pages/feature/mpOpenAPI-2.0/examples.adoc index 4bf454f5d..03e1803a7 100644 --- a/modules/reference/pages/feature/mpOpenAPI-2.0/examples.adoc +++ b/modules/reference/pages/feature/mpOpenAPI-2.0/examples.adoc @@ -32,6 +32,34 @@ For example, the following configuration is for the `sample_app` application, wh - The `` element sets the info section for the final OpenAPI document, which documents web modules 1, 2, and 4. +==== Naming applications and modules + +- The application name is determined by the value of the `name` attribute when the application is deployed in `server.xml` using `application`, `webApplication`, or `enterpriseApplication`. For example: ++ +[source,xml] +---- + +---- ++ +If the application is deployed in the `dropins` directory or if the `name` attribute is not specified, the name defaults to the archive filename with the extension removed. ++ +- The module name is specified in the web module's `web.xml` file. If there is no `web.xml` file or if it does not specify a name, the module name defaults to the filename with the extension removed. + +==== Override Info + +You can also override the `info` section of the OpenAPI document using the following configuration: + +[source,xml] +---- + + + +---- + +Overriding the `info` section is useful for documenting multiple modules or applications. Without an override, the `info` section can be replaced with a standard version which indicates that documentation from several modules was merged. + For more information, see xref:ROOT:documentation-openapi.adoc#multi-module[Multiple application and multi-module application support with MicroProfile OpenAPI] diff --git a/modules/reference/pages/feature/mpOpenAPI-3.0/examples.adoc b/modules/reference/pages/feature/mpOpenAPI-3.0/examples.adoc index 5d185557c..84c50f317 100644 --- a/modules/reference/pages/feature/mpOpenAPI-3.0/examples.adoc +++ b/modules/reference/pages/feature/mpOpenAPI-3.0/examples.adoc @@ -32,4 +32,32 @@ For example, the following configuration is for the `sample_app` application, wh - The `` element sets the info section for the final OpenAPI document, which documents web modules 1, 2, and 4. +==== Naming applications and modules + +- The application name is determined by the value of the `name` attribute when the application is deployed in `server.xml` using `application`, `webApplication`, or `enterpriseApplication`. For example: ++ +[source,xml] +---- + +---- ++ +If the application is deployed in the `dropins` directory or if the `name` attribute is not specified, the name defaults to the archive filename with the extension removed. ++ +- The module name is specified in the web module's `web.xml` file. If there is no `web.xml` file or if it does not specify a name, the module name defaults to the filename with the extension removed. + +==== Override Info + +You can also override the `info` section of the OpenAPI document using the following configuration: + +[source,xml] +---- + + + +---- + +Overriding the `info` section is useful for documenting multiple modules or applications. Without an override, the `info` section can be replaced with a standard version which indicates that documentation from several modules was merged. + For more information, see xref:ROOT:documentation-openapi.adoc#multi-module[Multiple application and multi-module application support with MicroProfile OpenAPI] diff --git a/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc b/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc index c527d1fd3..03e1803a7 100644 --- a/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc +++ b/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc @@ -32,36 +32,34 @@ For example, the following configuration is for the `sample_app` application, wh - The `` element 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] - +==== Naming applications and modules -=== mpOpenAPI-4.0 - Will be placed in another doc (Placed here for REVIEW) +- The application name is determined by the value of the `name` attribute when the application is deployed in `server.xml` using `application`, `webApplication`, or `enterpriseApplication`. For example: ++ +[source,xml] +---- + +---- ++ +If the application is deployed in the `dropins` directory or if the `name` attribute is not specified, the name defaults to the archive filename with the extension removed. ++ +- The module name is specified in the web module's `web.xml` file. If there is no `web.xml` file or if it does not specify a name, the module name defaults to the filename with the extension removed. -By default, all deployed applications and modules are included in the OpenAPI documentation. However, you can configure which applications and modules should be included. +==== Override Info -For example, the following configuration is for the `sample_app` application, which consists of an `EAR` file containing five web modules. +You can also override the `info` section of the OpenAPI document using the following configuration: [source,xml] ---- - sample_app/module-3 - sample_app/module-5 - + ---- -- The `` elements exclude the `module-3` and `module-5` web modules. - -- The `` element sets the info section for the final OpenAPI document, which documents web modules 1, 2, and 4. +Overriding the `info` section is useful for documenting multiple modules or applications. Without an override, the `info` section can be replaced with a standard version which indicates that documentation from several modules was merged. For more information, see xref:ROOT:documentation-openapi.adoc#multi-module[Multiple application and multi-module application support with MicroProfile OpenAPI] + diff --git a/modules/reference/pages/feature/mpOpenAPI-4.0/examples.adoc b/modules/reference/pages/feature/mpOpenAPI-4.0/examples.adoc index cc3d7831c..826ad124b 100644 --- a/modules/reference/pages/feature/mpOpenAPI-4.0/examples.adoc +++ b/modules/reference/pages/feature/mpOpenAPI-4.0/examples.adoc @@ -30,4 +30,33 @@ For example, the following configuration is for the `sample_app` application, wh - The `` element sets the info section for the final OpenAPI document, which documents web modules 1, 2, and 4. + +==== Naming applications and modules + +- The application name is determined by the value of the `name` attribute when the application is deployed in `server.xml` using `application`, `webApplication`, or `enterpriseApplication`. For example: ++ +[source,xml] +---- + +---- ++ +If the application is deployed in the `dropins` directory or if the `name` attribute is not specified, the name defaults to the archive filename with the extension removed. ++ +- The module name is specified in the web module's `web.xml` file. If there is no `web.xml` file or if it does not specify a name, the module name defaults to the filename with the extension removed. + +==== Override Info + +You can also override the `info` section of the OpenAPI document using the following configuration: + +[source,xml] +---- + + + +---- + +Overriding the `info` section is useful for documenting multiple modules or applications. Without an override, the `info` section can be replaced with a standard version which indicates that documentation from several modules was merged. + For more information, see xref:ROOT:documentation-openapi.adoc#multi-module[Multiple application and multi-module application support with MicroProfile OpenAPI] \ No newline at end of file From 7ce45ddd3c8e259c33d7e9846b8399e676d2a7d3 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Mon, 25 Nov 2024 23:54:15 +0530 Subject: [PATCH 58/81] 7654-Documentation-MicroProfile-OpenAPI-4.0-9 7654-Documentation-MicroProfile-OpenAPI-4.0-9 #7654 --- modules/ROOT/pages/documentation-openapi.adoc | 54 ++++++++++--------- .../pages/feature/mpOpenAPI-2.0/examples.adoc | 4 +- .../pages/feature/mpOpenAPI-3.0/examples.adoc | 4 +- .../pages/feature/mpOpenAPI-3.1/examples.adoc | 4 +- .../pages/feature/mpOpenAPI-4.0/examples.adoc | 16 ++++-- 5 files changed, 49 insertions(+), 33 deletions(-) diff --git a/modules/ROOT/pages/documentation-openapi.adoc b/modules/ROOT/pages/documentation-openapi.adoc index 08486c99b..f66a2f001 100644 --- a/modules/ROOT/pages/documentation-openapi.adoc +++ b/modules/ROOT/pages/documentation-openapi.adoc @@ -18,11 +18,11 @@ Other developers need relevant information to build an application that communic MicroProfile OpenAPI facilitates this communication by generating human and machine-readable documentation on a simple interface that does not require access to the source code. The following sections provide more information about the available approaches, supported versions, and configurations for using MicroProfile OpenAPI with Open Liberty. -- <<#code1, The code-first approach>> -- <<#design1, The design-first approach>> -- <<#supp-ver, Supported OpenAPI versions>> -- <<#multi-module, Multiple application and multi-module application support with MicroProfile OpenAPI>> -- <<#conf-mm-supprt, Configuring multiple application and multi-module support>> + +* <<#code1, The code-first approach>> +* <<#design1, The design-first approach>> +* <<#supp-ver, Supported OpenAPI versions>> +* <<#multi-module, Multiple application and multi-module application support>> You can implement MicroProfile OpenAPI for Open Liberty by enabling the feature:mpOpenAPI[display=MicroProfile OpenAPI] feature. When this feature is enabled, you can view the OpenAPI document in a browser by using the `/openapi` endpoint. For example, if your browser is on the same machine where your server is running, you can view the raw OpenAPI document at the `\http://localhost:9080/openapi` URL or view the OpenAPI document in a user interface at the `\http://localhost:9080/openapi/ui` URL. @@ -157,12 +157,8 @@ The MicroProfile OpenAPI feature generates structured documentation based on the If you are using a feature that supports more than one version of the OpenAPI specification, you can switch between versions with configuration. You might need to do this if you or your end users use tools or libraries that don't yet support a newer version of the OpenAPI specification. -For example, you can select OpenAPI v3.0 when using `mpOpenAPI-4.0`. +For more information, see link:/docs/latest/reference/feature/mpOpenAPI-4.0.html#apiversion[Selecting the OpenAPI specification version]. -[source,xml] ----- - ----- [#multi-module] == Multiple application and multi-module application support with MicroProfile OpenAPI @@ -172,42 +168,52 @@ When multiple applications or applications with more than one web module are dep .Multiple application and multi-module application support with MicroProfile OpenAPI [cols="1,2", options="header"] |=== -|Feature |Behavior +|Feature |Default behavior |`mpOpenAPI-4.0` -|By default, all deployed applications and modules are included in the structured documentation, and the behavior can be modified through configuration. +|All deployed applications and modules are included in the structured documentation, and the behavior can be modified through configuration. |`mpOpenAPI-2.0` to `mpOpenAPI-3.1` -|By default, only the first web module of the first deployed application is included in the structured documentation, but the behavior can be modified through configuration. +|Only the first web module of the first deployed application is included in the structured documentation, but the behavior can be modified through configuration. |`mpOpenAPI-1.0` to `mpOpenAPI-1.1` |Only the first web module of the first deployed application is included in the structured documentation, and this behavior cannot be modified. |=== [#conf-mm-supprt] -== Configuring multiple application and multi-module support +== Configuring multiple application and multi-module API documentation Open Liberty offers two main ways to configure support for multiple applications and multi-module projects. -- Configure using the `server.xml` file +=== Configure by using the `server.xml` file + +Customize the structured API documentation that is generated for your applications by configuring the link:/docs/latest/reference/feature/mpOpenAPI-4.0.html#_configure_openapi_documentation_for_a_multi_module_application[server.xml] file. Use the following elements within the `mpOpenAPI` configuration to control the inclusion and exclusion of applications and modules in the OpenAPI documentation: + +- `includeApplication`: Specifies applications to include in the documentation. +- `excludeApplication`: Specifies applications to exclude from the documentation. +- `includeModule`: Specifies modules to include in the documentation. +- `excludeModule`: Specifies modules to exclude from the documentation. -You can customize the structured API documentation that is generated for your applications by configuring the `server.xml` file. By using the `includeApplication`, `excludeApplication`, `includeModule`, and `excludeModule` elements within the `mpOpenAPI` configuration, you gain precise control over which applications and modules are included in the OpenAPI documentation. This flexibility is useful for tailoring the documentation to your specific needs, such as excluding sensitive modules or overriding default metadata. The following sections provide examples and explain how to configure these elements effectively. +This configuration provides flexibility to tailor the documentation to your specific needs, such as excluding sensitive modules or overriding default metadata. -for more information, see the feature:mpOpenAPI[display=MicroProfile OpenAPI 4.0] feature. +For more information, see the feature:mpOpenAPI[MicroProfile OpenAPI 4.0] feature. -- Configure using MicroProfile Config properties -MicroProfile Config provides a way to manage which applications and modules are included in the generated OpenAPI documentation by specifying configuration properties. With these properties, you can set inclusion and exclusion rules and customize the info section of the final OpenAPI document. This method is ideal for dynamic setups, enabling changes without directly modifying the `server.xml` file. However, there are some limitations. Configurations that are defined in the `server.xml` file take priority over those set through MicroProfile Config. Additionally, the properties must be set by using sources that apply to the entire server, such as `jvm.properties`, `server.env`, or environment variables. +=== Configure by using MicroProfile Config properties -for more information, see xref:reference:config/mpOpenAPI.adoc[MicroProfile Config properties for MicroProfile OpenAPI]. +MicroProfile Config provides a way to manage which applications and modules are included in the generated OpenAPI documentation by specifying configuration properties. Use these properties to define inclusion and exclusion rules and to customize the `info` section of the final OpenAPI document. +- This method is suitable for dynamic setups because it allows changes to be made without directly modifying the `server.xml` file. +- When both methods are used, configurations that are defined in the `server.xml` file take precedence over the ones set through MicroProfile Config. +- Properties must be configured by using sources that apply to the entire server, such as the `jvm.properties`, `server.env`, or the environment variables. +- MicroProfile Config options are compatible only with versions 3.0 and earlier. -=== Multi-module naming rules +When you configure support for multiple applications and multi-module environments by using MicroProfile Config, the application and module names are determined based on specific rules. -- When you configure support for multiple applications and multi-module environments by using MicroProfile Config, the application name is taken from the application's deployment descriptor (`application.xml` or `web.xml`). If there is no deployment descriptor or if it does not specify a name, the name defaults to the application archive filename with the extension removed. -+ -- The module name follows the same rules as described for the `server.xml` configuration. +- **Application name**: The application name is determined from the application's deployment descriptor (`application.xml` or `web.xml`). If the deployment descriptor is missing or does not specify a name, the application name defaults to the application archive filename with the file extension removed. +- **Module name**: The module name is determined by using the same rules as described for the `server.xml` configuration. +For more information, see the xref:reference:config/mpOpenAPI.adoc[MicroProfile Config properties for MicroProfile OpenAPI]. == See also diff --git a/modules/reference/pages/feature/mpOpenAPI-2.0/examples.adoc b/modules/reference/pages/feature/mpOpenAPI-2.0/examples.adoc index 03e1803a7..a70545021 100644 --- a/modules/reference/pages/feature/mpOpenAPI-2.0/examples.adoc +++ b/modules/reference/pages/feature/mpOpenAPI-2.0/examples.adoc @@ -32,7 +32,7 @@ For example, the following configuration is for the `sample_app` application, wh - The `` element sets the info section for the final OpenAPI document, which documents web modules 1, 2, and 4. -==== Naming applications and modules +=== Naming applications and modules - The application name is determined by the value of the `name` attribute when the application is deployed in `server.xml` using `application`, `webApplication`, or `enterpriseApplication`. For example: + @@ -45,7 +45,7 @@ If the application is deployed in the `dropins` directory or if the `name` attri + - The module name is specified in the web module's `web.xml` file. If there is no `web.xml` file or if it does not specify a name, the module name defaults to the filename with the extension removed. -==== Override Info +=== Override the info section in the OpenAPI document You can also override the `info` section of the OpenAPI document using the following configuration: diff --git a/modules/reference/pages/feature/mpOpenAPI-3.0/examples.adoc b/modules/reference/pages/feature/mpOpenAPI-3.0/examples.adoc index 84c50f317..967a64d24 100644 --- a/modules/reference/pages/feature/mpOpenAPI-3.0/examples.adoc +++ b/modules/reference/pages/feature/mpOpenAPI-3.0/examples.adoc @@ -32,7 +32,7 @@ For example, the following configuration is for the `sample_app` application, wh - The `` element sets the info section for the final OpenAPI document, which documents web modules 1, 2, and 4. -==== Naming applications and modules +=== Naming applications and modules - The application name is determined by the value of the `name` attribute when the application is deployed in `server.xml` using `application`, `webApplication`, or `enterpriseApplication`. For example: + @@ -45,7 +45,7 @@ If the application is deployed in the `dropins` directory or if the `name` attri + - The module name is specified in the web module's `web.xml` file. If there is no `web.xml` file or if it does not specify a name, the module name defaults to the filename with the extension removed. -==== Override Info +=== Override the info section in the OpenAPI document You can also override the `info` section of the OpenAPI document using the following configuration: diff --git a/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc b/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc index 03e1803a7..a70545021 100644 --- a/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc +++ b/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc @@ -32,7 +32,7 @@ For example, the following configuration is for the `sample_app` application, wh - The `` element sets the info section for the final OpenAPI document, which documents web modules 1, 2, and 4. -==== Naming applications and modules +=== Naming applications and modules - The application name is determined by the value of the `name` attribute when the application is deployed in `server.xml` using `application`, `webApplication`, or `enterpriseApplication`. For example: + @@ -45,7 +45,7 @@ If the application is deployed in the `dropins` directory or if the `name` attri + - The module name is specified in the web module's `web.xml` file. If there is no `web.xml` file or if it does not specify a name, the module name defaults to the filename with the extension removed. -==== Override Info +=== Override the info section in the OpenAPI document You can also override the `info` section of the OpenAPI document using the following configuration: diff --git a/modules/reference/pages/feature/mpOpenAPI-4.0/examples.adoc b/modules/reference/pages/feature/mpOpenAPI-4.0/examples.adoc index 826ad124b..92bf1e365 100644 --- a/modules/reference/pages/feature/mpOpenAPI-4.0/examples.adoc +++ b/modules/reference/pages/feature/mpOpenAPI-4.0/examples.adoc @@ -30,8 +30,7 @@ For example, the following configuration is for the `sample_app` application, wh - The `` element sets the info section for the final OpenAPI document, which documents web modules 1, 2, and 4. - -==== Naming applications and modules +=== Naming applications and modules - The application name is determined by the value of the `name` attribute when the application is deployed in `server.xml` using `application`, `webApplication`, or `enterpriseApplication`. For example: + @@ -44,7 +43,7 @@ If the application is deployed in the `dropins` directory or if the `name` attri + - The module name is specified in the web module's `web.xml` file. If there is no `web.xml` file or if it does not specify a name, the module name defaults to the filename with the extension removed. -==== Override Info +=== Override the info section in the OpenAPI document You can also override the `info` section of the OpenAPI document using the following configuration: @@ -59,4 +58,15 @@ You can also override the `info` section of the OpenAPI document using the follo Overriding the `info` section is useful for documenting multiple modules or applications. Without an override, the `info` section can be replaced with a standard version which indicates that documentation from several modules was merged. +[#apiversion] +=== Selecting the OpenAPI specification version +If you are using a feature that supports more than one version of the OpenAPI specification, you can switch between versions with configuration. You might need to do this if you or your end users use tools or libraries that don't yet support a newer version of the OpenAPI specification. + +For example, you can select OpenAPI v3.0 when using `mpOpenAPI-4.0`. + +[source,xml] +---- + +---- + For more information, see xref:ROOT:documentation-openapi.adoc#multi-module[Multiple application and multi-module application support with MicroProfile OpenAPI] \ No newline at end of file From e002a35f5c073b9a446644e02b94e28469b6e44a Mon Sep 17 00:00:00 2001 From: David Mueller Date: Mon, 25 Nov 2024 15:57:26 -0500 Subject: [PATCH 59/81] Davids edits #7654 --- modules/ROOT/pages/documentation-openapi.adoc | 38 +++++++++++++------ .../pages/feature/mpOpenAPI-3.0/examples.adoc | 20 +++++----- .../pages/feature/mpOpenAPI-3.1/examples.adoc | 22 +++++------ .../pages/feature/mpOpenAPI-4.0/examples.adoc | 29 +++++++------- 4 files changed, 62 insertions(+), 47 deletions(-) diff --git a/modules/ROOT/pages/documentation-openapi.adoc b/modules/ROOT/pages/documentation-openapi.adoc index f66a2f001..5b6c19511 100644 --- a/modules/ROOT/pages/documentation-openapi.adoc +++ b/modules/ROOT/pages/documentation-openapi.adoc @@ -156,14 +156,13 @@ The MicroProfile OpenAPI feature generates structured documentation based on the |=== If you are using a feature that supports more than one version of the OpenAPI specification, you can switch between versions with configuration. You might need to do this if you or your end users use tools or libraries that don't yet support a newer version of the OpenAPI specification. - For more information, see link:/docs/latest/reference/feature/mpOpenAPI-4.0.html#apiversion[Selecting the OpenAPI specification version]. [#multi-module] == Multiple application and multi-module application support with MicroProfile OpenAPI -When multiple applications or applications with more than one web module are deployed to the same Open Liberty server, the structured documentation differs depending on which MicroProfile OpenAPI feature version you use. +When multiple applications or an application with more than one web module are deployed to the same Open Liberty runtime, the structured documentation differs depending on which MicroProfile OpenAPI feature version you use. .Multiple application and multi-module application support with MicroProfile OpenAPI [cols="1,2", options="header"] @@ -171,21 +170,39 @@ When multiple applications or applications with more than one web module are dep |Feature |Default behavior |`mpOpenAPI-4.0` -|All deployed applications and modules are included in the structured documentation, and the behavior can be modified through configuration. +|All deployed applications and modules are included in the structured documentation. You can modify this behavior through configuration. |`mpOpenAPI-2.0` to `mpOpenAPI-3.1` -|Only the first web module of the first deployed application is included in the structured documentation, but the behavior can be modified through configuration. +|Only the first web module of the first deployed application is included in the structured documentation. You can modify this behavior through configuration. |`mpOpenAPI-1.0` to `mpOpenAPI-1.1` -|Only the first web module of the first deployed application is included in the structured documentation, and this behavior cannot be modified. +|Only the first web module of the first deployed application is included in the structured documentation. This behavior cannot be modified. |=== [#conf-mm-supprt] -== Configuring multiple application and multi-module API documentation +== Including and excluding applications and modules from OpenAPI documentation + +You can configure which applications or modules are included in your OpenAPI documentation either by setting elements in your server.xml file or by specifying MicroProfile Config properties. For most scenarios, 'server.xml` configuration is preferred and MicroProfile Config properties are recommended only for compatibility with earlier versions of MicroProfile OpenAPI that are already using these properties. + +Configure application or module documentation by using the `server.xml` file:: +You can control the inclusion and exclusion of applications and modules in the OpenAPI documentation by configuring the `mpOpenAPI` configuration element in your `server.xml` file. ++ +In MicroProfile OpenAPI 4.0 and later, all applications and modules are included by default. To exclude certain applications or modules, see link:/docs/latest/reference/feature/mpOpenAPI-4.0.html#_configure_openapi_documentation_for_a_multi_module_application[MicroProfile 4.0: Configure OpenAPI documentation for a multi-module application]. ++ +In MicroProfile MicroProfile OpenAPI 2.0-.31, only the first web module of the first deployed application is included in the structured documentation. To include or exclude applications or modules, see link:/docs/latest/reference/feature/mpOpenAPI-3.0.html#_configure_openapi_documentation_for_a_multi_module_application[MicroProfile 3.0: Configure OpenAPI documentation for a multi-module application] + +Configure application or module documentation by using MicroProfile Config properties:: +MicroProfile Config provides properties to manage which applications and modules are included in the generated OpenAPI documentation. This option is recommended only for compatibility with applications that already use MicroProfile config to include or exclude modules or applications fro the API documentation. Newer configurations can instead use the `server.xml` file, as previously described. ++ +- You must configure properties by using sources that apply to the entire server, such as the `jvm.properties`, `server.env`, or the environment variables. +- When you configure support for multiple applications and multi-module environments by using MicroProfile Config, the application name is determined from the application's deployment descriptor (`application.xml` or `web.xml`). If the deployment descriptor is missing or does not specify a name, the application name defaults to the application archive file name without the file extension. Similarly, the module name is specified in the web module `web.xml` file. If the `web.xml` file does not exist or does not specify a name, the module name defaults to the file name without the file extension. +- Any configuration that is defined in the `server.xml` file to include or exclude modules and applications takes precedence over configuration that is set through MicroProfile Config. ++ +For more information, see the xref:reference:config/mpOpenAPI.adoc[MicroProfile Config properties for MicroProfile OpenAPI]. -Open Liberty offers two main ways to configure support for multiple applications and multi-module projects. -=== Configure by using the `server.xml` file + +=== Customize the structured API documentation that is generated for your applications by configuring the link:/docs/latest/reference/feature/mpOpenAPI-4.0.html#_configure_openapi_documentation_for_a_multi_module_application[server.xml] file. Use the following elements within the `mpOpenAPI` configuration to control the inclusion and exclusion of applications and modules in the OpenAPI documentation: @@ -204,11 +221,10 @@ For more information, see the feature:mpOpenAPI[MicroProfile OpenAPI 4.0] featur MicroProfile Config provides a way to manage which applications and modules are included in the generated OpenAPI documentation by specifying configuration properties. Use these properties to define inclusion and exclusion rules and to customize the `info` section of the final OpenAPI document. - This method is suitable for dynamic setups because it allows changes to be made without directly modifying the `server.xml` file. -- When both methods are used, configurations that are defined in the `server.xml` file take precedence over the ones set through MicroProfile Config. -- Properties must be configured by using sources that apply to the entire server, such as the `jvm.properties`, `server.env`, or the environment variables. + - MicroProfile Config options are compatible only with versions 3.0 and earlier. -When you configure support for multiple applications and multi-module environments by using MicroProfile Config, the application and module names are determined based on specific rules. +, the application and module names are determined based on specific rules. - **Application name**: The application name is determined from the application's deployment descriptor (`application.xml` or `web.xml`). If the deployment descriptor is missing or does not specify a name, the application name defaults to the application archive filename with the file extension removed. - **Module name**: The module name is determined by using the same rules as described for the `server.xml` configuration. diff --git a/modules/reference/pages/feature/mpOpenAPI-3.0/examples.adoc b/modules/reference/pages/feature/mpOpenAPI-3.0/examples.adoc index 967a64d24..e4162cd72 100644 --- a/modules/reference/pages/feature/mpOpenAPI-3.0/examples.adoc +++ b/modules/reference/pages/feature/mpOpenAPI-3.0/examples.adoc @@ -1,9 +1,9 @@ === Configure OpenAPI documentation for a multi-module application -// This example only applies to 2.0 forward, and so the file and directory must be manually copied and applied to any new versions. Copy the directory and file and change the directory name to reflect the new feature version, for example `mpOpenAPI-3.2`. +// This example applies only to versions 2.0-3.1. -By default, only the first module of the first deployed application is included in the OpenAPI documentation. However, you can configure the MicroProfile OpenAPI feature to merge the OpenAPI documentation for multiple applications or modules into a single document. +Only the first module of the first deployed application is included in the OpenAPI documentation by default. However, you can configure the MicroProfile OpenAPI feature to merge the OpenAPI documentation for multiple applications or modules into a single document. For example, the following configuration is for the `sample_app` application, which consists of an `EAR` file containing five web modules. @@ -26,13 +26,13 @@ For example, the following configuration is for the `sample_app` application, wh ---- -- The `` element specifies that all applications are included in the final OpenAPI document. +- The `includeApplication` element specifies that all applications are included in the final OpenAPI document. -- The `` elements exclude the `module-3` and `module-5` web modules. +- The `excludeModule` elements exclude the `module-3` and `module-5` web modules. -- The `` element sets the info section for the final OpenAPI document, which documents web modules 1, 2, and 4. +- The `info` element sets the info section for the final OpenAPI document, which documents web modules 1, 2, and 4. -=== Naming applications and modules +==== Naming applications and modules - The application name is determined by the value of the `name` attribute when the application is deployed in `server.xml` using `application`, `webApplication`, or `enterpriseApplication`. For example: + @@ -45,9 +45,11 @@ If the application is deployed in the `dropins` directory or if the `name` attri + - The module name is specified in the web module's `web.xml` file. If there is no `web.xml` file or if it does not specify a name, the module name defaults to the filename with the extension removed. +For more information, see xref:ROOT:documentation-openapi.adoc#multi-module[Multiple application and multi-module application support with MicroProfile OpenAPI]. + === Override the info section in the OpenAPI document -You can also override the `info` section of the OpenAPI document using the following configuration: +You can override the `info` section of the OpenAPI document specifying the `info` element within the `mpOpenAPI` element: [source,xml] ---- @@ -58,6 +60,4 @@ You can also override the `info` section of the OpenAPI document using the follo ---- -Overriding the `info` section is useful for documenting multiple modules or applications. Without an override, the `info` section can be replaced with a standard version which indicates that documentation from several modules was merged. - -For more information, see xref:ROOT:documentation-openapi.adoc#multi-module[Multiple application and multi-module application support with MicroProfile OpenAPI] +Overriding the `info` section is useful for documenting multiple modules or applications. Without an override, the `info` section is a standard version that indicates that documentation from several modules was merged. diff --git a/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc b/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc index a70545021..2e21d22b2 100644 --- a/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc +++ b/modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc @@ -1,9 +1,9 @@ === Configure OpenAPI documentation for a multi-module application -// This example only applies to 2.0 forward, and so the file and directory must be manually copied and applied to any new versions. Copy the directory and file and change the directory name to reflect the new feature version, for example `mpOpenAPI-3.2`. +// This example applies only to versions 2.0-3.1. -By default, only the first module of the first deployed application is included in the OpenAPI documentation. However, you can configure the MicroProfile OpenAPI feature to merge the OpenAPI documentation for multiple applications or modules into a single document. +Only the first module of the first deployed application is included in the OpenAPI documentation by default. However, you can configure the MicroProfile OpenAPI feature to merge the OpenAPI documentation for multiple applications or modules into a single document. For example, the following configuration is for the `sample_app` application, which consists of an `EAR` file containing five web modules. @@ -26,13 +26,13 @@ For example, the following configuration is for the `sample_app` application, wh ---- -- The `` element specifies that all applications are included in the final OpenAPI document. +- The `includeApplication` element specifies that all applications are included in the final OpenAPI document. -- The `` elements exclude the `module-3` and `module-5` web modules. +- The `excludeModule` elements exclude the `module-3` and `module-5` web modules. -- The `` element sets the info section for the final OpenAPI document, which documents web modules 1, 2, and 4. +- The `info` element sets the info section for the final OpenAPI document, which documents web modules 1, 2, and 4. -=== Naming applications and modules +==== Naming applications and modules - The application name is determined by the value of the `name` attribute when the application is deployed in `server.xml` using `application`, `webApplication`, or `enterpriseApplication`. For example: + @@ -45,9 +45,11 @@ If the application is deployed in the `dropins` directory or if the `name` attri + - The module name is specified in the web module's `web.xml` file. If there is no `web.xml` file or if it does not specify a name, the module name defaults to the filename with the extension removed. +For more information, see xref:ROOT:documentation-openapi.adoc#multi-module[Multiple application and multi-module application support with MicroProfile OpenAPI] + === Override the info section in the OpenAPI document -You can also override the `info` section of the OpenAPI document using the following configuration: +You can override the `info` section of the OpenAPI document specifying the `info` element within the `mpOpenAPI` element: [source,xml] ---- @@ -58,8 +60,4 @@ You can also override the `info` section of the OpenAPI document using the follo ---- -Overriding the `info` section is useful for documenting multiple modules or applications. Without an override, the `info` section can be replaced with a standard version which indicates that documentation from several modules was merged. - -For more information, see xref:ROOT:documentation-openapi.adoc#multi-module[Multiple application and multi-module application support with MicroProfile OpenAPI] - - +Overriding the `info` section is useful for documenting multiple modules or applications. Without an override, the `info` section is a standard version that indicates that documentation from several modules was merged. diff --git a/modules/reference/pages/feature/mpOpenAPI-4.0/examples.adoc b/modules/reference/pages/feature/mpOpenAPI-4.0/examples.adoc index 92bf1e365..8f7eb8458 100644 --- a/modules/reference/pages/feature/mpOpenAPI-4.0/examples.adoc +++ b/modules/reference/pages/feature/mpOpenAPI-4.0/examples.adoc @@ -1,10 +1,10 @@ - +[#mm] === Configure OpenAPI documentation for a multi-module application -// This example only applies to 2.0 forward, and so the file and directory must be manually copied and applied to any new versions. Copy the directory and file and change the directory name to reflect the new feature version, for example `mpOpenAPI-3.2`. +// This example only applies to 4.0 forward, and so the file and directory must be manually copied and applied to any new versions. Copy the directory and file and change the directory name to reflect the new feature version, for example `mpOpenAPI-4.1`. -By default, all deployed applications and modules are included in the OpenAPI documentation. However, you can configure which applications and modules should be included. +In MicroProfile OpenAPI 4.0 and later, all deployed applications and modules are included in the OpenAPI documentation by default. However, you can configure which applications and modules are included. For example, the following configuration is for the `sample_app` application, which consists of an `EAR` file containing five web modules. @@ -26,11 +26,11 @@ For example, the following configuration is for the `sample_app` application, wh ---- -- The `` elements exclude the `module-3` and `module-5` web modules. +- The `excludeModule` elements exclude the `module-3` and `module-5` web modules. -- The `` element sets the info section for the final OpenAPI document, which documents web modules 1, 2, and 4. +- The `info` element sets the info section for the final OpenAPI document, which documents web modules 1, 2, and 4. -=== Naming applications and modules +==== Naming applications and modules - The application name is determined by the value of the `name` attribute when the application is deployed in `server.xml` using `application`, `webApplication`, or `enterpriseApplication`. For example: + @@ -39,13 +39,16 @@ For example, the following configuration is for the `sample_app` application, wh ---- + -If the application is deployed in the `dropins` directory or if the `name` attribute is not specified, the name defaults to the archive filename with the extension removed. +If the application is deployed in the `dropins` directory or if the `name` attribute is not specified, the name defaults to the archive filename without the file extension. + -- The module name is specified in the web module's `web.xml` file. If there is no `web.xml` file or if it does not specify a name, the module name defaults to the filename with the extension removed. +- The module name is specified in the web module's `web.xml` file. If no `web.xml` file exists or if it does not specify a name, the module name defaults to the file name without the file extension. + +For more information, see xref:ROOT:documentation-openapi.adoc#multi-module[Multiple application and multi-module application support with MicroProfile OpenAPI]. + === Override the info section in the OpenAPI document -You can also override the `info` section of the OpenAPI document using the following configuration: +You can override the `info` section of the OpenAPI document specifying the `info` element within the `mpOpenAPI` element: [source,xml] ---- @@ -56,17 +59,15 @@ You can also override the `info` section of the OpenAPI document using the follo ---- -Overriding the `info` section is useful for documenting multiple modules or applications. Without an override, the `info` section can be replaced with a standard version which indicates that documentation from several modules was merged. +Overriding the `info` section is useful for documenting multiple modules or applications. Without an override, the `info` section is a standard version that indicates that documentation from several modules was merged. [#apiversion] === Selecting the OpenAPI specification version -If you are using a feature that supports more than one version of the OpenAPI specification, you can switch between versions with configuration. You might need to do this if you or your end users use tools or libraries that don't yet support a newer version of the OpenAPI specification. +If you are using a feature that supports more than one version of the OpenAPI specification, you can switch between versions with configuration. You might need to do this if you or your users use tools or libraries that don't yet support a newer version of the OpenAPI specification. -For example, you can select OpenAPI v3.0 when using `mpOpenAPI-4.0`. +For example, `mpOpenAPI-4.0` defaults to OpenAPI 3.1, but you can specify the following configuration to set it to OpenAPI 3.0. [source,xml] ---- ---- - -For more information, see xref:ROOT:documentation-openapi.adoc#multi-module[Multiple application and multi-module application support with MicroProfile OpenAPI] \ No newline at end of file From 4df99bc5486aa1d98a1988e403da775b9b71c6c0 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Mon, 25 Nov 2024 15:58:46 -0500 Subject: [PATCH 60/81] Update documentation-openapi.adoc --- modules/ROOT/pages/documentation-openapi.adoc | 30 ------------------- 1 file changed, 30 deletions(-) diff --git a/modules/ROOT/pages/documentation-openapi.adoc b/modules/ROOT/pages/documentation-openapi.adoc index 5b6c19511..985de1a46 100644 --- a/modules/ROOT/pages/documentation-openapi.adoc +++ b/modules/ROOT/pages/documentation-openapi.adoc @@ -201,36 +201,6 @@ MicroProfile Config provides properties to manage which applications and modules For more information, see the xref:reference:config/mpOpenAPI.adoc[MicroProfile Config properties for MicroProfile OpenAPI]. - -=== - -Customize the structured API documentation that is generated for your applications by configuring the link:/docs/latest/reference/feature/mpOpenAPI-4.0.html#_configure_openapi_documentation_for_a_multi_module_application[server.xml] file. Use the following elements within the `mpOpenAPI` configuration to control the inclusion and exclusion of applications and modules in the OpenAPI documentation: - -- `includeApplication`: Specifies applications to include in the documentation. -- `excludeApplication`: Specifies applications to exclude from the documentation. -- `includeModule`: Specifies modules to include in the documentation. -- `excludeModule`: Specifies modules to exclude from the documentation. - -This configuration provides flexibility to tailor the documentation to your specific needs, such as excluding sensitive modules or overriding default metadata. - -For more information, see the feature:mpOpenAPI[MicroProfile OpenAPI 4.0] feature. - - -=== Configure by using MicroProfile Config properties - -MicroProfile Config provides a way to manage which applications and modules are included in the generated OpenAPI documentation by specifying configuration properties. Use these properties to define inclusion and exclusion rules and to customize the `info` section of the final OpenAPI document. - -- This method is suitable for dynamic setups because it allows changes to be made without directly modifying the `server.xml` file. - -- MicroProfile Config options are compatible only with versions 3.0 and earlier. - -, the application and module names are determined based on specific rules. - -- **Application name**: The application name is determined from the application's deployment descriptor (`application.xml` or `web.xml`). If the deployment descriptor is missing or does not specify a name, the application name defaults to the application archive filename with the file extension removed. -- **Module name**: The module name is determined by using the same rules as described for the `server.xml` configuration. - -For more information, see the xref:reference:config/mpOpenAPI.adoc[MicroProfile Config properties for MicroProfile OpenAPI]. - == See also - Guide: link:/guides/microprofile-config-intro.html[Separating configuration from code in microservices] From aef0d49cc0d066148a29a31efd1051cb7063ad98 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Mon, 25 Nov 2024 19:29:44 -0500 Subject: [PATCH 61/81] Update documentation-openapi.adoc --- modules/ROOT/pages/documentation-openapi.adoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/modules/ROOT/pages/documentation-openapi.adoc b/modules/ROOT/pages/documentation-openapi.adoc index 985de1a46..18943af0a 100644 --- a/modules/ROOT/pages/documentation-openapi.adoc +++ b/modules/ROOT/pages/documentation-openapi.adoc @@ -180,19 +180,19 @@ When multiple applications or an application with more than one web module are d |=== [#conf-mm-supprt] -== Including and excluding applications and modules from OpenAPI documentation +=== Including and excluding applications and modules from OpenAPI documentation -You can configure which applications or modules are included in your OpenAPI documentation either by setting elements in your server.xml file or by specifying MicroProfile Config properties. For most scenarios, 'server.xml` configuration is preferred and MicroProfile Config properties are recommended only for compatibility with earlier versions of MicroProfile OpenAPI that are already using these properties. +You can configure which applications or modules are included in your OpenAPI documentation either by setting elements in your `server.xml` file or by specifying MicroProfile Config properties. For most scenarios, `server.xml` configuration is preferred and MicroProfile Config properties are recommended only for compatibility with existing configurations that are already using these properties. Configure application or module documentation by using the `server.xml` file:: You can control the inclusion and exclusion of applications and modules in the OpenAPI documentation by configuring the `mpOpenAPI` configuration element in your `server.xml` file. + -In MicroProfile OpenAPI 4.0 and later, all applications and modules are included by default. To exclude certain applications or modules, see link:/docs/latest/reference/feature/mpOpenAPI-4.0.html#_configure_openapi_documentation_for_a_multi_module_application[MicroProfile 4.0: Configure OpenAPI documentation for a multi-module application]. +In MicroProfile OpenAPI 4.0 and later, all applications and modules are included by default. To exclude certain applications or modules, see link:/docs/latest/reference/feature/mpOpenAPI-4.0.html#mm[MicroProfile 4.0: Configure OpenAPI documentation for a multi-module application]. + -In MicroProfile MicroProfile OpenAPI 2.0-.31, only the first web module of the first deployed application is included in the structured documentation. To include or exclude applications or modules, see link:/docs/latest/reference/feature/mpOpenAPI-3.0.html#_configure_openapi_documentation_for_a_multi_module_application[MicroProfile 3.0: Configure OpenAPI documentation for a multi-module application] +In MicroProfile MicroProfile OpenAPI 2.0-3.1, only the first web module of the first deployed application is included in the structured documentation. To include or exclude applications or modules, see link:/docs/latest/reference/feature/mpOpenAPI-3.0.html#_configure_openapi_documentation_for_a_multi_module_application[MicroProfile 3.0: Configure OpenAPI documentation for a multi-module application] Configure application or module documentation by using MicroProfile Config properties:: -MicroProfile Config provides properties to manage which applications and modules are included in the generated OpenAPI documentation. This option is recommended only for compatibility with applications that already use MicroProfile config to include or exclude modules or applications fro the API documentation. Newer configurations can instead use the `server.xml` file, as previously described. +MicroProfile Config provides properties to manage which applications and modules are included in the generated OpenAPI documentation. This option is recommended only for compatibility with applications that already use MicroProfile Config to include or exclude modules or applications fro the API documentation. Newer configurations can instead use the `server.xml` file, as previously described. + - You must configure properties by using sources that apply to the entire server, such as the `jvm.properties`, `server.env`, or the environment variables. - When you configure support for multiple applications and multi-module environments by using MicroProfile Config, the application name is determined from the application's deployment descriptor (`application.xml` or `web.xml`). If the deployment descriptor is missing or does not specify a name, the application name defaults to the application archive file name without the file extension. Similarly, the module name is specified in the web module `web.xml` file. If the `web.xml` file does not exist or does not specify a name, the module name defaults to the file name without the file extension. @@ -203,4 +203,4 @@ For more information, see the xref:reference:config/mpOpenAPI.adoc[MicroProfile == See also -- Guide: link:/guides/microprofile-config-intro.html[Separating configuration from code in microservices] +- Guide: link:/guides/microprofile-openapi.html[Documenting RESTful APIs] From a3dde158af5654faca9d0e23750e364744f0fe2c Mon Sep 17 00:00:00 2001 From: David Mueller Date: Mon, 25 Nov 2024 19:34:42 -0500 Subject: [PATCH 62/81] Update documentation-openapi.adoc --- modules/ROOT/pages/documentation-openapi.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/documentation-openapi.adoc b/modules/ROOT/pages/documentation-openapi.adoc index 18943af0a..198be8388 100644 --- a/modules/ROOT/pages/documentation-openapi.adoc +++ b/modules/ROOT/pages/documentation-openapi.adoc @@ -198,7 +198,7 @@ MicroProfile Config provides properties to manage which applications and modules - When you configure support for multiple applications and multi-module environments by using MicroProfile Config, the application name is determined from the application's deployment descriptor (`application.xml` or `web.xml`). If the deployment descriptor is missing or does not specify a name, the application name defaults to the application archive file name without the file extension. Similarly, the module name is specified in the web module `web.xml` file. If the `web.xml` file does not exist or does not specify a name, the module name defaults to the file name without the file extension. - Any configuration that is defined in the `server.xml` file to include or exclude modules and applications takes precedence over configuration that is set through MicroProfile Config. + -For more information, see the xref:reference:config/mpOpenAPI.adoc[MicroProfile Config properties for MicroProfile OpenAPI]. +For more information, see the xref:microprofile-config-properties.adoc#openap[MicroProfile Config properties for MicroProfile OpenAPI]. == See also From b395778b07d4e1bd2db5b2927564e34a3c37081d Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Tue, 26 Nov 2024 12:28:33 +0530 Subject: [PATCH 63/81] 7654-Documentation-MicroProfile-OpenAPI-4.0-010 7654-Documentation-MicroProfile-OpenAPI-4.0-010 #7654 --- modules/ROOT/pages/documentation-openapi.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/documentation-openapi.adoc b/modules/ROOT/pages/documentation-openapi.adoc index 198be8388..558958ef0 100644 --- a/modules/ROOT/pages/documentation-openapi.adoc +++ b/modules/ROOT/pages/documentation-openapi.adoc @@ -198,7 +198,7 @@ MicroProfile Config provides properties to manage which applications and modules - When you configure support for multiple applications and multi-module environments by using MicroProfile Config, the application name is determined from the application's deployment descriptor (`application.xml` or `web.xml`). If the deployment descriptor is missing or does not specify a name, the application name defaults to the application archive file name without the file extension. Similarly, the module name is specified in the web module `web.xml` file. If the `web.xml` file does not exist or does not specify a name, the module name defaults to the file name without the file extension. - Any configuration that is defined in the `server.xml` file to include or exclude modules and applications takes precedence over configuration that is set through MicroProfile Config. + -For more information, see the xref:microprofile-config-properties.adoc#openap[MicroProfile Config properties for MicroProfile OpenAPI]. +For more information, see the xref:microprofile-config-properties.adoc#openapi[MicroProfile Config properties for MicroProfile OpenAPI]. == See also From 809a1a99af779550d521dd0ba513ba201c16a798 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Tue, 26 Nov 2024 16:59:06 +0530 Subject: [PATCH 64/81] 7610-MicroProfile 7.0 ID-7 7610-MicroProfile 7.0 ID-7 #7610 --- .../pages/send-receive-multipart-jaxrs.adoc | 58 +++++++++ .../reference/pages/diff/mp-61-70-diff.adoc | 118 ++++-------------- 2 files changed, 80 insertions(+), 96 deletions(-) diff --git a/modules/ROOT/pages/send-receive-multipart-jaxrs.adoc b/modules/ROOT/pages/send-receive-multipart-jaxrs.adoc index c9089d58d..3f725d79a 100644 --- a/modules/ROOT/pages/send-receive-multipart-jaxrs.adoc +++ b/modules/ROOT/pages/send-receive-multipart-jaxrs.adoc @@ -45,6 +45,64 @@ buildscript { } ---- +[#multipart] +== Processing multipart data + +The `multipart/form-data` media type enables requests to send multiple entities (parts) as a single entity using `jakarta.ws.rs.core.EntityPart` objects. + +For example, MicroProfile Multipart Rest Clients are defined as Java interfaces. + +[source,java] +---- +@Consumes(MediaType.MULTIPART_FORM_DATA) +@Produces(MediaType.MULTIPART_FORM_DATA) +@Path("/test-app") +public interface MultiPartClient extends AutoCloseable { + + @POST + @Path("upload/") + void uploadFile(List entityParts) throws IOException; +} +---- + +The example code utilizing this ingerface + +source,java] +---- +public void uploadMultipleFiles() throws Exception { + try (MultiPartClient client = RestClientBuilder.newBuilder() + .baseUri(uri) + .build(MultiPartClient.class)) { + final Map entityPartContent = new LinkedHashMap<>(2); + try (InputStream in = MultiPartClientTest.class + .getResourceAsStream("/multipart/test-file1.txt")) { + entityPartContent.put("test-file1.txt", in.readAllBytes()); + } + try (InputStream in = MultiPartClientTest.class + .getResourceAsStream("/multipart/test-file2.txt")) { + entityPartContent.put("test-file2.txt", in.readAllBytes()); + } + final List files = entityPartContent.entrySet() + .stream() + .map((entry) -> { + try { + return EntityPart.withName(entry.getKey()) + .fileName(entry.getKey()) + .content(entry.getValue()) + .mediaType(MediaType.APPLICATION_OCTET_STREAM_TYPE) + .build(); + } catch (IOException e) { + throw new UncheckedIOException(e); + } + }) + .collect(Collectors.toList()); + client.uploadFile(files); + + } + } +---- + + == Send multipart/form-data parts from Jakarta Restful Web Services resources One way to send multipart form data in an HTTP request is to use an HTML form. You might create an HTML form for a human user to send file data to a web application. The following example shows an HTML form that sends an HTTP request in three parts that each specifies a particular content type. diff --git a/modules/reference/pages/diff/mp-61-70-diff.adoc b/modules/reference/pages/diff/mp-61-70-diff.adoc index cffccc8b2..eafa020b4 100644 --- a/modules/reference/pages/diff/mp-61-70-diff.adoc +++ b/modules/reference/pages/diff/mp-61-70-diff.adoc @@ -87,7 +87,7 @@ RestClientBuilder.newBuilder() === Processing multipart data -Information and example code are added to the link:https://download.eclipse.org/microprofile/microprofile-rest-client-4.0/microprofile-rest-client-spec-4.0.html#_processing_multipart_data[MicroProfile Rest Client 4.0 specification] for processing multipart data, introduced as part of RESTful Web Services version 3.1 in EE10. +Information and example code are added to the xref:send-receive-multipart-jaxrs.adoc#multipart[Send and receive multipart/form-data parts in Jakarta Restful Web Services] for processing multipart data, introduced as part of RESTful Web Services version 3.1 in EE10. [#openapi] @@ -103,14 +103,10 @@ New APIs and annotation parameters are added to MicroProfile OpenAPI 4.0, to all If you use the new APIs and annotations corresponding to OpenAPI 3.1 features, the additional information they provide is not be included when the feature is configured to generate OpenAPI 3.0 documents. -However, these changes mean that OpenAPI 3.1 is not fully backward compatible with OpenAPI 3.0, and existing tools may not work with it. To maintain compatibility with existing tools, you can configure `mpOpenAPI-4.0` to produce OpenAPI 3.0 documentation. +However, these changes mean that OpenAPI 3.1 is not fully backward compatible with OpenAPI 3.0, and existing tools may not work with it. To maintain compatibility with existing tools, you can configure `mpOpenAPI-4.0` to produce OpenAPI 3.0 documentation. For more information, see link:/docs/latest/reference/feature/mpOpenAPI-4.0.html#apiversion[Selecting the OpenAPI specification version]. -[source,xml] ----- - ----- -=== All Deployed Applications Are Documented by Default +=== All deployed applications are documented by default In this update, all deployed applications are included in the OpenAPI documentation by default. In previous versions of mpOpenAPI, only the first module of the first deployed application was documented by default. You can control which applications are included in the documentation using the following configuration: @@ -132,17 +128,9 @@ For more information on this configuration, see feature:mpOpenAPI-4.0[display=Mi MicroProfile Fault Tolerance 4.1, an update to version 4.0, introduces integration with MicroProfile Telemetry 2.0. This allows Fault Tolerance to export metrics directly to MicroProfile Telemetry. The existing integration with `mpMetrics` remains unchanged. +For more information, see the link:/docs/latest/reference/feature/mpFaultTolerance-4.1.html#_enabling_this_feature[MicroProfile Fault Tolerance] feature. -=== Enable MicroProfile Fault Tolerance - -To enable MicroProfile Fault Tolerance, add the following to your `server.xml` file. - -[source,xml] ----- -mpFaultTolerance-4.1 ----- - -For integration between `mpFaultTolerance` and `mpTelemetry`, you must enable both `mpFaultTolerance-4.1` and `mpTelemetry-2.0` simultaneously. When both features are enabled, mpFaultTolerance will automatically export metrics to mpTelemetry. +For integration between feature:mpFaultTolerance-4.1[display=MicroProfile Fault Tolerance] and feature:mpTelemetry-2.0[display=MicroProfile Telemetry], you must enable both feature:mpFaultTolerance-4.1[display=MicroProfile Fault Tolerance 4.1] and feature:mpTelemetry-2.0[display=MicroProfile Telemetry 2.0] simultaneously. When both features are enabled, feature:mpFaultTolerance-4.1[display=MicroProfile Fault Tolerance] will automatically export metrics to feature:mpTelemetry-2.0[display=MicroProfile Telemetry]. [source,xml] ---- @@ -150,54 +138,54 @@ For integration between `mpFaultTolerance` and `mpTelemetry`, you must enable bo mpTelemetry-2.0 ---- -For more information on configuring mpTelemetry to export metrics, see the section on `mpTelemetry-2.0`. +For more information on configuring feature:mpTelemetry-2.0[display=MicroProfile Telemetry] to export metrics, see xref:microprofile-telemetry.html#global[ollecting and exporting logs, metrics, and traces with OpenTelemetry]. -If `mpFaultTolerance-4.1` is enabled alongside both `mpTelemetry-2.0` and `mpMetrics-5.1`, Fault Tolerance will export metrics to both mpTelemetry and mpMetrics. +If feature:mpFaultTolerance-4.1[display=MicroProfile Fault Tolerance] is enabled alongside both feature:mpTelemetry-2.0[display=MicroProfile Telemetry] and feature:mpMetrics-5.1[display=MicroProfile Metrics], Fault Tolerance will export metrics to both MicroProfile Telemetry and MicroProfile Metrics. -.Comparison between metrics in mpMetrics and mpTelemetry +.Comparison of Metric Types between MicroProfile Metrics and MicroProfile Telemetry [cols="1,1,1", options="header"] |=== -|Name |Type in mpMetrics |Type in mpTelemetry +|Name |Type in MicroProfile Metrics |Type in MicroProfile Telemetry |`ft.invocations.total` |`Counter` -|A counter that emits long +|`Counter` (provides a long value) |`ft.retry.calls.total` |`Counter` -|A counter that emits long +|`Counter` (provides a long value) |`ft.retry.retries.total` |`Counter` -|A counter that emits long +|`Counter` (provides a long value) |`ft.timeout.calls.total` |`Counter` -|A counter that emits long +|`Counter` (provides a long value) |`ft.circuitbreaker.calls.total` |`Counter` -|A counter that emits long +|`Counter` (provides a long value) |`ft.circuitbreaker.state.total` |`Gauge` -|A counter that emits long +|`Counter` (provides a long value) |`ft.circuitbreaker.opened.total` |`Counter` -|A counter that emits long +|`Counter` (provides a long value) |`ft.bulkhead.calls.total` |`Counter` -|A counter that emits long +|`Counter` (provides a long value) |`ft.bulkhead.executionsRunning` |`Gauge` -|An UpDownCounter that emits long +|`UpDownCounter` (provides a long value) |`ft.bulkhead.executionsWaiting` |`Gauge` -|An UpDownCounter that emits long +|`UpDownCounter` (provides a long value) |=== @@ -229,7 +217,7 @@ If `mpFaultTolerance-4.1` is enabled alongside both `mpTelemetry-2.0` and `mpMet [#tm] == Differences between MicroProfile Telemetry 2.0 and 1.1 -MicroProfile Telemetry 2.0 is an update to MicroProfile Telemetry 1.1, incorporating the latest OpenTelemetry SDK (version 1.39). Previously, only traces were collected and exported. The updated feature now includes the ability to collect and export metrics and logs. Specifically, the following enhancements are provided: +feature:mpTelemetry-2.0[display=MicroProfile Telemetry 2.0] is an update to MicroProfile Telemetry 1.1, incorporating the latest OpenTelemetry SDK (version 1.39). Previously, only traces were collected and exported. The updated feature now includes the ability to collect and export metrics and logs. Specifically, the following enhancements are provided: * Access to the OpenTelemetry Metrics API * HTTP metrics @@ -237,73 +225,11 @@ MicroProfile Telemetry 2.0 is an update to MicroProfile Telemetry 1.1, incorpora * Runtime-level logs * Application logs -=== Enable MicroProfile Telemetry - -To enable MicroProfile Telemetry, add the following to your `server.xml` file. - -[source,xml] ----- -mpTelemetry-2.0 ----- +For more information, see the link:/docs/latest/reference/feature/mpTelemetry-2.0.html#_enabling_this_feature[MicroProfile Telemetry] feature. MicroProfile Telemetry 2.0 provides runtime-level telemetry. To enable this, you must add the MicroProfile Telemetry feature to your `server.xml` file and enable the OpenTelemetry SDK by using system properties or environment variables. Once enabled, you can configure how MicroProfile Telemetry collects and exports traces, metrics, and logs. This is different from MicroProfile Telemetry 1.1, which provided full functionality by using only MicroProfile Config for configuration. If you do not use system properties or environment variables for configuration, runtime-level metrics and logs cannot be collected. Using other available MicroProfile Config properties cannot enable the collection of these metrics and logs. -To enable the OpenTelemetry SDK, use the following configuration. - -[source,properties] ----- -otel.sdk.disabled=false ----- - -To set the name of the service, use the following configuration. -[source,properties] ----- -otel.service.name=app1 ----- - - -=== Accessing the Metrics API - -You can use the OpenTelemetry Metrics API to define custom metrics within your application code. By enabling the MicroProfile Telemetry feature version 2.0 or later, you can collect and emit these custom metrics to customize the observability of your application. - -For more information on the OpenTelemetry metrics, see the link:https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/1.39.0/io/opentelemetry/api/metrics/package-summary.html[OpenTelemetry Metrics API documentation]. - -To make the APIs accessible, you must enable third-party APIs for your application by adding the following configuration to your `server.xml` file. - -[source,xml] ----- - - - ----- - -=== Collecting logs - -You can enable MicroProfile Telemetry to collect logs from various sources within the Open Liberty runtime environment. MicroProfile Telemetry can collect the following types of events: - -- xref:ROOT:mptel-log-events-list.adoc#me[Message events] -- xref:ROOT:mptel-log-events-list.adoc#te[Trace events] -- xref:ROOT:mptel-log-events-list.adoc#ffdce[FFDC events] - -To enable these log sources, configure the source attribute for the mpTelemetry element with a comma-separated list of the desired log sources: - -[source,xml] ----- - ----- - -The mpTelemetry configuration element is optional. If you do not specify it or omit the source attribute, the default configuration source is message. For more details, see feature:mpTelemetry-2.0[display=Collect logs from a specified source]. - -=== Exporting metrics and logs - -By default, all OpenTelemetry data is exported to link:https://opentelemetry.io/docs/specs/otel/protocol/exporter/[OTLP]. You can change the export settings for metrics by specifying the `otel.metrics.exporter` property or the `OTEL_METRICS_EXPORTER` environment variable. For logs, specify the `otel.logs.exporter` property or the `OTEL_LOGS_EXPORTER` environment variable. - -For example, to change the metrics exporter so that collected metrics are sent to the console, set the following: - -[source,properties] ----- -otel.metrics.exporter = console ----- +For more information on OpenTelemetry, see xref:microprofile-telemetry.html[ollecting and exporting logs, metrics, and traces with OpenTelemetry]. From 18fe4a52b5b69c62d68cd74d989966f2838b7c24 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Tue, 26 Nov 2024 17:01:38 +0530 Subject: [PATCH 65/81] 7610-MicroProfile 7.0 ID-8 7610-MicroProfile 7.0 ID-8 #7610 --- modules/reference/pages/diff/mp-61-70-diff.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/reference/pages/diff/mp-61-70-diff.adoc b/modules/reference/pages/diff/mp-61-70-diff.adoc index eafa020b4..0e678188f 100644 --- a/modules/reference/pages/diff/mp-61-70-diff.adoc +++ b/modules/reference/pages/diff/mp-61-70-diff.adoc @@ -231,5 +231,5 @@ MicroProfile Telemetry 2.0 provides runtime-level telemetry. To enable this, you If you do not use system properties or environment variables for configuration, runtime-level metrics and logs cannot be collected. Using other available MicroProfile Config properties cannot enable the collection of these metrics and logs. -For more information on OpenTelemetry, see xref:microprofile-telemetry.html[ollecting and exporting logs, metrics, and traces with OpenTelemetry]. +For more information on OpenTelemetry, see xref:microprofile-telemetry.html[Collecting and exporting logs, metrics, and traces with OpenTelemetry]. From 5832aa4bc4834098e8ddaefbce1b474c8a50a417 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Tue, 26 Nov 2024 18:21:58 +0530 Subject: [PATCH 66/81] 7610-MicroProfile 7.0 ID-9 7610-MicroProfile 7.0 ID-9 #7610 --- modules/reference/pages/diff/mp-61-70-diff.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/reference/pages/diff/mp-61-70-diff.adoc b/modules/reference/pages/diff/mp-61-70-diff.adoc index 0e678188f..b14a4d343 100644 --- a/modules/reference/pages/diff/mp-61-70-diff.adoc +++ b/modules/reference/pages/diff/mp-61-70-diff.adoc @@ -87,7 +87,7 @@ RestClientBuilder.newBuilder() === Processing multipart data -Information and example code are added to the xref:send-receive-multipart-jaxrs.adoc#multipart[Send and receive multipart/form-data parts in Jakarta Restful Web Services] for processing multipart data, introduced as part of RESTful Web Services version 3.1 in EE10. +Information and example code are added to the xref:ROOT:send-receive-multipart-jaxrs.adoc#multipart[send and receive multipart/form-data parts in Jakarta Restful Web Services] for processing multipart data, introduced as part of RESTful Web Services version 3.1 in EE10. [#openapi] @@ -138,7 +138,7 @@ For integration between feature:mpFaultTolerance-4.1[display=MicroProfile Fault mpTelemetry-2.0 ---- -For more information on configuring feature:mpTelemetry-2.0[display=MicroProfile Telemetry] to export metrics, see xref:microprofile-telemetry.html#global[ollecting and exporting logs, metrics, and traces with OpenTelemetry]. +For more information on configuring feature:mpTelemetry-2.0[display=MicroProfile Telemetry] to export metrics, see xref:ROOT:microprofile-telemetry.adoc#global[Collecting and exporting logs, metrics, and traces with OpenTelemetry]. If feature:mpFaultTolerance-4.1[display=MicroProfile Fault Tolerance] is enabled alongside both feature:mpTelemetry-2.0[display=MicroProfile Telemetry] and feature:mpMetrics-5.1[display=MicroProfile Metrics], Fault Tolerance will export metrics to both MicroProfile Telemetry and MicroProfile Metrics. @@ -231,5 +231,5 @@ MicroProfile Telemetry 2.0 provides runtime-level telemetry. To enable this, you If you do not use system properties or environment variables for configuration, runtime-level metrics and logs cannot be collected. Using other available MicroProfile Config properties cannot enable the collection of these metrics and logs. -For more information on OpenTelemetry, see xref:microprofile-telemetry.html[Collecting and exporting logs, metrics, and traces with OpenTelemetry]. +For more information on OpenTelemetry, see xref:ROOT:microprofile-telemetry.adoc[Collecting and exporting logs, metrics, and traces with OpenTelemetry]. From 8b92302f92e883ce05a8c4d9870a63c0a2574447 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Tue, 26 Nov 2024 18:29:24 +0530 Subject: [PATCH 67/81] 7654-Documentation-MicroProfile-OpenAPI-4.0-011 7654-Documentation-MicroProfile-OpenAPI-4.0-011 #7654 --- modules/ROOT/pages/documentation-openapi.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/documentation-openapi.adoc b/modules/ROOT/pages/documentation-openapi.adoc index 558958ef0..b37c18b43 100644 --- a/modules/ROOT/pages/documentation-openapi.adoc +++ b/modules/ROOT/pages/documentation-openapi.adoc @@ -198,7 +198,7 @@ MicroProfile Config provides properties to manage which applications and modules - When you configure support for multiple applications and multi-module environments by using MicroProfile Config, the application name is determined from the application's deployment descriptor (`application.xml` or `web.xml`). If the deployment descriptor is missing or does not specify a name, the application name defaults to the application archive file name without the file extension. Similarly, the module name is specified in the web module `web.xml` file. If the `web.xml` file does not exist or does not specify a name, the module name defaults to the file name without the file extension. - Any configuration that is defined in the `server.xml` file to include or exclude modules and applications takes precedence over configuration that is set through MicroProfile Config. + -For more information, see the xref:microprofile-config-properties.adoc#openapi[MicroProfile Config properties for MicroProfile OpenAPI]. +For more information, see the link:/docs/latest/reference/microprofile-config-properties.html#openapi[MicroProfile Config properties for MicroProfile OpenAPI]. == See also From 1abd67f12ef40d4c66a69abc41437050997cce02 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Tue, 26 Nov 2024 13:04:37 -0500 Subject: [PATCH 68/81] edits #7655 --- .../pages/custom-mptelemetry-metrics.adoc | 2 +- modules/ROOT/pages/fault-tolerance.adoc | 7 ++++- modules/ROOT/pages/telemetry-trace.adoc | 2 +- .../feature/mpTelemetry-2.0/description.adoc | 1 + .../feature/mpTelemetry-2.0/examples.adoc | 28 ++----------------- 5 files changed, 12 insertions(+), 28 deletions(-) create mode 100644 modules/reference/pages/feature/mpTelemetry-2.0/description.adoc diff --git a/modules/ROOT/pages/custom-mptelemetry-metrics.adoc b/modules/ROOT/pages/custom-mptelemetry-metrics.adoc index 0176592ad..4e6618973 100644 --- a/modules/ROOT/pages/custom-mptelemetry-metrics.adoc +++ b/modules/ROOT/pages/custom-mptelemetry-metrics.adoc @@ -18,7 +18,7 @@ For more information about collecting and emitting metrics with MicroProfile Tel For more information about OpenTelemetry metrics, see the link:https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/1.39.0/io/opentelemetry/api/metrics/package-summary.html[OpenTelemetry metrics API documentation]. -Before you can use OpenTelemetry to define custom metrics metrics, you must make 3rd party APIs visible in your runtime environment by editing your runtime configuration. You must also add the OpenTelemetry API and annotations as a dependency on your build path. For more information, see link:/docs/latest/reference/feature/mpTelemetry-2.0.html#dev[Customize your application telemetry with the OpenTelemetry API]. +Before you can use OpenTelemetry to define custom metrics metrics, you must make 3rd party APIs visible in your runtime environment by editing your runtime configuration. For more information, see link:/docs/latest/reference/feature/mpTelemetry-2.0.html#dev[Customize your application telemetry with the OpenTelemetry API]. The following example defines a custom counter metric: diff --git a/modules/ROOT/pages/fault-tolerance.adoc b/modules/ROOT/pages/fault-tolerance.adoc index d6a5fd8fd..b000f2875 100644 --- a/modules/ROOT/pages/fault-tolerance.adoc +++ b/modules/ROOT/pages/fault-tolerance.adoc @@ -17,10 +17,13 @@ You can build resilient microservices by including fault tolerance policies in y Microservice-based applications are resilient when they can continue operating if there is a failure or error in some part of the system. Fault tolerance helps applications fail fast and recover smoothly by guiding how and when certain requests occur and by providing fallback strategies to handle common errors. For example, in an airline ticket application, different microservices might support scheduling, purchasing, and customer preferences. If one service fails, fault tolerance policies help contain the error and keep it from taking down the whole application. + == MicroProfile Fault Tolerance The feature:mpFaultTolerance[display=MicroProfile Fault Tolerance] feature defines a standard API to implement a set of fault tolerance policies. The policies that you implement in your code guide how long requests run, when they retry after an error, and what they do to recover when certain requests fail. MicroProfile Fault Tolerance makes it easy to build resilient microservices that provide reliable function, even when errors occur. +When you enable both feature:mpFaultTolerance-4.1[display=MicroProfile Fault Tolerance 4.1] and feature:mpTelemetry-2.0[display=MicroProfile Telemetry 2.0], fault tolerance metrics are automatically collected and exported to the configured OpenTelemetry metrics exporter. For more information, see xref:microprofile-telemetry.adoc[Collect logs, metrics, and traces with OpenTelemetry] and xref:mptelemetry-metrics-list.adoc[MicroProfile Telemetry metrics reference list]. + MicroProfile Fault Tolerance supports the following policies: - <<#timeout,Timeouts>> @@ -210,5 +213,7 @@ Ready to start building more resilient microservices with MicroProfile Fault Tol * To learn how to use the Circuit Breaker and Fallback policies to prevent repeated failed calls to a service, see link:/guides/circuit-breaker.html[Preventing repeated failed calls to microservices]. == See also + +- xref:reference:diff/mp-61-70-diff.adoc#ft[Differences between MicroProfile Fault Tolerance 4.1 and 4.0] +- - xref:reference:diff/mp-33-40-diff.adoc#ft[Differences between MicroProfile Fault Tolerance 3.0 and 2.1] - xref:reference:diff/mp-22-30-diff.adoc#ft[Differences between MicroProfile Fault Tolerance 2.0 and 1.1] -- xref:reference:diff/mp-33-40-diff.adoc#ft[Differences between MicroProfile Fault Tolerance 3.0 and 2.1] diff --git a/modules/ROOT/pages/telemetry-trace.adoc b/modules/ROOT/pages/telemetry-trace.adoc index 456f67f8e..e6a806c52 100644 --- a/modules/ROOT/pages/telemetry-trace.adoc +++ b/modules/ROOT/pages/telemetry-trace.adoc @@ -30,7 +30,7 @@ In Open Liberty version 23.0.0.11 and later, spans are automatically generated f 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.39.0/io/opentelemetry/api/trace/package-summary.html[OpenTelemetry API]. -However, before you manually instrument your code, you must make 3rd party APIs visible in your runtime environment by editing your runtime configuration. You must also add the OpenTelemetry API and annotations as a dependency on your build path. For more information, see link:/docs/latest/reference/feature/mpTelemetry-2.0.html#dev[Customize your application telemetry with the OpenTelemetry API]. +However, before you manually instrument your code, you must make 3rd party APIs visible in your runtime environment by editing your runtime configuration. For more information, see link:/docs/latest/reference/feature/mpTelemetry-2.0.html#dev[Customize your application telemetry with the OpenTelemetry API]. After you complete those prerequisites, you're ready to instrument your code. The following examples show configuration options with the OpenTelemetry API. diff --git a/modules/reference/pages/feature/mpTelemetry-2.0/description.adoc b/modules/reference/pages/feature/mpTelemetry-2.0/description.adoc new file mode 100644 index 000000000..ceb7042f4 --- /dev/null +++ b/modules/reference/pages/feature/mpTelemetry-2.0/description.adoc @@ -0,0 +1 @@ +MicroProfile Telemetry 2.0 is compatible with multiple versions of the feature:microprofile[display=MicroProfile umbrella feature]. It is automatically enabled when you enable `microprofile-6.1` or `microprofile-7.0`. However, it also works with `microprofile-5.0`, `microprofile-4.1`, or `microprofile-1.4` if you separately enable it alongside any of those features. diff --git a/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc b/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc index 8d0df4d78..b59b3b4af 100644 --- a/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc +++ b/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc @@ -15,7 +15,7 @@ When you enable the MicroProfile Telemetry feature and set this property, your s [#logs] === Collect logs from a specified source -To enable the MicroProfile Telemetry feature to collect logs from different sources in the Open Liberty runtime environment, configure the `source` attribute for the `mpTelemetry` element with a comma-separated list of comma-separated log sources. +To enable the MicroProfile Telemetry feature to collect logs from different sources in the Open Liberty runtime environment, configure the `source` attribute for the `mpTelemetry` element with a comma-separated list of log sources. [source,xml] ---- @@ -31,11 +31,9 @@ To enable the MicroProfile Telemetry feature to collect logs from different sour [#dev] === Customize your application telemetry with the OpenTelemetry API -Although OpenTelemetry automatically collects a default set of logs, metrics, and traces, if you need to xref:ROOT:telemetry-trace.adoc[manually instrument your code to collect traces] or xref:ROOT:custom-mptelemetry-metrics.adoc[define custom metrics], you must make the OpenTelemetry API and annotations available in your development environment. +Although OpenTelemetry automatically collects a default set of logs, metrics, and traces, if you need to xref:ROOT:telemetry-trace.adoc[manually instrument your code to collect traces] or xref:ROOT:custom-mptelemetry-metrics.adoc[define custom metrics], you must make the OpenTelemetry API visible in your development environment. -Complete the following prerequisites before you configure custom OpenTelemetry traces or metrics in your application code: - -* xref:ROOT:class-loader-library-config.adoc#3rd-party[Enable third-party APIs] for your application by adding the following code in your `server.xml` file: +xref:ROOT: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] ---- @@ -43,23 +41,3 @@ Complete the following prerequisites before you configure custom OpenTelemetry t ---- - -* 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] ----- - - io.opentelemetry - opentelemetry-api - 1.39.0 - provided - - - io.opentelemetry.instrumentation - opentelemetry-instrumentation-annotations - 1.39.0-alpha - provided - ----- - -Once you complete these prerequisites, you can use the OpenTelemetry API and annotations in your development environment to configure custom application telemetry. From 7ce7b0f547bc234f739ebddf752bb9982921a944 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Tue, 26 Nov 2024 15:50:27 -0500 Subject: [PATCH 69/81] Update documentation-openapi.adoc --- modules/ROOT/pages/documentation-openapi.adoc | 149 ++++++++++++++++-- 1 file changed, 137 insertions(+), 12 deletions(-) diff --git a/modules/ROOT/pages/documentation-openapi.adoc b/modules/ROOT/pages/documentation-openapi.adoc index b37c18b43..8d2ea5503 100644 --- a/modules/ROOT/pages/documentation-openapi.adoc +++ b/modules/ROOT/pages/documentation-openapi.adoc @@ -182,22 +182,147 @@ When multiple applications or an application with more than one web module are d [#conf-mm-supprt] === Including and excluding applications and modules from OpenAPI documentation -You can configure which applications or modules are included in your OpenAPI documentation either by setting elements in your `server.xml` file or by specifying MicroProfile Config properties. For most scenarios, `server.xml` configuration is preferred and MicroProfile Config properties are recommended only for compatibility with existing configurations that are already using these properties. +You can configure which applications or modules are included in your OpenAPI documentation either by <> or by <>. For most scenarios, `server.xml` configuration is preferred and MicroProfile Config properties are recommended only for compatibility with existing configurations that are already using these properties. -Configure application or module documentation by using the `server.xml` file:: -You can control the inclusion and exclusion of applications and modules in the OpenAPI documentation by configuring the `mpOpenAPI` configuration element in your `server.xml` file. -+ -In MicroProfile OpenAPI 4.0 and later, all applications and modules are included by default. To exclude certain applications or modules, see link:/docs/latest/reference/feature/mpOpenAPI-4.0.html#mm[MicroProfile 4.0: Configure OpenAPI documentation for a multi-module application]. -+ -In MicroProfile MicroProfile OpenAPI 2.0-3.1, only the first web module of the first deployed application is included in the structured documentation. To include or exclude applications or modules, see link:/docs/latest/reference/feature/mpOpenAPI-3.0.html#_configure_openapi_documentation_for_a_multi_module_application[MicroProfile 3.0: Configure OpenAPI documentation for a multi-module application] +[#server] +==== Configure application or module documentation by using the `server.xml` file +You can control the inclusion and exclusion of applications and modules in the OpenAPI documentation by configuring the following elements within the config:mpOpenAPI[] configuration element in your `server.xml` file: + +- `excludeModule` | `excludeApplication`: Specify module or application names, one per element, that are to be excluded from the OpenAPI document. Specify module names in the `{ApplicationName}/{ModuleName}` format. +- `includeModule` | `includeApplication`: Specify module or application names, one per element, that are to be included in the OpenAPI document. Specify module names in the `{ApplicationName}/{ModuleName}` format. The `all` special value includes all available applications. +- `info`: Specify an `info` section for the OpenAPI document. THis element is useful to override the default `info` section of merged OpenAPI documentation for multiple modules or applications. + +In feature:mpOpenAPI-4.0[display=MicroProfile OpenAPI 4.0] and later, all applications and modules are included by default. To exclude certain applications or modules, specify the `excludeModule` or `excludeApplication` element within the `mpOpenAPI` element. + +In the following example, the `sample_app` application consists of an EAR file containing five web modules. This configuration excludes modules 3 and 5 and provides a custom `info` section for the merged API documentation for modules 1,2, and 4: + +[source,xml] +---- + + sample_app/module-3 + sample_app/module-5 + + +---- + +In MicroProfile MicroProfile OpenAPI 2.0 - feature:mpOpenAPI-3.1[display=3.1], only the first web module of the first deployed application is included in the structured documentation. To include or exclude applications specify the corresponding elements within the `mpOpenAPI` element. + +In the following example, the `sample_app` application consists of an EAR file containing five web modules. By default, only `module-1` is included in the documentation. This configuration includes all modules, then selectively excludes modules 3 and 5. It also provides a custom `info` section for the merged API documentation for modules 1,2, and 4: + +[source,xml] +---- + + all + sample_app/module-3 + sample_app/module-5 + + +---- + +When you configure OpenAPI documentation in the `server.xml` file, the application name is determined by the value of the `name` attribute when the application is deployed in `server.xml` using `application`, `webApplication`, or `enterpriseApplication`. For example: + +[source,xml] +---- + +---- + +If the application is deployed in the `dropins` directory or if the `name` attribute is not specified, the name defaults to the archive filename without the file extension. + +For module names, the module name is specified in the web module's `web.xml` file. If no `web.xml` file exists or if it does not specify a name, the module name defaults to the file name without the file extension. + +[#mp-config] +==== Configure application or module documentation by using MicroProfile Config properties -Configure application or module documentation by using MicroProfile Config properties:: MicroProfile Config provides properties to manage which applications and modules are included in the generated OpenAPI documentation. This option is recommended only for compatibility with applications that already use MicroProfile Config to include or exclude modules or applications fro the API documentation. Newer configurations can instead use the `server.xml` file, as previously described. -+ -- You must configure properties by using sources that apply to the entire server, such as the `jvm.properties`, `server.env`, or the environment variables. -- When you configure support for multiple applications and multi-module environments by using MicroProfile Config, the application name is determined from the application's deployment descriptor (`application.xml` or `web.xml`). If the deployment descriptor is missing or does not specify a name, the application name defaults to the application archive file name without the file extension. Similarly, the module name is specified in the web module `web.xml` file. If the `web.xml` file does not exist or does not specify a name, the module name defaults to the file name without the file extension. + +WHen you configure the inclusion or exclusion of modules or applications with MicroProfile Config, the following limitations apply: + +- You must configure properties in a source that applies to the entire runtime, such as the `bootstrap.properties`, `jvm.properties`, or `server.env` files, or the `variable` element in the `server.xml` file. - Any configuration that is defined in the `server.xml` file to include or exclude modules and applications takes precedence over configuration that is set through MicroProfile Config. -+ + + +The following table lists xref:external-configuration.adoc[MicroProfile Config] properties that can be specified to configure which modules or applications are included in the generated OpenAPI documentation. + +.Configuration properties for multiple application and multi-module application support +[%header,cols="3,6,6a"] +|=== + +|Property name +|Description +|Valid values + +|`mp.openapi.extensions.liberty.merged.include` +|This property specifies which modules or applications are included in the generated OpenAPI documentation. +| +* `all` + +This value includes all modules and applications in a deployment. +* `first` + +This value includes only the first web module of the first application deployed. +* A comma-separated list of `_application_name_` or `_application_name_/_module_name_` includes the named applications and modules. + +|`mp.openapi.extensions.liberty.merged.exclude` +|This property overrides the `mp.openapi.extensions.liberty.merged.include` property to specify which applications or web modules are excluded from the generated OpenAPI documentation. +| +* `none` + +This value excludes no applications or web modules. +* A comma-separated list of `_application_name_` or `_application_name_/_module_name_` excludes the named applications and modules. + +|`mp.openapi.extensions.liberty.merged.info` +|This property sets the `info` section of the final Open API document. If it is set, the `info` section in the final OpenAPI document is replaced with the value of the property. This replacement is made after any merging is completed. +|The value must be https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#infoObject[a valid OpenAPI info section] in JSON format. + +|=== + + +When you configure support for multiple applications and multi-module environments by using MicroProfile Config, the application name is determined from the application's deployment descriptor (`application.xml` or `web.xml`). If the deployment descriptor is missing or does not specify a name, the application name defaults to the application archive file name without the file extension. Similarly, the module name is specified in the web module `web.xml` file. If the `web.xml` file does not exist or does not specify a name, the module name defaults to the file name without the file extension. + +In the following `jvm.properties` file example, an OpenAPI document is configured for the `sample_app` application, which consists of an EAR file with five web modules. + +[source,properties] +---- +mp.openapi.extensions.liberty.merged.include=all +mp.openapi.extensions.liberty.merged.exclude=sample_app/module-3,sample_app/module-5 +mp.openapi.extensions.liberty.merged.info= +{ + "title": "A multi-module sample application", + "description": "This is a sample application.", + "termsOfService": "http://example.com/sample_app/terms", + "contact": { + "name": "API Support", + "url": "http://www.example.com/sample_app/support", + "email": "sample_app_support@example.com" + }, + "license": { + "name": "License 2.0", + "url": "https://www.example.org/licenses/LICENSE-2.0.html" + }, + "version": "2.0.1" +} +---- + +* The `mp.openapi.extensions.liberty.merged.include` property specifies that all five modules are included in the final OpenAPI document. +* The `mp.openapi.extensions.liberty.merged.exclude` overrides the `mp.openapi.extensions.liberty.merged.include` property to exclude the `module-3` and `module-5` web modules. +* 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 the link:/docs/latest/reference/microprofile-config-properties.html#openapi[MicroProfile Config properties for MicroProfile OpenAPI]. From 2ba63f9a7fdbc78b532279f72055276c0b092718 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Tue, 26 Nov 2024 17:10:38 -0500 Subject: [PATCH 70/81] edits --- modules/ROOT/pages/observability.adoc | 8 ++++---- modules/ROOT/pages/telemetry-trace.adoc | 4 ++-- .../{mpTelemetry => mpTelemetry-1.0}/description.adoc | 2 -- .../reference/pages/feature/mpTelemetry-2.0/examples.adoc | 2 +- 4 files changed, 7 insertions(+), 9 deletions(-) rename modules/reference/pages/feature/{mpTelemetry => mpTelemetry-1.0}/description.adoc (65%) diff --git a/modules/ROOT/pages/observability.adoc b/modules/ROOT/pages/observability.adoc index f63eb1346..a9ca00358 100644 --- a/modules/ROOT/pages/observability.adoc +++ b/modules/ROOT/pages/observability.adoc @@ -15,7 +15,7 @@ When applications are observable, operations teams can identify and understand the root causes of bugs, bottlenecks, and other inefficiencies. Open Liberty provides a robust framework for developing observable applications and integrates with numerous third-party monitoring tools. -With MicroProfile Telemetry 2.0 and later, you can manage logs, metrics, and traces in a standardized way by using the OpenTelemetry protocol. For more information, see xref:microprofile-telemetry.adoc[OpenTelemetry]. +With MicroProfile Telemetry 2.0 and later, you can manage logs, metrics, and traces in a standardized way by using the OpenTelemetry protocol. For more information, see xref:microprofile-telemetry.adoc[Collect logs, metrics, and traces with OpenTelemetry]. The following topics provide information to help you develop observable applications with Open Liberty. @@ -35,14 +35,14 @@ xref:mptelemetry-logging.adoc[Write logs with MicroProfile Telemetry logging]:: You can use MicroProfile Telemetry to mange your logs, along with traces and metrics. When you enable the MicroProfile Telemetry feature version 2.0 or later, MicroProfile Telemetry automatically collects any logs that are sent to the `java.util.logging` API. //// +xref:health-check-microservices.adoc[Health checks for microservices]:: +A health check is a special REST API implementation that you can use to validate the status of a microservice and its dependencies. With MicroProfile Health, microservices can self-check their health and publish their overall status to a defined endpoint. + xref:microservice-observability-metrics.adoc[Microservice observability with MicroProfile metrics]:: 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 server and deployed applications. xref:micrometer-metrics.adoc[Choose your own monitoring tools with MicroProfile Metrics]:: The Open Liberty MicroProfile Metrics 5.0 feature uses embedded Micrometer metrics technology to transfer metric data to multiple third-party monitoring systems. Starting in MicroProfile Metrics 5.0, you can instrument your code in a standardized way to visualize metrics results in the monitoring system of your choice. -xref:health-check-microservices.adoc[Health checks for microservices]:: -A health check is a special REST API implementation that you can use to validate the status of a microservice and its dependencies. With MicroProfile Health, microservices can self-check their health and publish their overall status to a defined endpoint. - For hands-on tutorials on different observability configurations for Open Liberty, check out our link:/guides/#observability[Observability guides]. diff --git a/modules/ROOT/pages/telemetry-trace.adoc b/modules/ROOT/pages/telemetry-trace.adoc index e6a806c52..3d05346af 100644 --- a/modules/ROOT/pages/telemetry-trace.adoc +++ b/modules/ROOT/pages/telemetry-trace.adoc @@ -21,7 +21,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 that you need to do is configure runtime as described in xref:microprofile-telemetry.adoc[OpenTelemetry]. 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 that you need to do is configure runtime as described in xref:microprofile-telemetry.adoc[Collect logs, metrics, and traces with OpenTelemetry]. 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. @@ -32,7 +32,7 @@ Automatic instrumentation is available only for JAX-RS and Jakarta RESTful web s However, before you manually instrument your code, you must make 3rd party APIs visible in your runtime environment by editing your runtime configuration. For more information, see link:/docs/latest/reference/feature/mpTelemetry-2.0.html#dev[Customize your application telemetry with the OpenTelemetry API]. -After you complete those prerequisites, you're ready to instrument your code. The following examples show configuration options with the OpenTelemetry API. +The following examples show configuration options with the OpenTelemetry API. - Add extra information, such as the user ID, to the current span. Any information that you add to a span is visible when you look at the traces on your trace server. + diff --git a/modules/reference/pages/feature/mpTelemetry/description.adoc b/modules/reference/pages/feature/mpTelemetry-1.0/description.adoc similarity index 65% rename from modules/reference/pages/feature/mpTelemetry/description.adoc rename to modules/reference/pages/feature/mpTelemetry-1.0/description.adoc index fcdc56efb..6a45a48c2 100644 --- a/modules/reference/pages/feature/mpTelemetry/description.adoc +++ b/modules/reference/pages/feature/mpTelemetry-1.0/description.adoc @@ -1,3 +1 @@ For information about migrating from MicroProfile Open Tracing to MicroProfile Open Telemetry, see xref:diff/mp-50-60-diff.adoc#telemetry[Differences between MicroProfile Telemetry 1.0 and MicroProfile OpenTracing 3.0]. - -For information about configuring MicroProfile Telemetry, see xref:ROOT:microprofile-telemetry.adoc[OpenTelemetry]. diff --git a/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc b/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc index b59b3b4af..7098549d3 100644 --- a/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc +++ b/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc @@ -34,7 +34,7 @@ To enable the MicroProfile Telemetry feature to collect logs from different sour Although OpenTelemetry automatically collects a default set of logs, metrics, and traces, if you need to xref:ROOT:telemetry-trace.adoc[manually instrument your code to collect traces] or xref:ROOT:custom-mptelemetry-metrics.adoc[define custom metrics], you must make the OpenTelemetry API visible in your development environment. xref:ROOT: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] ---- From 9525687ad146696badfac5e1e3dc1d759ca23165 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Wed, 27 Nov 2024 16:08:47 +0530 Subject: [PATCH 71/81] 7610-MicroProfile 7.0 ID-010 7610-MicroProfile 7.0 ID-010 #7610 --- .../reference/pages/diff/mp-61-70-diff.adoc | 57 ++++++++++--------- 1 file changed, 30 insertions(+), 27 deletions(-) diff --git a/modules/reference/pages/diff/mp-61-70-diff.adoc b/modules/reference/pages/diff/mp-61-70-diff.adoc index b14a4d343..eb751e799 100644 --- a/modules/reference/pages/diff/mp-61-70-diff.adoc +++ b/modules/reference/pages/diff/mp-61-70-diff.adoc @@ -20,15 +20,18 @@ MicroProfile 7.0 is a major release. It introduces updated MicroProfile specifications, including MicroProfile Telemetry 2.0, MicroProfile Rest Client 4.0, MicroProfile OpenAPI 4.0, and MicroProfile Fault Tolerance 4.1. -This release includes several significant changes. -- MicroProfile Metrics 5.1 has been removed from the MicroProfile umbrella release and is now a stand-alone specification. -- MicroProfile Telemetry 2.0 marks a major release by incorporating support for Logs and Metrics in addition to Tracing, broadening its observability capabilities. -- MicroProfile Rest Client 4.0 has adopted Jakarta Restful Web Services 3.1 to support multipart form data, while MicroProfile OpenAPI 4.0 has aligned with the OpenAPI 3.1 standards to help ensure compliance with the latest specifications. -- MicroProfile 7.0 is designed to work with Jakarta EE 10 as the minimum version. +This release introduces several important changes: + +- MicroProfile Metrics 5.1 is no longer part of the MicroProfile umbrella release and now stands as an independent specification. +- MicroProfile Telemetry 2.0 expands observability by adding support for Logs and Metrics. +- MicroProfile Rest Client 4.0 uses Jakarta Restful Web Services 3.1 to support multipart form data. +- MicroProfile OpenAPI 4.0 complies with the OpenAPI 3.1 standards which help ensure compliance with the latest specifications. +- MicroProfile 7.0 requires Jakarta EE 10 as the minimum version. + If you are updating your application from using MicroProfile 6.1 features to using link:https://github.com/eclipse/microprofile/releases/tag/7.0[MicroProfile 7.0] features, the changes in API behavior might require you to update your application code. The following sections provide details about migrating your applications from MicroProfile 6.1 to MicroProfile 7.0: -- <<#mp, Differences between MicroProfile 7.0 and 6.1>> +- <<#mp, Differences between MicroProfile 7.0 and 6.1 umbrella features>> - <<#rc, Differences between MicroProfile REST Client 4.0 and 3.0>> - <<#openapi, Differences between MicroProfile OpenAPI 4.0 and 3.1>> - <<#ft, Differences between Fault Tolerance 4.1 and 4.0>> @@ -36,18 +39,18 @@ If you are updating your application from using MicroProfile 6.1 features to usi [#mp] -== Differences between MicroProfile 7.0 and 6.1 +== Differences between MicroProfile 7.0 and 6.1 umbrella features link:https://download.eclipse.org/microprofile/microprofile-7.0/microprofile-spec-7.0.html[MicroProfile 7.0] is a major release that includes backward-incompatible changes. One significant update is the replacement of MicroProfile Metrics with MicroProfile Telemetry 2.0, which offers Metrics capabilities in addition to support for logs and tracing. -If you are using MicroProfile Metrics from MicroProfile 6.1, you need to add the following in your `server.xml` file when upgrading to MicroProfile 7.0. +If you are using MicroProfile Metrics from MicroProfile 6.1, include the following configuration in your `server.xml` file when you upgrade to MicroProfile 7.0: [source,xml] ---- mpMetrics-5.1 ---- -If your application does not use any APIs from MicroProfile Metrics, your application has the Metrics from MicroProfile Telemetry 2.0, and no migration effort is required. +If your application does not use any APIs from MicroProfile Metrics, no migration effort is needed. You can instead use feature:mpTelemetry-2.0[display=MicroProfile Telemetry metrics]. In Open Liberty, the feature:jakartaee-10.0[display=Jakarta EE 10 Core Profile] features are automatically included with the `microProfile-7.0` feature to provide a smoother upgrade experience from `microProfile-6.1`. @@ -56,7 +59,7 @@ In Open Liberty, the feature:jakartaee-10.0[display=Jakarta EE 10 Core Profile] [#rc] == Differences between MicroProfile REST Client 4.0 and 3.0 -With the release of the feature:mpRestClient-4.0[display=MicroProfile REST Client 4.0] feature, the underlying MicroProfile REST Client implementation for Open Liberty is now compatible with Jakarta EE 10 and is designed to tolerate Jakarta EE 11. +With the release of the feature:mpRestClient-4.0[display=MicroProfile REST Client 4.0], the underlying MicroProfile REST Client implementation for Open Liberty is now compatible with Jakarta EE 10 and is designed to tolerate Jakarta EE 11. The following sections provide details about changes in behavior between the feature:mpRestClient-3.0[display=MicroProfile Rest Client 3.0] and feature:mpRestClient-4.0[display=MicroProfile Rest Client 4.0] features. @@ -75,7 +78,7 @@ RestClientBuilder.newBuilder() === Set HTTP Headers on a per instance basis -You can now set HTTP headers for each Client instance using the new `RestClientBuilder.header(String, Object)` method. +You can now set HTTP headers for each Client instance by using the new `RestClientBuilder.header(String, Object)` method. [source,java] ---- @@ -97,19 +100,18 @@ Information and example code are added to the xref:ROOT:send-receive-multipart-j The OpenAPI document is now generated in OpenAPI 3.1 format by default, an update from OpenAPI 3.0 in `mpOpenAPI-3.1`. -OpenAPI 3.1 introduces the ability to capture more detail, including the use of the full JSON Schema (2020-12 draft) for describing data objects. It also adds support for documenting webhooks and for indicating that an API uses mutual TLS for authentication. For more information see the link:https://github.com/OAI/OpenAPI-Specification/releases/tag/3.1.0[OpenAPI 3.1.0 release notes]. +OpenAPI 3.1 introduces the ability to capture more detail, including the use of the full JSON Schema (2020-12 draft) for describing data objects. It also adds support for documenting webhooks and for indicating that an API uses mutual TLS for authentication. For more information, see the link:https://github.com/OAI/OpenAPI-Specification/releases/tag/3.1.0[OpenAPI 3.1.0 release notes]. -New APIs and annotation parameters are added to MicroProfile OpenAPI 4.0, to allow users to take advantage of the new OpenAPI 3.1 features. For more information on new APIs, see the link:https://download.eclipse.org/microprofile/microprofile-open-api-4.0.2/microprofile-openapi-spec-4.0.2.html#release_notes_40[MicroProfile OpenAPI 4.0 release notes]. +New APIs and annotation parameters are added to MicroProfile OpenAPI 4.0 to allow users to take advantage of the new OpenAPI 3.1 features. For more information on the new APIs, see the link:https://download.eclipse.org/microprofile/microprofile-open-api-4.0.2/microprofile-openapi-spec-4.0.2.html#release_notes_40[MicroProfile OpenAPI 4.0 release notes]. -If you use the new APIs and annotations corresponding to OpenAPI 3.1 features, the additional information they provide is not be included when the feature is configured to generate OpenAPI 3.0 documents. - -However, these changes mean that OpenAPI 3.1 is not fully backward compatible with OpenAPI 3.0, and existing tools may not work with it. To maintain compatibility with existing tools, you can configure `mpOpenAPI-4.0` to produce OpenAPI 3.0 documentation. For more information, see link:/docs/latest/reference/feature/mpOpenAPI-4.0.html#apiversion[Selecting the OpenAPI specification version]. +If you use the new APIs and annotations that correspond to OpenAPI 3.1 features, the additional information they provide is not included if you configure the MicroProfile OpenAPI 4.0 feature to generate OpenAPI 3.0 documents. +However, these changes mean that OpenAPI 3.1 is not fully compatible with earlier versions, such as OpenAPI 3.0, and existing tools might not work with it. To maintain compatibility with existing tools, you can configure `mpOpenAPI-4.0` to produce OpenAPI 3.0 documentation. For more information, see link:/docs/latest/reference/feature/mpOpenAPI-4.0.html#apiversion[Selecting the OpenAPI specification version]. === All deployed applications are documented by default -In this update, all deployed applications are included in the OpenAPI documentation by default. In previous versions of mpOpenAPI, only the first module of the first deployed application was documented by default. +In this update, all deployed applications are included in the OpenAPI documentation by default. In previous versions of MicroProfile OpenAPI, only the first module of the first deployed application was documented by default. -You can control which applications are included in the documentation using the following configuration: +You can control which applications are included in the documentation by using the following configuration: [source,xml] ---- @@ -126,11 +128,9 @@ For more information on this configuration, see feature:mpOpenAPI-4.0[display=Mi [#ft] == Differences between Fault Tolerance 4.1 and 4.0 -MicroProfile Fault Tolerance 4.1, an update to version 4.0, introduces integration with MicroProfile Telemetry 2.0. This allows Fault Tolerance to export metrics directly to MicroProfile Telemetry. The existing integration with `mpMetrics` remains unchanged. - -For more information, see the link:/docs/latest/reference/feature/mpFaultTolerance-4.1.html#_enabling_this_feature[MicroProfile Fault Tolerance] feature. +feature:mpFaultTolerance-4.1[display=MicroProfile Fault Tolerance 4.1], an update to version 4.0, introduces integration with MicroProfile Telemetry 2.0. This feature allows Fault Tolerance to export metrics directly to MicroProfile Telemetry. The existing integration with `mpMetrics` remains unchanged. -For integration between feature:mpFaultTolerance-4.1[display=MicroProfile Fault Tolerance] and feature:mpTelemetry-2.0[display=MicroProfile Telemetry], you must enable both feature:mpFaultTolerance-4.1[display=MicroProfile Fault Tolerance 4.1] and feature:mpTelemetry-2.0[display=MicroProfile Telemetry 2.0] simultaneously. When both features are enabled, feature:mpFaultTolerance-4.1[display=MicroProfile Fault Tolerance] will automatically export metrics to feature:mpTelemetry-2.0[display=MicroProfile Telemetry]. +For integration between feature:mpFaultTolerance-4.1[display=MicroProfile Fault Tolerance] and feature:mpTelemetry-2.0[display=MicroProfile Telemetry], you must enable both feature:mpFaultTolerance-4.1[display=MicroProfile Fault Tolerance 4.1] and feature:mpTelemetry-2.0[display=MicroProfile Telemetry 2.0] simultaneously. When both features are enabled, feature:mpFaultTolerance-4.1[display=MicroProfile Fault Tolerance] can automatically export metrics to feature:mpTelemetry-2.0[display=MicroProfile Telemetry]. [source,xml] ---- @@ -140,7 +140,9 @@ For integration between feature:mpFaultTolerance-4.1[display=MicroProfile Fault For more information on configuring feature:mpTelemetry-2.0[display=MicroProfile Telemetry] to export metrics, see xref:ROOT:microprofile-telemetry.adoc#global[Collecting and exporting logs, metrics, and traces with OpenTelemetry]. -If feature:mpFaultTolerance-4.1[display=MicroProfile Fault Tolerance] is enabled alongside both feature:mpTelemetry-2.0[display=MicroProfile Telemetry] and feature:mpMetrics-5.1[display=MicroProfile Metrics], Fault Tolerance will export metrics to both MicroProfile Telemetry and MicroProfile Metrics. +If feature:mpFaultTolerance-4.1[display=MicroProfile Fault Tolerance] is enabled alongside both feature:mpTelemetry-2.0[display=MicroProfile Telemetry] and feature:mpMetrics-5.1[display=MicroProfile Metrics], Fault Tolerance can export metrics to both MicroProfile Telemetry and MicroProfile Metrics. + +The following table provides a comparison of the metric types in MicroProfile Metrics and MicroProfile Telemetry. It highlights the differences in data representation and metric types across both specifications. .Comparison of Metric Types between MicroProfile Metrics and MicroProfile Telemetry [cols="1,1,1", options="header"] @@ -189,6 +191,9 @@ If feature:mpFaultTolerance-4.1[display=MicroProfile Fault Tolerance] is enabled |=== + +The following table compares histogram metrics in MicroProfile Metrics and MicroProfile Telemetry. It highlights the differences in metric types, units, and bucket boundaries. These details help you to understand the changes that are needed when you move between the two frameworks. + .Comparison between Histogram Metrics in mpMetrics and mpTelemetry [cols="1,1,1,1,1", options="header"] |=== @@ -217,7 +222,7 @@ If feature:mpFaultTolerance-4.1[display=MicroProfile Fault Tolerance] is enabled [#tm] == Differences between MicroProfile Telemetry 2.0 and 1.1 -feature:mpTelemetry-2.0[display=MicroProfile Telemetry 2.0] is an update to MicroProfile Telemetry 1.1, incorporating the latest OpenTelemetry SDK (version 1.39). Previously, only traces were collected and exported. The updated feature now includes the ability to collect and export metrics and logs. Specifically, the following enhancements are provided: +feature:mpTelemetry-2.0[display=MicroProfile Telemetry 2.0] is an enhancement to MicroProfile Telemetry 1.1, incorporating OpenTelemetry SDK version 1.39. In the earlier version, only traces were be collected and exported. The updated feature now includes the ability to collect and export metrics and logs. Specifically, the following enhancements are provided: * Access to the OpenTelemetry Metrics API * HTTP metrics @@ -225,9 +230,7 @@ feature:mpTelemetry-2.0[display=MicroProfile Telemetry 2.0] is an update to Micr * Runtime-level logs * Application logs -For more information, see the link:/docs/latest/reference/feature/mpTelemetry-2.0.html#_enabling_this_feature[MicroProfile Telemetry] feature. - -MicroProfile Telemetry 2.0 provides runtime-level telemetry. To enable this, you must add the MicroProfile Telemetry feature to your `server.xml` file and enable the OpenTelemetry SDK by using system properties or environment variables. Once enabled, you can configure how MicroProfile Telemetry collects and exports traces, metrics, and logs. This is different from MicroProfile Telemetry 1.1, which provided full functionality by using only MicroProfile Config for configuration. +MicroProfile Telemetry 2.0 provides runtime-level telemetry. To enable this feature, add the MicroProfile Telemetry feature to your `server.xml` file and enable the OpenTelemetry SDK by using system properties or environment variables. Once the feature is enabled, you can configure how MicroProfile Telemetry collects and exports traces, metrics, and logs. This function differs from MicroProfile Telemetry 1.1, which provided full support through MicroProfile Config for configuration. If you do not use system properties or environment variables for configuration, runtime-level metrics and logs cannot be collected. Using other available MicroProfile Config properties cannot enable the collection of these metrics and logs. From 163b83758bd4a01975a48ef8ef1209298038bfc2 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Wed, 27 Nov 2024 16:28:28 +0530 Subject: [PATCH 72/81] 7654-Documentation-MicroProfile-OpenAPI-4.0-012 7654-Documentation-MicroProfile-OpenAPI-4.0-012 #7654 --- modules/ROOT/pages/documentation-openapi.adoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/modules/ROOT/pages/documentation-openapi.adoc b/modules/ROOT/pages/documentation-openapi.adoc index 8d2ea5503..cd85a3dc9 100644 --- a/modules/ROOT/pages/documentation-openapi.adoc +++ b/modules/ROOT/pages/documentation-openapi.adoc @@ -182,11 +182,11 @@ When multiple applications or an application with more than one web module are d [#conf-mm-supprt] === Including and excluding applications and modules from OpenAPI documentation -You can configure which applications or modules are included in your OpenAPI documentation either by <> or by <>. For most scenarios, `server.xml` configuration is preferred and MicroProfile Config properties are recommended only for compatibility with existing configurations that are already using these properties. +You can configure which applications or modules are included in your OpenAPI documentation either by <<#server, setting elements in your `server.xml` file>> or by <<#mp-config, specifying MicroProfile Config properties>>. For most scenarios, `server.xml` configuration is preferred and MicroProfile Config properties are recommended only for compatibility with existing configurations that are already using these properties. [#server] ==== Configure application or module documentation by using the `server.xml` file -You can control the inclusion and exclusion of applications and modules in the OpenAPI documentation by configuring the following elements within the config:mpOpenAPI[] configuration element in your `server.xml` file: +You can control the inclusion and exclusion of applications and modules in the OpenAPI documentation by configuring the following elements within the config:mpOpenAPI[] configuration element in your `server.xml` file: - `excludeModule` | `excludeApplication`: Specify module or application names, one per element, that are to be excluded from the OpenAPI document. Specify module names in the `{ApplicationName}/{ModuleName}` format. - `includeModule` | `includeApplication`: Specify module or application names, one per element, that are to be included in the OpenAPI document. Specify module names in the `{ApplicationName}/{ModuleName}` format. The `all` special value includes all available applications. @@ -194,7 +194,7 @@ You can control the inclusion and exclusion of applications and modules in the O In feature:mpOpenAPI-4.0[display=MicroProfile OpenAPI 4.0] and later, all applications and modules are included by default. To exclude certain applications or modules, specify the `excludeModule` or `excludeApplication` element within the `mpOpenAPI` element. -In the following example, the `sample_app` application consists of an EAR file containing five web modules. This configuration excludes modules 3 and 5 and provides a custom `info` section for the merged API documentation for modules 1,2, and 4: +In the following example, the `sample_app` application consists of an EAR file containing five web modules. This configuration excludes modules 3 and 5 and provides a custom `info` section for the merged API documentation for modules 1, 2, and 4: [source,xml] ---- @@ -216,7 +216,7 @@ In the following example, the `sample_app` application consists of an EAR file c In MicroProfile MicroProfile OpenAPI 2.0 - feature:mpOpenAPI-3.1[display=3.1], only the first web module of the first deployed application is included in the structured documentation. To include or exclude applications specify the corresponding elements within the `mpOpenAPI` element. -In the following example, the `sample_app` application consists of an EAR file containing five web modules. By default, only `module-1` is included in the documentation. This configuration includes all modules, then selectively excludes modules 3 and 5. It also provides a custom `info` section for the merged API documentation for modules 1,2, and 4: +In the following example, the `sample_app` application consists of an EAR file containing five web modules. By default, only `module-1` is included in the documentation. This configuration includes all modules, then selectively excludes modules 3 and 5. It also provides a custom `info` section for the merged API documentation for modules 1, 2, and 4: [source,xml] ---- @@ -253,7 +253,7 @@ For module names, the module name is specified in the web module's `web.xml` fil MicroProfile Config provides properties to manage which applications and modules are included in the generated OpenAPI documentation. This option is recommended only for compatibility with applications that already use MicroProfile Config to include or exclude modules or applications fro the API documentation. Newer configurations can instead use the `server.xml` file, as previously described. -WHen you configure the inclusion or exclusion of modules or applications with MicroProfile Config, the following limitations apply: +When you configure the inclusion or exclusion of modules or applications with MicroProfile Config, the following limitations apply: - You must configure properties in a source that applies to the entire runtime, such as the `bootstrap.properties`, `jvm.properties`, or `server.env` files, or the `variable` element in the `server.xml` file. - Any configuration that is defined in the `server.xml` file to include or exclude modules and applications takes precedence over configuration that is set through MicroProfile Config. @@ -292,7 +292,7 @@ This value excludes no applications or web modules. |=== -When you configure support for multiple applications and multi-module environments by using MicroProfile Config, the application name is determined from the application's deployment descriptor (`application.xml` or `web.xml`). If the deployment descriptor is missing or does not specify a name, the application name defaults to the application archive file name without the file extension. Similarly, the module name is specified in the web module `web.xml` file. If the `web.xml` file does not exist or does not specify a name, the module name defaults to the file name without the file extension. +When you configure support for multiple applications and multi-module environments by using MicroProfile Config, the application name is determined from the application's deployment descriptor (`application.xml` or `web.xml`). If the deployment descriptor is missing or does not specify a name, the application name defaults to the application archive file name without the file extension. Similarly, the module name is specified in the web module `web.xml` file. If the `web.xml` file does not exist or does not specify a name, the module name defaults to the file name without the file extension. In the following `jvm.properties` file example, an OpenAPI document is configured for the `sample_app` application, which consists of an EAR file with five web modules. From f81e6b3dcac680f7a2872019f85de41ca9bcd4bf Mon Sep 17 00:00:00 2001 From: David Mueller Date: Wed, 27 Nov 2024 08:24:26 -0500 Subject: [PATCH 73/81] minor edits --- modules/ROOT/pages/documentation-openapi.adoc | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/documentation-openapi.adoc b/modules/ROOT/pages/documentation-openapi.adoc index cd85a3dc9..d08fe0b6f 100644 --- a/modules/ROOT/pages/documentation-openapi.adoc +++ b/modules/ROOT/pages/documentation-openapi.adoc @@ -190,7 +190,7 @@ You can control the inclusion and exclusion of applications and modules in the O - `excludeModule` | `excludeApplication`: Specify module or application names, one per element, that are to be excluded from the OpenAPI document. Specify module names in the `{ApplicationName}/{ModuleName}` format. - `includeModule` | `includeApplication`: Specify module or application names, one per element, that are to be included in the OpenAPI document. Specify module names in the `{ApplicationName}/{ModuleName}` format. The `all` special value includes all available applications. -- `info`: Specify an `info` section for the OpenAPI document. THis element is useful to override the default `info` section of merged OpenAPI documentation for multiple modules or applications. +- `info`: Specify an `info` section for the OpenAPI document. This element is useful to override the default `info` section of merged OpenAPI documentation for multiple modules or applications. In feature:mpOpenAPI-4.0[display=MicroProfile OpenAPI 4.0] and later, all applications and modules are included by default. To exclude certain applications or modules, specify the `excludeModule` or `excludeApplication` element within the `mpOpenAPI` element. @@ -214,7 +214,7 @@ In the following example, the `sample_app` application consists of an EAR file c ---- -In MicroProfile MicroProfile OpenAPI 2.0 - feature:mpOpenAPI-3.1[display=3.1], only the first web module of the first deployed application is included in the structured documentation. To include or exclude applications specify the corresponding elements within the `mpOpenAPI` element. +In MicroProfile MicroProfile OpenAPI 2.0 - feature:mpOpenAPI-3.1[display=3.1], only the first web module of the first deployed application is included in the structured documentation. To include or exclude applications, specify the corresponding elements within the `mpOpenAPI` element. In the following example, the `sample_app` application consists of an EAR file containing five web modules. By default, only `module-1` is included in the documentation. This configuration includes all modules, then selectively excludes modules 3 and 5. It also provides a custom `info` section for the merged API documentation for modules 1, 2, and 4: @@ -292,8 +292,6 @@ This value excludes no applications or web modules. |=== -When you configure support for multiple applications and multi-module environments by using MicroProfile Config, the application name is determined from the application's deployment descriptor (`application.xml` or `web.xml`). If the deployment descriptor is missing or does not specify a name, the application name defaults to the application archive file name without the file extension. Similarly, the module name is specified in the web module `web.xml` file. If the `web.xml` file does not exist or does not specify a name, the module name defaults to the file name without the file extension. - In the following `jvm.properties` file example, an OpenAPI document is configured for the `sample_app` application, which consists of an EAR file with five web modules. [source,properties] @@ -322,6 +320,7 @@ mp.openapi.extensions.liberty.merged.info= * The `mp.openapi.extensions.liberty.merged.exclude` overrides the `mp.openapi.extensions.liberty.merged.include` property to exclude the `module-3` and `module-5` web modules. * 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. +When you configure support for multiple applications and multi-module environments by using MicroProfile Config, the application name is determined from the application's deployment descriptor (`application.xml` or `web.xml`). If the deployment descriptor is missing or does not specify a name, the application name defaults to the application archive file name without the file extension. Similarly, the module name is specified in the web module `web.xml` file. If the `web.xml` file does not exist or does not specify a name, the module name defaults to the file name without the file extension. For more information, see the link:/docs/latest/reference/microprofile-config-properties.html#openapi[MicroProfile Config properties for MicroProfile OpenAPI]. From 948f664dc60ed69b0f22af2baefb5fe77ef38c1c Mon Sep 17 00:00:00 2001 From: David Mueller Date: Wed, 27 Nov 2024 08:52:28 -0500 Subject: [PATCH 74/81] Update microprofile-telemetry.adoc --- modules/ROOT/pages/microprofile-telemetry.adoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/microprofile-telemetry.adoc b/modules/ROOT/pages/microprofile-telemetry.adoc index 27921a89d..a39e4a237 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -14,10 +14,12 @@ The OpenTelemetry project is a collection of open source, vendor-independent resources for collecting and managing application telemetry data. With Open Liberty and MicroProfile Telemetry 2.0 and later, you can manage logs, metrics, and traces in a standardized way by using the OpenTelemetry protocol. -OpenTelemetry provides a link:https://opentelemetry.io/docs/collector/[collector] component that can receive telemetry data from your runtime and applications and export it to backend services of your choice for monitoring and analysis. By default, all OpenTelemetry data is exported by using the OpenTelemetry Protocol (OTLP). OTLP defines the encoding of telemetry data and the protocol that is used to exchange data between a client and server. Many backend services accept OTLP data without requiring conversion, but OpenTelemetry also provides a collection of service-specific exporters for popular open source and commercial services, such as link:https://zipkin.io/[Zipkin] and link:https://prometheus.io/[Prometheus]. You can configure exporter settings by specifying system properties or environment variables. +OpenTelemetry provides a link:https://opentelemetry.io/docs/collector/[collector] component that can receive telemetry data from your runtime and applications and export it to backend services of your choice for monitoring and analysis. By default, all OpenTelemetry data is exported by using the OpenTelemetry Protocol (OTLP). OTLP defines the encoding of telemetry data and the protocol that is used to exchange data between a client and server. Many backend services accept OTLP data without requiring conversion, but OpenTelemetry also provides a collection of service-specific exporters for popular open source and commercial services, such as link:https://grafana.com/blog/2024/03/13/an-opentelemetry-backend-in-a-docker-image-introducing-grafana/otel-lgtm/[Grafana] and link:https://prometheus.io/[Prometheus]. You can configure exporter settings by specifying system properties or environment variables. OpenTelemetry is implemented in Open Liberty through the feature:mpTelemetry[display=MicroProfile Telemetry] feature. When you enable the MicroProfile Telemetry feature 2.0 or later and specify the required configuration property, Open Liberty automatically collects and exports logs, traces, and metrics at the application or runtime level. For many common application scenarios, no changes are needed in your application code to collect this data. MicroProfile Telemetry 1.1 and earlier enables only the collection of traces and only at the application level. + + [#global] == Collecting and exporting logs, metrics, and traces with OpenTelemetry From 1837a6bc7a95bbd13f23a9ed579ce329d2d63fa1 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Wed, 27 Nov 2024 09:13:27 -0500 Subject: [PATCH 75/81] add 7.0 jdoc frame --- .../pages/javadoc/microprofile-7.0-javadoc.adoc | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 modules/reference/pages/javadoc/microprofile-7.0-javadoc.adoc diff --git a/modules/reference/pages/javadoc/microprofile-7.0-javadoc.adoc b/modules/reference/pages/javadoc/microprofile-7.0-javadoc.adoc new file mode 100644 index 000000000..11877b75f --- /dev/null +++ b/modules/reference/pages/javadoc/microprofile-7.0-javadoc.adoc @@ -0,0 +1,15 @@ +// 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-layout: javadoc += MicroProfile 7.0 + +++++ + +++++ From e56e3b0c0b65b0fea48141b5391d24cb5766411c Mon Sep 17 00:00:00 2001 From: David Mueller Date: Wed, 27 Nov 2024 10:01:07 -0500 Subject: [PATCH 76/81] update nav for 24.0.0.12 #7610 #7712 #7655 --- modules/ROOT/nav.adoc | 11 ++++++----- modules/reference/nav.adoc | 2 ++ 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 9cef9f6c7..73f5ebe2b 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -49,12 +49,12 @@ ** xref:distributed-session-caching.adoc[Distributed session caching] ** xref:configuring-infinispan-support.adoc[Configuring Infinispan as a JCache provider] * xref:observability.adoc[Observability] - ** xref:prepare-mptelemetry.adoc[Prepare your development environment for MicroProfile Telemetry] +// ** xref:prepare-mptelemetry.adoc[Prepare your development environment for MicroProfile Telemetry] ** xref:custom-mptelemetry-metrics.adoc[Define custom MicroProfile Telemetry metrics] ** xref:telemetry-trace.adoc[Code instrumentation for MicroProfile Telemetry tracing] - ** xref:mptelemetry-logging.adoc[Write logs with MicroProfile Telemetry logging] - ** xref:microservice-observability-metrics.adoc[Microservice observability with with MicroProfile Metrics] - ** xref:micrometer-metrics.adoc[Choose your own monitoring tools with MicroProfile Metrics] +// ** xref:mptelemetry-logging.adoc[Write logs with MicroProfile Telemetry logging] + ** xref:microservice-observability-metrics.adoc[Microservice observability with MicroProfile Metrics] + *** xref:micrometer-metrics.adoc[Choose your own monitoring tools with MicroProfile Metrics] ** xref:health-check-microservices.adoc[Health checks for microservices] ** https://openliberty.io/guides/#observability[Guides: Observability] * xref:integration-testing.adoc[Testing] @@ -116,7 +116,6 @@ // Begin operations section .Operations -* xref:microprofile-telemetry.adoc[Enable observability with MicroProfile Telemetry] * xref:log-trace-configuration.adoc[Logs] ** xref:log-management.adoc[Log management] ** xref:access-logging.adoc[HTTP access logging] @@ -132,6 +131,8 @@ ** xref:metrics-list.adoc[MicroProfile Metrics reference list] ** xref:configuring-jmx-connection.adoc[Configuring JMX connections] ** xref:jmx-metrics-list.adoc[JMX metrics reference list] +* xref:microprofile-telemetry.adoc[OpenTelemetry] + ** xref:telemetry-troubleshooting.adoc[Troubleshooting OpenTelemetry] * xref:slow-hung-request-detection.adoc[Slow and hung request detection] * xref:validating-server-connections.adoc[Validating server connections] * xref:admin-center.adoc[Admin Center GUI] diff --git a/modules/reference/nav.adoc b/modules/reference/nav.adoc index da6747fb3..c22deb5d4 100644 --- a/modules/reference/nav.adoc +++ b/modules/reference/nav.adoc @@ -63,6 +63,7 @@ include::reference:partial$platform-nav.adoc[] ** xref:javadoc/liberty-javaee7-javadoc.adoc[Java EE 7] * xref:microprofile-api.adoc[MicroProfile API] + ** xref:javadoc/microprofile-7.0-javadoc.adoc[MicroProfile 7.0] ** xref:javadoc/microprofile-6.1-javadoc.adoc[MicroProfile 6.1] ** xref:javadoc/microprofile-6.0-javadoc.adoc[MicroProfile 6.0] ** xref:javadoc/microprofile-5.0-javadoc.adoc[MicroProfile 5.0] @@ -77,6 +78,7 @@ include::reference:partial$platform-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-61-70-diff.adoc[Differences between MicroProfile 7.0 and 6.1] ** 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] From 236f879b9a7e3c906a9baf1356cb1a532c2e106e Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Wed, 27 Nov 2024 21:53:37 +0530 Subject: [PATCH 77/81] 7610-MicroProfile 7.0 ID-011 7610-MicroProfile 7.0 ID-011 #7610 --- modules/reference/pages/diff/mp-61-70-diff.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/reference/pages/diff/mp-61-70-diff.adoc b/modules/reference/pages/diff/mp-61-70-diff.adoc index eb751e799..9cbf38bff 100644 --- a/modules/reference/pages/diff/mp-61-70-diff.adoc +++ b/modules/reference/pages/diff/mp-61-70-diff.adoc @@ -128,9 +128,9 @@ For more information on this configuration, see feature:mpOpenAPI-4.0[display=Mi [#ft] == Differences between Fault Tolerance 4.1 and 4.0 -feature:mpFaultTolerance-4.1[display=MicroProfile Fault Tolerance 4.1], an update to version 4.0, introduces integration with MicroProfile Telemetry 2.0. This feature allows Fault Tolerance to export metrics directly to MicroProfile Telemetry. The existing integration with `mpMetrics` remains unchanged. +feature:mpFaultTolerance-4.1[display=MicroProfile Fault Tolerance 4.1], an update to version 4.0, introduces integration with feature:mpTelemetry-2.0[display=MicroProfile Telemetry 2.0]. This feature allows Fault Tolerance to export metrics directly to MicroProfile Telemetry. The existing integration with feature:mpMetrics-5.1[display=MicroProfile Metrics] remains unchanged. -For integration between feature:mpFaultTolerance-4.1[display=MicroProfile Fault Tolerance] and feature:mpTelemetry-2.0[display=MicroProfile Telemetry], you must enable both feature:mpFaultTolerance-4.1[display=MicroProfile Fault Tolerance 4.1] and feature:mpTelemetry-2.0[display=MicroProfile Telemetry 2.0] simultaneously. When both features are enabled, feature:mpFaultTolerance-4.1[display=MicroProfile Fault Tolerance] can automatically export metrics to feature:mpTelemetry-2.0[display=MicroProfile Telemetry]. +For integration between MicroProfile Fault Tolerance and MicroProfile Telemetry, you must enable both MicroProfile Fault Tolerance 4.1 and MicroProfile Telemetry 2.0. When both features are enabled, MicroProfile Fault Tolerance can automatically export metrics to MicroProfile Telemetry. [source,xml] ---- @@ -138,9 +138,9 @@ For integration between feature:mpFaultTolerance-4.1[display=MicroProfile Fault mpTelemetry-2.0 ---- -For more information on configuring feature:mpTelemetry-2.0[display=MicroProfile Telemetry] to export metrics, see xref:ROOT:microprofile-telemetry.adoc#global[Collecting and exporting logs, metrics, and traces with OpenTelemetry]. +For more information on configuring MicroProfile Telemetry to export metrics, see xref:ROOT:microprofile-telemetry.adoc#global[Collecting and exporting logs, metrics, and traces with OpenTelemetry]. -If feature:mpFaultTolerance-4.1[display=MicroProfile Fault Tolerance] is enabled alongside both feature:mpTelemetry-2.0[display=MicroProfile Telemetry] and feature:mpMetrics-5.1[display=MicroProfile Metrics], Fault Tolerance can export metrics to both MicroProfile Telemetry and MicroProfile Metrics. +If MicroProfile Fault Tolerance is enabled alongside both MicroProfile Telemetry and MicroProfile Metrics, Fault Tolerance can export metrics to both MicroProfile Telemetry and MicroProfile Metrics. The following table provides a comparison of the metric types in MicroProfile Metrics and MicroProfile Telemetry. It highlights the differences in data representation and metric types across both specifications. From 9dc8967c68b0fd394ae4866bad7a44bf60b37eff Mon Sep 17 00:00:00 2001 From: David Mueller Date: Wed, 27 Nov 2024 11:36:52 -0500 Subject: [PATCH 78/81] editys --- modules/ROOT/pages/custom-mptelemetry-metrics.adoc | 6 +++--- modules/ROOT/pages/microprofile.adoc | 2 +- modules/ROOT/pages/mptel-log-events-list.adoc | 2 +- modules/ROOT/pages/mptelemetry-metrics-list.adoc | 2 +- modules/reference/pages/diff/mp-50-60-diff.adoc | 2 +- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/modules/ROOT/pages/custom-mptelemetry-metrics.adoc b/modules/ROOT/pages/custom-mptelemetry-metrics.adoc index 4e6618973..38bd93de7 100644 --- a/modules/ROOT/pages/custom-mptelemetry-metrics.adoc +++ b/modules/ROOT/pages/custom-mptelemetry-metrics.adoc @@ -14,9 +14,7 @@ You can use the OpenTelemetry metrics API to define custom metrics in your application code. When you enable the MicroProfile Telemetry feature 2.0 or later, you can then collect and emit these metrics to customize the observability of your application. -For more information about collecting and emitting metrics with MicroProfile Telemetry, see xref:microprofile-telemetry.adoc[OpenTelemetry]. - -For more information about OpenTelemetry metrics, see the link:https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/1.39.0/io/opentelemetry/api/metrics/package-summary.html[OpenTelemetry metrics API documentation]. +For more information about collecting and emitting metrics with MicroProfile Telemetry, see xref:microprofile-telemetry.adoc[Collect logs, metrics, and traces with OpenTelemetry]. Before you can use OpenTelemetry to define custom metrics metrics, you must make 3rd party APIs visible in your runtime environment by editing your runtime configuration. For more information, see link:/docs/latest/reference/feature/mpTelemetry-2.0.html#dev[Customize your application telemetry with the OpenTelemetry API]. @@ -49,3 +47,5 @@ class WithCounter { In this example, `Meter` is used to define an instrument, in this case a Counter. Application code then can record measurement values along with other attributes. Measurement aggregations are computed separately for each unique combination of attributes. For a full list of available metrics, see link:https://opentelemetry.io/docs/specs/otel/metrics/api/#meter-operations[Meter operations] in the OpenTelemetry documentation. + +For more information about OpenTelemetry metrics, see the link:https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/1.39.0/io/opentelemetry/api/metrics/package-summary.html[OpenTelemetry metrics API documentation]. diff --git a/modules/ROOT/pages/microprofile.adoc b/modules/ROOT/pages/microprofile.adoc index 5543b68d4..78b8e0b19 100644 --- a/modules/ROOT/pages/microprofile.adoc +++ b/modules/ROOT/pages/microprofile.adoc @@ -122,7 +122,7 @@ For more information, see xref:microservice-observability-metrics.adoc[Microserv === Enable distributed tracing of your microservices 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. -In Open Liberty, MicroProfile Telemetry is supported by the feature:mpTelemetry[display=MicroProfile Telemetry] feature. You can export the data that this feature collects to tracing systems such as Jaeger or Zipkin. For more information, see xref:microprofile-telemetry.adoc[OpenTelemetry]. +In Open Liberty, MicroProfile Telemetry is supported by the feature:mpTelemetry[display=MicroProfile Telemetry] feature. You can export the data that this feature collects to tracing systems such as Jaeger or Zipkin. For more information, see xref:microprofile-telemetry.adoc[Collect logs, metrics, and traces with OpenTelemetry]. 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]. diff --git a/modules/ROOT/pages/mptel-log-events-list.adoc b/modules/ROOT/pages/mptel-log-events-list.adoc index 47f7aa9da..839eb610b 100644 --- a/modules/ROOT/pages/mptel-log-events-list.adoc +++ b/modules/ROOT/pages/mptel-log-events-list.adoc @@ -14,7 +14,7 @@ MicroProfile Telemetry can collect logging events from the server runtime and applications. You can use these events to gather and analyze data that can help to better understand the behavior of applications. -For more information, see xref:microprofile-telemetry.adoc[OpenTelemetry]. +For more information, see xref:microprofile-telemetry.adoc[Collect logs, metrics, and traces with OpenTelemetry]. MicroProfile Telemetry can collect the following types of events: diff --git a/modules/ROOT/pages/mptelemetry-metrics-list.adoc b/modules/ROOT/pages/mptelemetry-metrics-list.adoc index 4bc962ec7..b067c9e8b 100644 --- a/modules/ROOT/pages/mptelemetry-metrics-list.adoc +++ b/modules/ROOT/pages/mptelemetry-metrics-list.adoc @@ -32,7 +32,7 @@ Use metric data to effectively monitor the status of your microservice systems. You can obtain metrics from applications, the Open Liberty runtime, and the Java virtual machine (JVM). They can be gathered and stored in database tools, such as link:https://prometheus.io/[Prometheus], and displayed on dashboards, such as link:https://grafana.com/[Grafana]. -When you enable the feature:mpTelemetry-2.0[display=MicroProfile Telemetry] feature version 2.0 and later, you can manage your logs, metrics, and traces in a standardized way with the OpenTelemetry protocol. For more information, see xref:microprofile-telemetry[OpenTelemetry]. +When you enable the feature:mpTelemetry-2.0[display=MicroProfile Telemetry] feature version 2.0 and later, you can manage your logs, metrics, and traces in a standardized way with the OpenTelemetry protocol. For more information, see xref:microprofile-telemetry[Collect logs, metrics, and traces with OpenTelemetry]. == Filter metrics to gather only the data you need diff --git a/modules/reference/pages/diff/mp-50-60-diff.adoc b/modules/reference/pages/diff/mp-50-60-diff.adoc index 98294075c..a6dac0b16 100644 --- a/modules/reference/pages/diff/mp-50-60-diff.adoc +++ b/modules/reference/pages/diff/mp-50-60-diff.adoc @@ -130,7 +130,7 @@ In MicroProfile 6.0, MicroProfile Telemetry 1.0 replaces MicroProfile OpenTracin === Configuration changes -In addition to replacing the `mpOpenTracing-3.0` feature with the `mpTelemtry-1.0` feature in your `server.xml` file, you must provide configuration to allow the MicroProfile Telemetry feature to connect to your distributed trace service. For more information, see xref:ROOT:microprofile-telemetry.adoc[OpenTelemetry]. +In addition to replacing the `mpOpenTracing-3.0` feature with the `mpTelemtry-1.0` feature in your `server.xml` file, you must provide configuration to allow the MicroProfile Telemetry feature to connect to your distributed trace service. For more information, see xref:ROOT:microprofile-telemetry.adoc[Collect logs, metrics, and traces with OpenTelemetry]. You do not need to package a client for your particular tracing service. MicroProfile Telemetry includes exporters for Zipkin, the OpenTelemetry Protocol (OTLP) (which is used by Jaeger since v1.35), and the older Jaeger protocol. If you need to export to a different service, you can provide a custom exporter by using the link:https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-sdk-extension-autoconfigure-spi/1.19.0/io/opentelemetry/sdk/autoconfigure/spi/traces/ConfigurableSpanExporterProvider.html[ConfigurableSpanExporterProvider service provider interface (SPI)]. From c3482ff0700fb1999657351aea6e17cfd28c4dba Mon Sep 17 00:00:00 2001 From: David Mueller Date: Wed, 27 Nov 2024 11:43:06 -0500 Subject: [PATCH 79/81] Update introduction-monitoring-metrics.adoc --- modules/ROOT/pages/introduction-monitoring-metrics.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/introduction-monitoring-metrics.adoc b/modules/ROOT/pages/introduction-monitoring-metrics.adoc index a7ccaf023..e448810de 100644 --- a/modules/ROOT/pages/introduction-monitoring-metrics.adoc +++ b/modules/ROOT/pages/introduction-monitoring-metrics.adoc @@ -10,13 +10,13 @@ :page-type: general :page-description: With Open Liberty, three types of metrics are available to monitor your applications: OpenTelemetry metrics provided by MicroProfile Telemetry, REST endpoint-style metrics that are provided by MicroProfile Metrics, and Java Management Extensions (JMX) metrics. :seo-title: Monitoring with metrics - OpenLiberty.io -:seo-description: With Open Liberty, three types of metrics are available to monitor your applications: OpenTelemetry metrics provided by MicroProfile Telemetry, REST endpoint-style metrics that are provided by MicroProfile Metrics, and Java Management Extensions (JMX) metrics..\ +:seo-description: With Open Liberty, three types of metrics are available to monitor your applications: OpenTelemetry metrics provided by MicroProfile Telemetry, REST endpoint-style metrics that are provided by MicroProfile Metrics, and Java Management Extensions (JMX) metrics = Monitoring with metrics -Three kinds of metrics are available to monitor your Open Liberty applications: OpenTelemetry metrics from MicroProfile Telemetry, REST endpoint-style metrics from MicroProfile Metrics, and Java Management Extensions (JMX) metrics. OpenTelemetry provides a standardized solution to manage metrics, logs, and traces.MicroProfile Metrics and JMX metrics can be used separately or in conjunction to improve the observability of your application systems. +Three kinds of metrics are available to monitor your Open Liberty applications: OpenTelemetry metrics from MicroProfile Telemetry, REST endpoint-style metrics from MicroProfile Metrics, and Java Management Extensions (JMX) metrics. OpenTelemetry provides a standardized solution to manage metrics, logs, and traces. MicroProfile Metrics and JMX metrics can be used separately or in conjunction to improve the observability of your application systems. -MicroProfile Telemetry 2.0 and later exports metrics to the configured OpenTelemetry metrics exporter, which can send metrics to the backend service of your choice. You might prefer this option if you also use MicroProfile Telemetry to manage your logs and traces. The following information pertains to MicroProfile Metrics and JMX Metrics. For information about using OpenTelemetry and MicroProfile Telemetry to collect and export metrics, see xref:microprofile-telemetry.adoc[OpenTelemetry]. +MicroProfile Telemetry 2.0 and later exports metrics to the configured OpenTelemetry metrics exporter, which can send metrics to the backend service of your choice. You might prefer this option if you also use MicroProfile Telemetry to manage your logs and traces. The following information pertains to MicroProfile Metrics and JMX Metrics. For information about using OpenTelemetry and MicroProfile Telemetry to collect and export metrics, see xref:microprofile-telemetry.adoc[Collect logs, metrics, and traces with OpenTelemetry]. MicroProfile Metrics can be accessed by monitoring tools, such as Prometheus, or by any client that can make REST requests. <<#jmx,JMX metrics>> are suitable for use by Java-based monitoring tools that can communicate with JMX servers, or by custom JMX clients. From 08a031275cd5532d86b8777b2a38e2eb14892581 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Wed, 27 Nov 2024 23:08:51 +0530 Subject: [PATCH 80/81] 7610-MicroProfile 7.0 ID-012 7610-MicroProfile 7.0 ID-012 #7610 --- .../pages/send-receive-multipart-jaxrs.adoc | 57 ------------------- .../reference/pages/diff/mp-61-70-diff.adoc | 2 +- 2 files changed, 1 insertion(+), 58 deletions(-) diff --git a/modules/ROOT/pages/send-receive-multipart-jaxrs.adoc b/modules/ROOT/pages/send-receive-multipart-jaxrs.adoc index 3f725d79a..4a93a4991 100644 --- a/modules/ROOT/pages/send-receive-multipart-jaxrs.adoc +++ b/modules/ROOT/pages/send-receive-multipart-jaxrs.adoc @@ -45,63 +45,6 @@ buildscript { } ---- -[#multipart] -== Processing multipart data - -The `multipart/form-data` media type enables requests to send multiple entities (parts) as a single entity using `jakarta.ws.rs.core.EntityPart` objects. - -For example, MicroProfile Multipart Rest Clients are defined as Java interfaces. - -[source,java] ----- -@Consumes(MediaType.MULTIPART_FORM_DATA) -@Produces(MediaType.MULTIPART_FORM_DATA) -@Path("/test-app") -public interface MultiPartClient extends AutoCloseable { - - @POST - @Path("upload/") - void uploadFile(List entityParts) throws IOException; -} ----- - -The example code utilizing this ingerface - -source,java] ----- -public void uploadMultipleFiles() throws Exception { - try (MultiPartClient client = RestClientBuilder.newBuilder() - .baseUri(uri) - .build(MultiPartClient.class)) { - final Map entityPartContent = new LinkedHashMap<>(2); - try (InputStream in = MultiPartClientTest.class - .getResourceAsStream("/multipart/test-file1.txt")) { - entityPartContent.put("test-file1.txt", in.readAllBytes()); - } - try (InputStream in = MultiPartClientTest.class - .getResourceAsStream("/multipart/test-file2.txt")) { - entityPartContent.put("test-file2.txt", in.readAllBytes()); - } - final List files = entityPartContent.entrySet() - .stream() - .map((entry) -> { - try { - return EntityPart.withName(entry.getKey()) - .fileName(entry.getKey()) - .content(entry.getValue()) - .mediaType(MediaType.APPLICATION_OCTET_STREAM_TYPE) - .build(); - } catch (IOException e) { - throw new UncheckedIOException(e); - } - }) - .collect(Collectors.toList()); - client.uploadFile(files); - - } - } ----- - == Send multipart/form-data parts from Jakarta Restful Web Services resources diff --git a/modules/reference/pages/diff/mp-61-70-diff.adoc b/modules/reference/pages/diff/mp-61-70-diff.adoc index 9cbf38bff..ac1f480b7 100644 --- a/modules/reference/pages/diff/mp-61-70-diff.adoc +++ b/modules/reference/pages/diff/mp-61-70-diff.adoc @@ -90,7 +90,7 @@ RestClientBuilder.newBuilder() === Processing multipart data -Information and example code are added to the xref:ROOT:send-receive-multipart-jaxrs.adoc#multipart[send and receive multipart/form-data parts in Jakarta Restful Web Services] for processing multipart data, introduced as part of RESTful Web Services version 3.1 in EE10. +The link:https://download.eclipse.org/microprofile/microprofile-rest-client-4.0/microprofile-rest-client-spec-4.0.html#_processing_multipart_data[MicroProfile Rest Client 4.0 specification] includes information and example code for processing multipart data, introduced as part of RESTful Web Services version 3.1 in EE10. [#openapi] From f37c03af51954529aa02633a6d14577acf5193a6 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Mon, 2 Dec 2024 09:10:37 -0500 Subject: [PATCH 81/81] add link to mp 7 diff --- .../reference/pages/feature/microProfile-7.0/description.adoc | 1 + 1 file changed, 1 insertion(+) create mode 100644 modules/reference/pages/feature/microProfile-7.0/description.adoc diff --git a/modules/reference/pages/feature/microProfile-7.0/description.adoc b/modules/reference/pages/feature/microProfile-7.0/description.adoc new file mode 100644 index 000000000..f130045dc --- /dev/null +++ b/modules/reference/pages/feature/microProfile-7.0/description.adoc @@ -0,0 +1 @@ +If you are updating your application from using MicroProfile 6.1 features to using MicroProfile 7.0 features, changes in API behavior might require you to update your application code. For more information, see xref:diff/mp-61-70-diff.adoc[Differences between MicroProfile 7.0 and 6.1].