Chapter 25. Eclipse MicroProfile
25.1. Using Eclipse MicroProfile Config to Manage Configuration
Eclipse Microprofile Config is provided as Technology Preview only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.
25.1.1. About the MicroProfile Config SmallRye Subsystem
Configuration data can change dynamically and applications need to be able to access the latest configuration information without restarting the server. Eclipse MicroProfile Config provides portable externalization of configuration data. This allows applications and microservices to be configured to run in multiple environments without a need for modification or repackaging. Eclipse MicroProfile Config functionality is implemented in JBoss EAP using the SmallRye Config component and is provided by the microprofile-config-smallrye
subsystem. This subsystem is included in the default JBoss EAP 7.3 configuration.
25.1.2. ConfigSources Supported by the MicroProfile Config SmallRye Subsystem
MicroProfile Config configuration properties, which can be in different formats and can come from different locations, are provided by ConfigSources, which are implementations of the org.eclipse.microprofile.config.spi.ConfigSource
interface.
The MicroProfile Config specification provides the following default ConfigSource
implementations for retrieving configuration values.
-
Using
System.getProperties()
. -
Using
System.getenv()
. -
From all
META-INF/microprofile-config.properties
files on the class path.
The microprofile-config-smallrye
subsystem supports the following additional types of ConfigSource
resources for retrieving configuration values.
- From properties.
- From a files in a directory.
-
From a
ConfigSource
class. -
From a
ConfigSourceProvider
class.
Although the sections below use the management CLI to configure the microprofile-config-smallrye
subsystem, you can also use the management console to accomplish these tasks by navigating to Configuration → Subsystems → MicroProfile Config → and clicking View.
See MicroProfile Config SmallRye Subsystem Attributes for the list of attributes available for configuring the MicroProfile Config SmallRye subsystem.
Obtaining ConfigSource Configuraton from Properties
You can store properties directly for access by a ConfigSource
by adding a config-source
attribute and specifying the properties
as a list.
The following management CLI command creates a ConfigSource
containing configuration data for the property1
and property2
properties.
/subsystem=microprofile-config-smallrye/config-source=props:add(properties={property1=value1,property2=value2})
This command results in the following XML configuration for the microprofile-config-smallrye
subsystem.
<subsystem xmlns="urn:wildfly:microprofile-config-smallrye:1.0"> <config-source name="props"> <property name="property1" value="value1"/> <property name="property2" value="value2"/> </config-source> </subsystem>
Obtaining ConfigSource Configuraton from a Directory
You can create a ConfigSource
to read properties from files in a directory by adding the config-source
attribute and specifying the directory that contains the files. The name of each file in the dir
directory is the name of a property and the file content is the value of the property,
The following management CLI command creates a ConfigSource
that reads configuration properties from files in the /etc/config/numbers-app/
directory.
/subsystem=microprofile-config-smallrye/config-source=file-props:add(dir={path=/etc/config/numbers-app})
This command results in the following XML configuration for the microprofile-config-smallrye
subsystem.
<subsystem xmlns="urn:wildfly:microprofile-config-smallrye:1.0"> <config-source name="file-props"> <dir path="/etc/config/numbers-app"/> </config-source> </subsystem>
This structure corresponds to the structure used by OpenShift ConfigMaps
. The dir
value corresponds to the mountPath
in the ConfigMap
definition in OpenShift or Kubernetes.
Any application deployed in JBoss EAP can programmatically access the properties that are stored in the directory.
Assume that the directory /etc/config/numbers-app/
contains the following two files:
-
num.size
: This file contains the value5
. -
num.max
: This file contains the value100
.
In the code example below, num.size
returns 5
and num.max
returns 100
.
@Inject @ConfigProperty(name = "num.size") int numSize; @Inject @ConfigProperty(name = "num.max") int numMax;
Obtaining ConfigSource Configuraton from a ConfigSource Class
You can create and configure a custom org.eclipse.microprofile.config.spi.ConfigSource
implementation class to provide a source for the configuration values.
The following management CLI command creates a ConfigSource
for the implementation class named org.example.MyConfigSource
that is provided by a JBoss Module named org.example
.
/subsystem=microprofile-config-smallrye/config-source=my-config-source:add(class={name=org.example.MyConfigSource, module=org.example})
This command results in the following XML configuration for the microprofile-config-smallrye
subsystem.
<subsystem xmlns="urn:wildfly:microprofile-config-smallrye:1.0"> <config-source name="my-config-source"> <class name="org.example.MyConfigSource" module="org.example"/> </config-source> </subsystem>
Properties provided by this ConfigSource
class are available to any JBoss EAP deployment.
For information about how to add a global module to the JBoss EAP server, see Define Global Modules.
Obtaining ConfigSource Configuraton from a ConfigSourceProvider Class
You can create and configure a custom org.eclipse.microprofile.config.spi.ConfigSourceProvider
implementation class that registers implementations for multiple ConfigSource
instances.
The following management CLI command creates a config-source-provider
for the implementation class named org.example.MyConfigSourceProvider
that is provided by a JBoss Module named org.example
.
/subsystem=microprofile-config-smallrye/config-source-provider=my-config-source-provider:add(class={name=org.example.MyConfigSourceProvider, module=org.example})
This command results in the following XML configuration for the microprofile-config-smallrye
subsystem.
<subsystem xmlns="urn:wildfly:microprofile-config-smallrye:1.0"> <config-source-provider name="my-config-source-provider"> <class name="org.example.MyConfigSourceProvider" module="org.example"/> </config-source-provider> </subsystem>
Properties provided by the ConfigSourceProvider
implementation are available to any JBoss EAP deployment.
For information about how to add a global module to the JBoss EAP server, see Define Global Modules.
25.1.3. Deploying Applications that Access ConfigSources
Applications that access MicroProfile Config in their Java code must enable CDI, either by including a META-INF/beans.xml
or WEB-INF/beans.xml
file in the deployment archive, or by including a CDI bean annotation.
For more information about CDI, see Contexts and Dependency Injection (CDI) in the JBoss EAP Development Guide.
25.2. Tracing Requests with the MicroProfile OpenTracing SmallRye Subsystem
Eclipse Microprofile OpenTracing is provided as Technology Preview only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.
25.2.1. About Eclipse MicroProfile OpenTracing
The ability to trace requests across service boundaries is important, especially in a microservices environment where a request can flow through multiple services during its life cycle. The Eclipse Microprofile OpenTracing specification defines behaviors and an API for accessing an OpenTracing compliant Tracer
object within a Jakarta RESTful Web Services application. The behaviors specify how OpenTracing Spans are to be created automatically for incoming and outgoing requests. The API defines how to explicitly disable or enable tracing for given endpoints.
25.2.2. About the MicroProfile OpenTracing SmallRye Subsystem
Eclipse Microprofile OpenTracing functionality is implemented in JBoss EAP using the SmallRye OpenTracing component and is provided by the microprofile-opentracing-smallrye
subsystem. This subsystem implements Microprofile 1.3.0, which includes support for tracing requests to JAX-RS endpoints and CDI beans and is included in the default JBoss EAP 7.3 configuration.
The microprofile-opentracing-smallrye
subsystem ships with the Jaeger Client as the default tracer, plus a set of instrumentation libraries for components commonly used in Jakarta EE applications, such as Jakarta RESTful Web Services and Contexts and Dependency Injection. Each individual WAR deployed to the JBoss EAP server automatically has its own Tracer
instance. Each WAR within an EAR is treated as an individual WAR, and each has its own Tracer
instance. By default, the service name used with the Jaeger Client is derived from the deployment’s name, which is usually the WAR file name.
25.2.3. Configuring the MicroProfile OpenTracing SmallRye Subsystem
The microprofile-opentracing-smallrye
subsystem is included in the default JBoss EAP 7.3 configuration. Because there can be a memory or performance costs associated with OpenTracing enabled, you might want to disable this subsystem.
Use the following management CLI commands to disable the MicroProfile OpenTracing feature globally for the server instance by removing the subsystem from the server configuration.
Remove the subsystem.
/subsystem=microprofile-opentracing-smallrye:remove()
Reload the server for the changes to take effect.
reload
Use the following management CLI commands to enable the MicroProfile OpenTracing feature globally for the server instance by adding the subsystem to the server configuration.
Add the subsystem.
/subsystem=microprofile-opentracing-smallrye:add()
Reload the server for the changes to take effect.
reload
There are no other configuration options available for the microprofile-opentracing-smallrye
subsystem. Instead, you configure the Jaeger Client by setting system properties or environment variables. See the Jaeger documentation for information about how to configure the Jaeger Client. See Configuration via Environment in the Jaeger documentation for the list of valid system properties.
Because this feature is provided as Technology Preview, the current configuration options, particularly those related to configuring the Jaeger Client tracer using system properties and environment variables, might change in incompatible ways in future releases.
Also be aware that, by default, the Jaeger Client for Jakarta has a probabilistic sampling strategy that is set to 0.001
, meaning that only approximately one in one thousand traces will be sampled. To sample every request, set the system properties JAEGER_SAMPLER_TYPE
to const
and JAEGER_SAMPLER_PARAM
to 1
.
For information about how to override the default tracer and how to trace CDI beans, see Using Eclipse MicroProfile OpenTracing to Trace Requests in the Development Guide.
25.3. Monitor Server Health Using Eclipse MicroProfile Health
Eclipse MicroProfile Health is provided as Technology Preview only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.
25.3.1. MicroProfile Health SmallRye Subsystem
JBoss EAP includes the SmallRye Health component, which provides Eclipse MicroProfile Health functionality using the microprofile-health-smallrye
subsystem. This subsystem is used to determine whether the JBoss EAP instance is responding as expected, and is enabled by default.
By default, the MicroProfile Health SmallRye subsystem only evaluates whether the server is running. To include custom health checks, see the Implement a Custom Health Check section in the Development Guide.
Microprofile Health is only available when running JBoss EAP as a standalone server.
25.3.2. Health Check Using the Management CLI Examples
Health checks can be examined using the management CLI.
-
The
:check
attribute demonstrates obtaining the current health of the server (liveness
andreadiness
probes).
/subsystem=microprofile-health-smallrye:check { "outcome" => "success", "result" => { "outcome" => "UP", "checks" => [] } }
-
The
:check-live
attribute obtains the health data forliveness
probes only.
/subsystem=microprofile-health-smallrye:check-live { "outcome" => "success", "result" => { "outcome" => "UP", "checks" => [] } }
-
The
:check-ready
attribute obtains the health data forreadiness
probes only.
/subsystem=microprofile-health-smallrye:check-ready { "outcome" => "success", "result" => { "outcome" => "UP", "checks" => [] } }
25.3.3. Examining the Health Check Using the Management Console
The management console includes a check runtime operation that shows the health checks and the global outcome as boolean value.
To obtain the current health status of the server from the management console:
- Navigate to the Runtime tab and select the server.
- In the Monitor column, click MicroProfile Health → View.
25.3.4. Examine the Health Check Using the HTTP Endpoint
Health check is automatically deployed to the health
context on JBoss EAP.
That means that in addition to being able to examine it using the management CLI, you can also obtain the current health using the HTTP endpoint. The default address for the `/health` endpoint, accessible from the management interfaces, is `http://127.0.0.1:9990/health`.
- To obtain the current health of the server using the HTTP endpoint, the following URL would be used.
http://HOST:9990/health
Accessing this context displays the health check in JSON format, indicating whether the server is healthy.This endpoint checks the health of both liveness
and readiness
probes.
-
The
/health/live
endpoint checks the current health ofliveness
probes.
http://HOST:9990/health/live
-
The
/health/ready
endpoint checks the current health ofreadiness
probes.
http://HOST:9990/health/ready
25.3.5. Global Status When Probes are not Defined
The :empty-readiness-checks-status
and :empty-liveness-checks-status
are management attributes that specify the global status when no readiness
or liveness
probes are defined. These attributes allow applications to report ‘DOWN’ until their probes verify that the application is ready/live. By default, these attributes will report ‘UP’.
-
The
:empty-readiness-checks-status
attribute specifies the global status forreadiness
probes if noreadiness
probes have been defined.
/subsystem=microprofile-health-smallrye:read-attribute(name=empty-readiness-checks-status) { "outcome" => "success", "result" => expression "${env.MP_HEALTH_EMPTY_READINESS_CHECKS_STATUS:UP}" }
-
The
:empty-liveness-checks-status`attribute specifies the global status for `liveness
probes if noliveness
probes have been defined.
/subsystem=microprofile-health-smallrye:read-attribute(name=empty-liveness-checks-status) { "outcome" => "success", "result" => expression "${env.MP_HEALTH_EMPTY_LIVENESS_CHECKS_STATUS:UP}" }
The /health
HTTP endpoint and :check
operation that check both readiness
and liveness
probes also take into account these attributes.
25.3.6. Enable Authentication for the HTTP Endpoint
The health
context can be configured to require that users be authorized to access the context.
To enable authentication on this endpoint:
Set the
security-enabled
attribute totrue
on themicroprofile-health-smallrye
subsystem./subsystem=microprofile-health-smallrye:write-attribute(name=security-enabled,value=true)
Reload the server for the changes to take effect.
reload
Any subsequent attempts to access the health
endpoint result in an authentication prompt.
25.4. Eclipse MicroProfile Metrics
Eclipse MicroProfile Metrics is provided as Technology Preview only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.
25.4.1. About the MicroProfile Metrics Subsystem
JBoss EAP includes the SmallRye Metrics component, which provides Eclipse MicroProfile Metrics functionality using the microprofile-metrics-smallrye
subsystem. This subsystem is used to provide monitoring data for the JBoss EAP instance, and is enabled by default.
The microprofile-metrics-smallrye
subsystem is only enabled in standalone configurations.
25.4.2. Examine Metrics Using the HTTP Endpoint
Metrics are automatically available on the JBoss EAP management interface, with the following contexts available.
-
/metrics/
- Contains metrics specified in the MicroProfile 3.0 specification. -
/metrics/vendor
- Contains vendor-specific metrics, such as memory pools. -
/metrics/application
- Contains metrics from deployed applications and subsystems that use the MicroProfile Metrics API.
The JBoss EAP subsystem metrics are exposed in the Prometheus format.
The metric names are based on subsystem and attribute names. For example, the subsystem undertow
exposes a metric attribute request-count
for every servlet in an application deployment. The name of this metric is jboss_undertow_request_count
. The prefix jboss helps identify the metrics source.
To see a list of the metrics exposed by EAP, execute the following command in the CLI:
$ curl -v http://localhost:9990/metrics | grep -i type
Example: Obtaining the request count for a JAX-RS application
The following example demonstrates how to find the number of requests made to a web service deployed on JBoss EAP. The example uses the helloworld-rs quickstart as the web service. Download the quickstart from: jboss-eap-quickstarts.
To examine the request-count
metric in the helloworld-rs quickstart:
Enable statistics for the
undertow
subsystem:Start the standalone server with statistics enabled:
$ ./standalone.sh -Dwildfly.statistics-enabled=true
For an already running server, enable the statistics for the
undertow
subsystem:/subsystem=undertow/:write-attribute(name=statistics-enabled,value=true)
Deploy the helloworld-rs quickstart:
In the root directory of the quickstart, deploy the web application using Maven:
$ mvn clean install wildfly:deploy
Query the
http
endpoint in the CLI using thecurl
command and filter forrequest_count
:$ curl -v http://localhost:9990/metrics | grep request_count
Output:
jboss_undertow_request_count_total{server="default-server",http_listener="default",} 0.0
The attribute value returned is
0.0
.- Access the quickstart, located at http://localhost:8080/helloworld-rs/, in a web browser and click any of the links.
Query the
http
endpoint again from the CLI:$ curl -v http://localhost:9990/metrics | grep request_count
Output:
jboss_undertow_request_count_total{server="default-server",http_listener="default",} 1.0
The value is updated to
1.0
.You can verify that the request count is updated correctly by repeating the last two steps.
25.4.3. Configure MicroProfile Metrics using the Management Console
In the management console, you can perform the following configurations:
- Enable or disable exposing metrics.
- Edit prefix for the exposed metrics.
- Enable or disable security.
- Reset non-required fields to initial or default values.
To configure the MicroProfile metrics using the management console:
- Access the management console and navigate to Configuration → Subsystems → MicroProfile Metrics and click View to open the MicroProfile Metrics page.
25.4.4. Enable Authentication for the HTTP Endpoint
The metrics
context, and all subcontexts, can be configured to require that users be authorized to access the context. The following procedure enables authentication on this endpoint.
Set the
security-enabled
attribute totrue
on themicroprofile-metrics-smallrye
subsystem./subsystem=microprofile-metrics-smallrye:write-attribute(name=security-enabled,value=true)
Reload the server for the changes to take effect.
reload
Any subsequent attempts to access the metrics
endpoint will now result in an authentication prompt.