MicroProfile 7.0 ID

[Emily-Jiang]

MicroProfile 7.0 is a major release with the current updated MicroProfile specifications:

1. MicroProfile Telemetry 2.0
2. MicroProfile Rest Client 4.0
3. MicroProfile OpenAPI 4.0
4. MicroProfile Fault Tolerance 4.1

This release has the following significant changes:

1. removing MicroProfile Metrics 5.1 from the MicroProfile umbrella release and make it standalone.
2. MicroProfile Telemetry 2.0 has a major release to include Logs, Metrics apart from Tracing.
3. MicroProfile Rest Client 4.0 consumed Jakarta Restful Web Services 3.1 to support multiparts.
4. MicroProfile OpenAPI 4.0 aligned with OpenAPI 3.1 standards.
5. MicroProfile 7.0 works with Jakarta EE 10 as a minimum.

[jim-krueger]

When the MicroProfile API document is updated with a "Differences between MicroProfile 7.0 and 6.1" section, please add a "Differences between MicroProfile REST Client 4.0 and 3.0" section with the following information:

With the release of the MicroProfile REST Client 4.0 feature (mpRestClient-4.0), 
the underlying MicroProfile REST Client implementation for Open Liberty is now 
compatible with Jakarta EE 10 and tolerates Jakarta EE 11. 

If you update your server from a version of the 
[MicroProfile REST Client](https://openliberty.io/docs/latest/reference/feature/mpRestClient.html) 
feature prior to version 3.0, changes in API behavior might require you to update 
your application code. See 
[Differences between MicroProfile REST Client 3.0 and 2.0](https://openliberty.io/docs/latest/reference/diff/mp-41-50-diff.html#rc) 
for details.

The following sections detail changes in behavior between the mpRestClient-3.0 and 
mpRestClient-4.0 features.

Client creation without URI

Users no longer need to crate a URI themselves to create a Client instance, instead they can pass a String.

RestClientBuilder.newBuilder()
                             .baseUri("http://example.com")
                             .build(SomeClient.class)

Set HTTP Headers on a per instance basis

Users are now able set HTTP Headers on a per Client instance via the new RestClientBuilder.header(String,Object) method.

RestClientBuilder.newBuilder()
                             .baseUri(someURI or String)
                             .header("Some-Header", headerValueObj)
                             .build(SomeClient.class)

Processing Multipart Data

Information and example code has been added to the Microprofile Rest Client 4.0 specification for processing multipart data, which was added as part of RESTful Web Services version 3.1 in EE10.

[Azquelt]

When the MicroProfile API document is updated with a "Differences between MicroProfile 7.0 and 6.1" section, please add a "Differences between MicroProfile OpenAPI 3.1 and 4.0" section with the following information:

OpenAPI version updated to 3.1

The OpenAPI document is now produced in OpenAPI 3.1 format by default (updated from OpenAPI 3.0 in mpOpenAPI-3.1).

OpenAPI 3.1 allows more detail to be captured, including the use of full JSON Schema (2020-12 draft) for describing data objects, support for documenting webhooks and support for documenting that an API uses mutual TLS for authentication. Further detail can be found in the 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. More detail on the new APIs can be found in the MicroProfile OpenAPI 4.0 release notes

However, the changes mean that OpenAPI 3.1 is not fully backwards compatible with OpenAPI 3.0 and existing tools may not work with it. For compatibility with existing tools, you can configure mpOpenAPI-4.0 to produce OpenAPI 3.0 documentation:

<mpOpenAPI openAPIVersion="3.0" />

If the new APIs and annotations which correspond to features from OpenAPI 3.1 are used, the additional information they provide will not be output when the feature is configured to produce OpenAPI 3.0 documents.

All deployed applications are documented by default

All deployed applications are now included in the OpenAPI documentation by default. Previous versions of mpOpenAPI defaulted to only documenting the first module of the first application deployed.

Which applications are included can be controlled using configuration:

<mpOpenAPI>
  <includeApplication>application1</includeApplication>
  <includeApplication>application2</includeApplication>
</mpOpenAPI>

More information an examples can be found in link to main MP OpenAPI docs for this configuration

[benjamin-confino]

Fault Tolerance version updated to 4.1

As an update to MicroProfile Fault Tolerance 4.0, the MicroProfile Fault Tolerance 4.1 provides integration with MicroProfile Telemetry 2.0 allowing Fault Tolerance to export metrics to MicroProfile Telemetry. The existing integration with mpMetrics remains unchanged.

Enable MicroProfile Fault Tolerance

Add the following in the server.xml.

<feature>mpFaultTolerance-4.1</feature>

To enable integration between mpFaultTolerance and mpTelemetry you must enable mpFaultTolerance-4.1 and mpTelemetry-2.0 simultaneously, at which point the mpFaultTolerance will automatically begin to export metrics to mpTelemetry.

<feature>mpFaultTolerance-4.1</feature>
<feature>mpTelemetry-2.0</feature>

See the section on mpTelemetry-2.0 for more detials on configuring mpTelemetry to export metrics.

If mpFaultTolerance-4.1 is enabled alongside both mpTelemetry-2.0 and mpMetrics-5.1 Fault Tolerence will export metrics to both mpTelemetry and mpMetrics.

Comparason between metrics in mpMetrics and mpTelemetry

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<Long>	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<Long>	An UpDownCounter that emits long
ft.bulkhead.executionsWaiting	Gauge<Long>	An UpDownCounter that emits long

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

[Emily-Jiang]

FaultTolerence version updated to 4.1

Fault Tolerence 4.1 introduces integration with Open Telemetry 2.0. If both features are enabled metrics from Fault Tolerance will automatically be exported from Fault Tolerance to Open Telemetry.

There is no user action needed to enable or use this integration beyond what is normally needed for Fault Tolerence and Open Telemetry.

@benjamin-confino this is too brief. You need to come up with a comparison table between FT 4.0 vs. 4.1. What are the metrics changes etc?

[Emily-Jiang]

MicroProfile 7.0 vs. MicroProfile 6.1
The MicroProfile 7.0 is a major release that does include backward incompatible changes.
It replaces MicroProfile Metrics with MicroProfile Telemetry 2.0 which offers the Metrics capabilities in addition to Logs and Tracing. If you are using MicroProfile Metrics from MicroProfile 6.1, when moving to MicroProfile 7.0, you need to add the following in the server.xml.

<feature>mpMetrics-5.1</feature>

If you have not used any APIs from MicroProfile Metrics, your application will have the Metrics from MicroProfile Telemetry 2.0 and no migration effort is needed.

In Open Liberty, the Jakarta EE 10 Core Profile features are automatically packaged with the feature microProfile-7.0 for better upgrade experience from microProfile-6.1.

[yasmin-aumeeruddy]

Telemetry version updated to 2.0

As an update to MicroProfile Telemetry 1.1, the MicroProfile Telemetry 2.0 feature provides the later version of the OpenTelemetry SDK, providing version 1.39 of OpenTelemetry. Previously, only traces were collected and exported. The new feature provides the ability to collect metrics and logs. In particular, the following are provided:

• Access to the OpenTelemetry Metrics API
• HTTP metrics
• JVM runtime environment metrics
• Runtime level logs
• Application logs

Enable MicroProfile Telemetry

Add the following in the server.xml.

<feature>mpTelemetry-2.0</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 sdk with system properties or environment variables. You can then configure how MicroProfile Telemetry collects and exports traces, metrics and logs. This is a significant difference from MicroProfile Telemetry 1.1 which was able to provide full functionality when configuring the feature with MicroProfile Config. If environment variables and system properties are not used for configuration, runtime level metrics and logs cannot be collected.

Using the aforementioned config sources, enable the OpenTelemetry sdk:

otel.sdk.disabled=false

Accessing the metrics API

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 OpenTelemetry metrics, see the OpenTelemetry metrics API documentation.

To make the APIs accessible, enable third-party APIs for your application by adding the following code in your server.xml file:

Collecting logs

You can enable MicroProfile Telemetry to collect logs from different sources in the Open Liberty runtime environment. MicroProfile Telemetry can collect the following types of events:

• Message events

• Trace events

• FFDC events

To enable these, configure the source attribute for the mpTelemetry element with a comma-separated list of the desired log sources:

<mpTelemetry source="message, trace, ffdc"/>

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 Collect logs from a specified source.

Exporting metrics and logs

By default, all OpenTelemetry data is exported to OTLP. You can change this setting 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, setting the following would change the metrics exporter to send the collected metrics to the console:

otel.metrics.exporter = console

[Emily-Jiang]

@yasmin-aumeeruddy thanks for the info! However, there are some piece are missing.

1. no snippet of server.xml
2. unclear what should be added to the mpTelemetry element with what attribute
3. please provide an example of otel.metrics.exporter property

[Emily-Jiang]

When the MicroProfile API document is updated with a "Differences between MicroProfile 7.0 and 6.1" section, please add a "Differences between MicroProfile REST Client 4.0 and 3.0" section with the following information:

With the release of the MicroProfile REST Client 4.0 feature (mpRestClient-4.0), 
the underlying MicroProfile REST Client implementation for Open Liberty is now 
compatible with Jakarta EE 10 and tolerates Jakarta EE 11. 

If you update your server from a version of the 
[MicroProfile REST Client](https://openliberty.io/docs/latest/reference/feature/mpRestClient.html) 
feature prior to version 3.0, changes in API behavior might require you to update 
your application code. See 
[Differences between MicroProfile REST Client 3.0 and 2.0](https://openliberty.io/docs/latest/reference/diff/mp-41-50-diff.html#rc) 
for details.

The following sections detail changes in behavior between the mpRestClient-3.0 and 
mpRestClient-4.0 features.

Client creation without URI

Users no longer need to crate a URI themselves to create a Client instance, instead they can pass a String.

RestClientBuilder.newBuilder()
                             .baseUri("http://example.com")
                             .build(SomeClient.class)

Set HTTP Headers on a per instance basis

Users are now able set HTTP Headers on a per Client instance via the new RestClientBuilder.header(String,Object) method.

RestClientBuilder.newBuilder()
                             .baseUri(someURI or String)
                             .header("Some-Header", headerValueObj)
                             .build(SomeClient.class)

@jim-krueger can you also mention the Multipart support?

In addition, example code for processing multipart data via the MicroProfile Rest Client was added to the specification. This support was added in a previous release and remains unchanged.

(Note for documentation developers: If you would prefer the text and example code can be taken directly from the specification link provided.)

[Azquelt]

@Emily-Jiang I've updated the first comment to correct OpenAPI 3.0 to OpenAPI 4.0.

[yasmin-aumeeruddy]

@Emily-Jiang I have updated the comment for MpTelemetry

[Emily-Jiang]

@benjamin-confino @jim-krueger please address my comments so that @chirp1 and @dmuelle can work on it today?

[jim-krueger]

@Emily-Jiang Done. Let me know if you feel more is needed.

[benjamin-confino]

@Emily-Jiang I've updated my comment, let me know if you want any further changes.

[Emily-Jiang]

@dmuelle @chirp1 the content is complete. please go ahead to act on this issue.

[ramkumar-k-9286]

Hi @Emily-Jiang

Draft page has been added.

Draft link: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/diff/mp-61-70-diff.html

Please review the same and add the Developer Reviewed label if you are satisfied with the changes.

Regards,
Ramkumar

CC @dmuelle

[benjamin-confino]

The Fault Tolerance section looks good.

[jim-krueger]

@ramkumar-k-9286 , @Emily-Jiang Please see the "Processing Multipart Data" section I've added to my MicroProfile Rest Client comment above.

[yasmin-aumeeruddy]

Following feedback from @Emily-Jiang , please change:

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.

otel.sdk.disabled=false

to:

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 and instead use other available MicroProfile Config properties, runtime-level metrics and logs cannot be collected.

To enable the OpenTelemetry SDK, use the following configuration.

otel.sdk.disabled=false

To set the name of the service, use the following configuration.

otel.service.name=app1

[ramkumar-k-9286]

Hi @Emily-Jiang

All the suggested corrections have been made.

Draft link: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/diff/mp-61-70-diff.html

Please review the same and add the Developer Reviewed label if you are satisfied with the changes.

Regards,
Ramkumar

CC @dmuelle

[Emily-Jiang]

@ramkumar-k-9286 looks good except the following link was not resolved

<link to main MP OpenAPI docs for this configuration>.

[ramkumar-k-9286]

Hi @Emily-Jiang

All the suggested corrections have been made.

Draft link: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/diff/mp-61-70-diff.html

Please review the same and add the Developer Reviewed label if you are satisfied with the changes.

Regards,
Ramkumar

CC @dmuelle

[Emily-Jiang]

Hi @Emily-Jiang

All the suggested corrections have been made.

Draft link: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/diff/mp-61-70-diff.html

Please review the same and add the Developer Reviewed label if you are satisfied with the changes.

Regards, Ramkumar

CC @dmuelle

Now I can see the link. Why does it point to mpOpenAPI-3.1 instead of 4.0? @Azquelt please confirm which one should be used. I had expected to see 4.0 is used.

[ramkumar-k-9286]

Hi @Emily-Jiang
All the suggested corrections have been made.
Draft link: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/diff/mp-61-70-diff.html
Please review the same and add the Developer Reviewed label if you are satisfied with the changes.
Regards, Ramkumar
CC @dmuelle

Now I can see the link. Why does it point to mpOpenAPI-3.1 instead of 4.0? @Azquelt please confirm which one should be used. I had expected to see 4.0 is used.

@Emily-Jiang I did it on purpose. i will replace it with 4.0. If I had placed 4.0 link now all you have got would have seen would have been a broken link.

[ramkumar-k-9286]

Hi @Emily-Jiang

All the suggested corrections have been made.

Draft link: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/diff/mp-61-70-diff.html

Please review the same and add the Developer Reviewed label if you are satisfied with the changes.

I've replaced the mpOpenAPI-3.1 link with the mpOpenAPI-4.0 link. However please NOTE that the 4.0 link will not be active until GA.

Regards,
Ramkumar

CC @dmuelle

[Emily-Jiang]

The content looks good to me. Thank you @ramkumar-k-9286