Chapter 25. Eclipse MicroProfile

25.1. Using Eclipse MicroProfile Config to Manage Configuration

Important

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

Note

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 ConfigurationSubsystemsMicroProfile 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 value 5.
  • num.max: This file contains the value 100.

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

Important

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 JAX-RS 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.1, which includes support for tracing requests to JAX-RS endpoints and CDI beans and is included in the default JBoss EAP 7.2 configuration.

The microprofile-opentracing-smallrye subsystem ships with the Jaeger Java Client as the default tracer, plus a set of instrumentation libraries for components commonly used in Java EE applications, such as JAX-RS and CDI. 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.2 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.

  1. Remove the subsystem.

    /subsystem=microprofile-opentracing-smallrye:remove()
  2. 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.

  1. Add the subsystem.

    /subsystem=microprofile-opentracing-smallrye:add()
  2. 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.

Important

Because this feature is provided as Technology Preview, the current configuration options, particularly those related to configuring the Jaeger Java 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 Java 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

Important

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. About the 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 if the JBoss EAP instance is responding as expected, and is enabled by default.

Important

By default, the MicroProfile Health SmallRye subsystem only examines if the server is running. To include custom health checks, see the Implement a Custom Health Check section in the Development Guide.

25.3.2. Examine the Health Check Using the Management CLI

Health checks can be examined using the management CLI. The following command demonstrates obtaining the current health of the server.

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

25.3.3. 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:PORT/health

Accessing this context displays the health check in JSON format, indicating if the server is healthy.

Enable Authentication for the HTTP Endpoint

The health context can be configured to require that users be authorized to access the context. The following procedure enables authentication on this endpoint.

  1. Set the security-enabled attribute to true on the microprofile-health-smallrye subsystem.

    /subsystem=microprofile-health-smallrye:write-attribute(name=security-enabled,value=true)
  2. Reload the server for the changes to take effect.

    reload

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