MicroProfile Metrics
5.1
5.0
4.0
3.0
2.3
2.2
2.0
1.1
1.0

This feature provides support for the Eclipse MicroProfile Metrics 5.0 specification for enterprise Java.

You can use MicroProfile Config properties to provide configuration values for MicroProfile Metrics. For more information, see MicroProfile Config Properties: Metrics.
MicroProfile metrics provides a /metrics endpoint from which you can access all metrics that are emitted by the Open Liberty server and deployed applications. When the application runs, you can view your metrics from any browser by accessing the endpoint.

If you are updating your application from using MicroProfile Metrics 4.0 to using MicroProfile Metrics 5.0, changes in API behavior might require you to update your application code. For more information, see Differences between MicroProfile Metrics 5.0 and 4.0.

Enabling this feature

To enable the MicroProfile Metrics 5.0 feature, add the following element declaration into your server.xml file, inside the featureManager element:

<feature>mpMetrics-5.0</feature>

Examples

Configure MicroProfile metrics security

The MicroProfile Metrics feature can be used to monitor applications that use the MicroProfile Metrics API. The MicroProfile Metrics API is a REST API that displays metrics for administrators to access. You can configure the MicroProfile Metrics feature to require authentication and authorization to access the /metrics endpoint. The following example shows a basic security configuration for the REST API:

<quickStartSecurity userName="theUser" userPassword="thePassword"/>
<keyStore id="defaultKeyStore" password="Liberty"/>

By default, the MicroProfile Metrics feature uses the default keystore to secure the /metrics REST endpoint. The quickStartSecurity element is specified to enable administrative role mapping for a user who needs access to the endpoint. However, you can use any method of administrative role mapping to configure access to the endpoint and enable metrics security.

Authorize access to the metrics API with a basic user registry

The /metrics REST endpoint is used to access the metrics that are stored in the server. The metrics can include both information about server components, such as connection pools, and metrics information that is created by applications. In some cases, you might want to limit access to this data. To allow users and groups of users access to the MicroProfile Metrics API, you can map the administrator role to users and groups that are in the configured user registry. The MicroProfile Metrics API is protected by the Open Liberty administrator role. The following example maps the user bob and the group AuthorizedGroup to the administrator role so that they can access the MicroProfile Metrics API:

<basicRegistry id="basic" realm="WebRealm">
    <user name="bob" password="bobpwd" />
    <user name="alice" password="alicepwd" />
    <user name="carl" password="carlpwd" />

    <group name="AuthorizedGroup">
        <member name="alice" />
    </group>
</basicRegistry>

 <administrator-role>
     <user>bob</user>
     <group>AuthorizedGroup</group>
 </administrator-role>

Authorize access to the metrics API with SSO

When you enable an SSO method, such as JSON Web Token (JWT), you can map the administrator role to the user-access-id or group-access-id element. This mapping authorizes access to the MicroProfile Metrics API. The following example shows the configuration to access the API when an SSO method is enabled:

<administrator-role>
    <user-access-id>user:https://idp.example.com/bob</user-access-id>
    <group-access-id>group:https://idp.example.com/ManagingGroup</group-access-id>
</administrator-role>

The user-access-id and group-access-id elements specify the realm that the authorized user or group belongs to. The user bob and the ManagingGroup group both belong to the https://idp.example.com realm that is authorized to access the API.

Remove MicroProfile metrics security

Although the default configuration for the MicroProfile Metrics feature secures the REST API, it is possible to remove metrics security. With secured authentication disabled, the metrics REST endpoint is not restricted only to HTTP, but is still accessible through the HTTPS protocol. The following example shows a MicroProfile Metrics configuration with security disabled:

<mpMetrics authentication="false"/>

Feature configuration elements

Standard API packages provided by this feature

  • jakarta.annotation

  • jakarta.annotation.security

  • jakarta.annotation.sql

Stable API packages provided by this feature

  • org.eclipse.microprofile.metrics

  • org.eclipse.microprofile.metrics.annotation

Liberty API packages provided by this feature

Features that this feature enables

Supported Java versions

  • JavaSE-11.0

  • JavaSE-17.0

  • JavaSE-21.0

  • JavaSE-22.0

Features that enable this feature

Developing a feature that depends on this feature

If you are developing a feature that depends on this feature, include the following item in the Subsystem-Content header in your feature manifest file.

io.openliberty.mpMetrics-5.0; type="osgi.subsystem.feature"

SPI packages provided by this feature