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.

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 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:

Differences between MicroProfile 7.0 and 6.1 umbrella features
Differences between MicroProfile REST Client 4.0 and 3.0
Differences between MicroProfile OpenAPI 4.0 and 3.1
Differences between Fault Tolerance 4.1 and 4.0
Differences between Telemetry 2.0 and 1.1

Differences between MicroProfile 7.0 and 6.1 umbrella features

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, include the following configuration in your server.xml file when you upgrade to MicroProfile 7.0:

<feature>mpMetrics-5.1</feature>

If your application does not use any APIs from MicroProfile Metrics, no migration effort is needed. You can instead use MicroProfile Telemetry metrics.

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.

Differences between MicroProfile REST Client 4.0 and 3.0

With the release of the 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 MicroProfile Rest Client 3.0 and MicroProfile Rest Client 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.

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 by using the new RestClientBuilder.header(String, Object) method.

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

Processing multipart data

The 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.

Differences between MicroProfile OpenAPI 4.0 and 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.

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 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 the new APIs, see the MicroProfile OpenAPI 4.0 release notes.

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 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 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 by using the following configuration:

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

For more information on this configuration, see MicroProfile OpenAPI 4.0 feature.

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 feature allows Fault Tolerance to export metrics directly to MicroProfile Telemetry. The existing integration with MicroProfile Metrics remains unchanged.

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.

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

For more information on configuring MicroProfile Telemetry to export metrics, see Collecting and exporting logs, metrics, and traces with OpenTelemetry.

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.

Comparison of Metric Types between MicroProfile Metrics and MicroProfile Telemetry
Name	Type in MicroProfile Metrics	Type in MicroProfile Telemetry
`ft.invocations.total`	`Counter`	`Counter` (provides a long value)
`ft.retry.calls.total`	`Counter`	`Counter` (provides a long value)
`ft.retry.retries.total`	`Counter`	`Counter` (provides a long value)
`ft.timeout.calls.total`	`Counter`	`Counter` (provides a long value)
`ft.circuitbreaker.calls.total`	`Counter`	`Counter` (provides a long value)
`ft.circuitbreaker.state.total`	`Gauge<Long>`	`Counter` (provides a long value)
`ft.circuitbreaker.opened.total`	`Counter`	`Counter` (provides a long value)
`ft.bulkhead.calls.total`	`Counter`	`Counter` (provides a long value)
`ft.bulkhead.executionsRunning`	`Gauge<Long>`	`UpDownCounter` (provides a long value)
`ft.bulkhead.executionsWaiting`	`Gauge<Long>`	`UpDownCounter` (provides a long value)

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
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

Differences between MicroProfile Telemetry 2.0 and 1.1

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
JVM runtime environment metrics
Runtime-level logs
Application logs

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.

For more information on OpenTelemetry, see Collecting and exporting logs, metrics, and traces with OpenTelemetry.