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.
Procedure
- Set up monitoring with MicroProfile metrics.
- 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"/>
- 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.
- 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.
- 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>
- 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.