Chapter 25. Eclipse MicroProfile

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.

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.

The microprofile-config-smallrye subsystem supports the following additional types of ConfigSource resources for retrieving configuration values.

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:

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.

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.

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.

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.

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.

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.

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.

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.

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.

Microprofile Health is only available when running JBoss EAP as a standalone server.

Health checks can be examined using the management CLI.

/subsystem=microprofile-health-smallrye:check
{
    "outcome" => "success",
    "result" => {
        "outcome" => "UP",
        "checks" => []
    }
}

/subsystem=microprofile-health-smallrye:check-live
{
    "outcome" => "success",
    "result" => {
        "outcome" => "UP",
        "checks" => []
    }
}

/subsystem=microprofile-health-smallrye:check-ready
{
    "outcome" => "success",
    "result" => {
        "outcome" => "UP",
        "checks" => []
    }
}

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:

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

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.

http://HOST:9990/health/live

http://HOST:9990/health/ready

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

/subsystem=microprofile-health-smallrye:read-attribute(name=empty-readiness-checks-status)
{
    "outcome" => "success",
    "result" => expression "${env.MP_HEALTH_EMPTY_READINESS_CHECKS_STATUS:UP}"
}

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

The health context can be configured to require that users be authorized to access the context.

To enable authentication on this endpoint:

Any subsequent attempts to access the health endpoint result in an authentication prompt.

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.

Metrics are automatically available on the JBoss EAP management interface, with the following contexts available.

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

To examine the request-count metric in the helloworld-rs quickstart:

In the management console, you can perform the following configurations:

To configure the MicroProfile metrics using the management console:

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.

Any subsequent attempts to access the metrics endpoint will now result in an authentication prompt.