Monitoring with MicroProfile metrics

You can use the mpMetrics-1.0 or the mpMetrics-1.1 feature to monitor applications that are instrumented with the MicroProfile metrics API. The mpMetrics-1.0 and the mpMetrics-1.1 features provide a /metrics REST interface that conforms to the MicroProfile metrics 1.0 or MicroProfile metrics 1.1 specification. Application developers can add their own custom metrics, by using the MicroProfile metrics API, alongside the metrics provided by Liberty.

Documentation for the MicroProfile Metrics feature versions 2.0 and later is available on the Open Liberty website.

Before you begin

To browse the MicroProfile metrics 1.0 specification, see Metrics for Eclipse MicroProfile 1.0 specification.

To browse the MicroProfile metrics 1.1 specification, see Metrics for Eclipse MicroProfile 1.1 specification.

Procedure

Set up monitoring with MicroProfile metrics.
1. Configure the feature. Add the mpMetrics-1.0 or the mpMetrics-1.1 feature to the feature manager in the server.xml file.
  The mpMetrics-1.0 or the mpMetrics-1.1 feature enables the user to optionally secure the REST API with authentication. The default configuration is to secure the REST API with authentication. 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 illustrates a basic security setup. MicroProfile metrics use the default keystore to secure the endpoint.
```
<featureManager>
  <feature>mpMetrics-1.0</feature>                  
</featureManager>

<quickStartSecurity userName="theUser" userPassword="thePassword"/>
<keyStore id="defaultKeyStore" password="Liberty"/>
```
  The following example illustrates a configuration without security:
```
<featureManager>
  <feature>mpMetrics-1.1</feature>                  
</featureManager>

<mpMetrics authentication="false"/>
```
2. Set up monitoring tools to monitor data from /metrics.
  
  The default format for responses to requests to /metrics is a text format compatible with Prometheus. Responses to requests made to /metrics with an accept header of application/json are provided in a JSON output format. See MicroProfile metrics REST API.
3. Optional: Use the mpMetrics-1.1 and the mpFaultTolerance-1.1 features together.
  
  Metrics are automatically provided for each method that you annotate with a fault tolerance annotation. The metrics that are provided depend on which fault tolerance annotations you use. For more information, see the Fault Tolerance 1.1 specification.
Authorize access to the metrics API.
1. To allow a user or a group of users to access the metrics API, map the administrator role to the user or group from the configured user registry.
  
  The metrics API is protected by Liberty administrator role.
  The following example shows a sample configuration to enable Bob, a user in the configured user registry, and AuthorizedGroup, a group in the configured user registry, to access the 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>
```
2. If authentication is performed by a single sign-on service, such as OpenID Connect or SAML, or is authenticated by a verifiable security token such as JSON Web Token (JWT), map the administrator role to the user or group access-id instead of the user or group name.
```
 <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>
```

Example

In the following example, the client is authenticated with a MicroProfile JWT where the user principal name (upn) claim is tom@example.com, the issuer (iss) claim is https://idp.example.com and the groups claim contains ManagingGroup.

{
  ...
  "sub": "tom",
  "upn": "tom@example.com",
  "groups": [
    "admin"
  ],
  "iss": "https://idp.example.com",
  ...
}

The following examples show two different sample configurations for mapping the administrator role to a subject in JWT.

To map the administrator role to the subject in JWT with <user-access-id>, use the following configuration:

 <administrator-role>
     <user-access-id>user:https://idp.example.com/tom@example.com</user-access-id>
  </administrator-role>

To map the administrator role to the subject in JWT with <group-access-id>, use the following configuration:

 <administrator-role>
     <group-access-id>group:https://idp.example.com/admin</group-access-id>
  </administrator-role>

For more information about mapping the administrator role, see Mapping the administrator role for Liberty.