Chapter 3. Administer MicroProfile in JBoss EAP 3.1. MicroProfile OpenTracing administration Important If you see duplicate traces exported for REST calls, disable the microprofile-opentracing-smallrye subsystem. For information about disabling the microprofile-opentracing-smallrye , see Removing the microprofile-opentracing-smallrye subsystem . 3.1.1. Enabling MicroProfile Open Tracing Use the following management CLI commands to enable the MicroProfile Open Tracing feature globally for the server instance by adding the subsystem to the server configuration. Procedure Enable the microprofile-opentracing-smallrye subsystem using the following management command: Reload the server for the changes to take effect. 3.1.2. Removing the microprofile-opentracing-smallrye subsystem The microprofile-opentracing-smallrye subsystem is included in the default JBoss EAP 7.4 configuration. This subsystem provides MicroProfile OpenTracing functionality for JBoss EAP 7.4. If you experience system memory or performance degradation with MicroProfile OpenTracing enabled, you might want to disable the microprofile-opentracing-smallrye subsystem. You can use the remove operation in the management CLI to disable the MicroProfile OpenTracing feature globally for a given server. Procedure Remove the microprofile-opentracing-smallrye subsystem. Reload the server for the changes to take effect. 3.1.3. Installing Jaeger Install Jaeger using docker . Prerequisites docker is installed. Procedure Install Jaeger using docker by issuing the following command in CLI: 3.2. MicroProfile Config configuration 3.2.1. Adding properties in a ConfigSource management resource You can store properties directly in a config-source subsystem as a management resource. Procedure Create a ConfigSource and add a property: 3.2.2. Configuring directories as ConfigSources When a property is stored in a directory as a file, the file-name is the name of a property and the file content is the value of the property. Procedure Create a directory where you want to store the files: Navigate to the directory: Create a file name to store the value for the property name : Add the value of the property to the file: Create a ConfigSource in which the file name is the property and the file contents the value of the property: This results in the following XML configuration: <subsystem xmlns="urn:wildfly:microprofile-config-smallrye:1.0"> <config-source name="file-props"> <dir path="/etc/config/prop-files"/> </config-source> </subsystem> 3.2.3. Obtaining ConfigSource 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. Procedure 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 . If you want to use a ConfigSource from the org.example module, add the <module name="org.eclipse.microprofile.config.api"/> dependency to the path/to/org/example/main/module.xml file. 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 the custom org.eclipse.microprofile.config.spi.ConfigSource implementation class are available to any JBoss EAP deployment. 3.2.4. Obtaining ConfigSource configuration 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. Procedure Create a config-source-provider : The command creates a config-source-provider for the implementation class named org.example.MyConfigSourceProvider that is provided by a JBoss Module named org.example . If you want to use a config-source-provider from the org.example module, add the <module name="org.eclipse.microprofile.config.api"/> dependency to the path/to/org/example/main/module.xml file. 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. Additional resources For information about how to add a global module to the JBoss EAP server, see Define Global Modules in the Configuration Guide for JBoss EAP. 3.3. MicroProfile Fault Tolerance configuration 3.3.1. Adding the MicroProfile Fault Tolerance extension The MicroProfile Fault Tolerance extension is included in standalone-microprofile.xml and standalone-microprofile-ha.xml configurations that are provided as part of JBoss EAP XP. The extension is not included in the standard standalone.xml configuration. To use the extension, you must manually enable it. Prerequisites EAP XP pack is installed. Procedure Add the MicroProfile Fault Tolerance extension using the following management CLI command: Enable the microprofile-fault-tolerance-smallrye subsystem using the following managenent command: Reload the server with the following management command: 3.4. MicroProfile Health configuration 3.4.1. Examining health using the management CLI You can check system health using the management CLI. Procedure Examine health: 3.4.2. Examining health using the management console You can check system health using the management console. A check runtime operation shows the health checks and the global outcome as boolean value. Procedure Navigate to the Runtime tab and select the server. In the Monitor column, click MicroProfile Health View . 3.4.3. Examining health using the HTTP endpoint Health check is automatically deployed to the health context on JBoss EAP, so you can obtain the current health using the HTTP endpoint. The default address for the /health endpoint, accessible from the management interface, is http://127.0.0.1:9990/health . Procedure To obtain the current health of the server using the HTTP endpoint, use the following URL:. Accessing this context displays the health check in JSON format, indicating if the server is healthy. 3.4.4. Enabling authentication for MicroProfile Health You can configure the health context to require authentication for access. Procedure Set the security-enabled attribute to true on the microprofile-health-smallrye subsystem. Reload the server for the changes to take effect. Any subsequent attempt to access the /health endpoint triggers an authentication prompt. 3.4.5. Readiness probes that determine server health and readiness JBoss EAP XP 4.0.0 supports three readiness probes to determine server health and readiness. server-status - returns UP when the server-state is running . boot-errors - returns UP when the probe detects no boot errors. deployment-status - returns UP when the status for all deployments is OK . These readiness probes are enabled by default. You can disable the probes using the MicroProfile Config property mp.health.disable-default-procedures . The following example illustrates the use of the three probes with the check operation: Additional resources MicroProfile Health in JBoss EAP Global status when probes are not defined 3.4.6. Global status when probes are not defined The :empty-readiness-checks-status , :empty-liveness-checks-status , and :empty-startup-checks-status management attributes specify the global status when no readiness , liveness , or startup probes are defined. These attributes allow applications to report 'DOWN' until their probes verify that the application is ready, live, or started up. By default, applications report 'UP'. The :empty-readiness-checks-status attribute specifies the global status for readiness probes if no readiness probes have been defined: The :empty-liveness-checks-status attribute specifies the global status for liveness probes if no liveness probes have been defined: The :empty-startup-checks-status attribute specifies the global status for startup probes if no startup probes have been defined: The /health HTTP endpoint and the :check operation that check readiness , liveness , and startup probes also take into account these attributes. You can also modify these attributes as shown in the following example: 3.5. MicroProfile JWT configuration 3.5.1. Enabling microprofile-jwt-smallrye subsystem The MicroProfile JWT integration is provided by the microprofile-jwt-smallrye subsystem and is included in the default configuration. If the subsystem is not present in the default configuration, you can add it as follows. Prerequisites EAP XP is installed. Procedure Enable the MicroProfile JWT smallrye extension in JBoss EAP: Enable the microprofile-jwt-smallrye subsystem: Reload the server: The microprofile-jwt-smallrye subsystem is enabled. 3.6. MicroProfile Metrics administration 3.6.1. Metrics available on the management interface The JBoss EAP subsystem metrics are exposed in Prometheus format. Metrics are automatically available on the JBoss EAP management interface, with the following contexts: /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 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 identifies JBoss EAP as the source of the metrics. 3.6.2. Examining metrics using the HTTP endpoint Examine the metrics that are available on the JBoss EAP management interface using the HTTP endpoint. Procedure Use the curl command: 3.6.3. Enabling Authentication for the MicroProfile Metrics HTTP Endpoint Configure the metrics context to require users to be authorized to access the context. This configuration extends to all the subcontexts of the metrics context. Procedure Set the security-enabled attribute to true on the microprofile-metrics-smallrye subsystem. Reload the server for the changes to take effect. Any subsequent attempt to access the metrics endpoint results in an authentication prompt. 3.6.4. Obtaining the request count for a web service Obtain the request count for a web service that exposes its request count metric. The following procedure uses helloworld-rs quickstart as the web service for obtaining request count. The quickstart is available at Download the quickstart from: jboss-eap-quickstarts . Prerequsites The web service exposes request count. Procedure Enable statistics for the undertow subsystem: Start the standalone server with statistics enabled: For an already running server, enable the statistics for the undertow subsystem: Deploy the helloworld-rs quickstart: In the root directory of the quickstart, deploy the web application using Maven: Query the HTTP endpoint in the CLI using the curl command and filter for request_count : Expected output: 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 from the CLI again: Expected output: The value is updated to 1.0 . Repeat the last two steps to verify that the request count is updated. 3.7. MicroProfile OpenAPI administration 3.7.1. Enabling MicroProfile OpenAPI The microprofile-openapi-smallrye subsystem is provided in the standalone-microprofile.xml configuration. However, JBoss EAP XP uses the standalone.xml by default. You must include the subsystem in standalone.xml to use it. Alternatively, you can follow the procedure Updating standalone configurations with MicroProfile subsystems and extensions to update the standalone.xml configuration file. Procedure Enable the MicroProfile OpenAPI smallrye extension in JBoss EAP: Enable the microprofile-openapi-smallrye subsystem using the following management command: Reload the server. The microprofile-openapi-smallrye subsystem is enabled. 3.7.2. Requesting an MicroProfile OpenAPI document using Accept HTTP header Request an MicroProfile OpenAPI document, in the JSON format, from a deployment using an Accept HTTP header. By default, the OpenAPI endpoint returns a YAML document. Prerequisites The deployment being queried is configured to return an MicroProfile OpenAPI document. Procedure Issue the following curl command to query the /openapi endpoint of the deployment: Replace http://localhost:8080 with the URL and port of the deployment. The Accept header indicates that the JSON document is to be returned using the application/json string. 3.7.3. Requesting an MicroProfile OpenAPI document using an HTTP parameter Request an MicroProfile OpenAPI document, in the JSON format, from a deployment using a query parameter in an HTTP request. By default, the OpenAPI endpoint returns a YAML document. Prerequisites The deployment being queried is configured to return an MicroProfile OpenAPI document. Procedure Issue the following curl command to query the /openapi endpoint of the deployment: Replace http://localhost:8080 with the URL and port of the deployment. The HTTP parameter format=JSON indicates that JSON document is to be returned. 3.7.4. Configuring JBoss EAP to serve a static OpenAPI document Configure JBoss EAP to serve a static OpenAPI document that describes the REST services for the host. When JBoss EAP is configured to serve a static OpenAPI document, the static OpenAPI document is processed before any Jakarta RESTful Web Services and MicroProfile OpenAPI annotations. In a production environment, disable annotation processing when serving a static document. Disabling annotation processing ensures that an immutable and versioned API contract is available for clients. Procedure Create a directory in the application source tree: APPLICATION_ROOT is the directory containing the pom.xml configuration file for the application. Query the OpenAPI endpoint, redirecting the output to a file: By default, the endpoint serves a YAML document, format=JSON specifies that a JSON document is returned. Configure the application to skip annotation scanning when processing the OpenAPI document model: Rebuild the application: Deploy the application again using the following management CLI commands: Undeploy the application: Deploy the application: JBoss EAP now serves a static OpenAPI document at the OpenAPI endpoint. 3.7.5. Disabling microprofile-openapi-smallrye You can disable the microprofile-openapi-smallrye subsystem in JBoss EAP XP using the management CLI. Procedure Disable the microprofile-openapi-smallrye subsystem: 3.8. MicroProfile Reactive Messaging administration 3.8.1. Configuring the required MicroProfile reactive messaging extension and subsystem for JBoss EAP If you want to enable asynchronous reactive messaging to your instance of JBoss EAP, you must add its extension through the JBoss EAP management CLI. Prerequisites You added the Reactive Streams Operators with SmallRye extension and subsystem. For more information, see MicroProfile Reactive Streams Operators Subsystem Configuration: Required Extension . You added the Reactive Messaging with SmallRye extension and subsystem. Procedure Open the JBoss EAP management CLI. Enter the following code: Note If you provision a server using Galleon, either on OpenShift or not, make sure you include the microprofile-reactive-messaging Galleon layer to get the core MicroProfile 2.0.1 and reactive messaging functionality, and to enable the required subsystems and extensions. Note that this configuration does not contain the JBoss EAP modules you need to enable Kafka connector functionality. To do this, use the microprofile-reactive-messaging-kafka layer. Verification You have successfully added the required MicroProfile Reactive Messaging extension and subsystem for JBoss EAP if you see success in two places in the resulting code in the management CLI. Tip If the resulting code says reload-required , you have to reload your server configuration to completely apply all of your changes. To reload, in a standalone server CLI, enter reload . 3.9. Standalone server configuration 3.9.1. Standalone server configuration files The JBoss EAP XP includes additional standalone server configuration files, standalone-microprofile.xml and standalone-microprofile-ha.xml . Standard configuration files that are included with JBoss EAP remain unchanged. Note that JBoss EAP XP 4.0.0 does not support the use of domain.xml files or domain mode. Table 3.1. Standalone configuration files available in JBoss EAP XP Configuration File Purpose Included capabilities Excluded capabilities standalone.xml This is the default configuration that is used when you start your standalone server. Includes information about the server, including subsystems, networking, deployments, socket bindings, and other configurable details. Excludes subsystems necessary for messaging or high availability. standalone-microprofile.xml This configuration file supports applications that use MicroProfile. Includes information about the server, including subsystems, networking, deployments, socket bindings, and other configurable details. Excludes the following capabilities: Jakarta Enterprise Beans Messaging Jakarta EE Batch Jakarta Server Faces Jakarta Enterprise Beans timers standalone-ha.xml Includes default subsystems and adds the modcluster and jgroups subsystems for high availability. Excludes subsystems necessary for messaging. standalone-microprofile-ha.xml This standalone file supports applications that use MicroProfile. Includes the modcluster and jgroups subsystems for high availability in addition to default subsystems. Excludes subsystems necessary for messaging. standalone-full.xml Includes the messaging-activemq and iiop-openjdk subsystems in addition to default subsystems. standalone-full-ha.xml Support for every possible subsystem. Includes subsystems for messaging and high availability in addition to default subsystems. standalone-load-balancer.xml Support for the minimum subsystems necessary to use the built-in mod_cluster front-end load balancer to load balance other JBoss EAP instances. By default, starting JBoss EAP as a standalone server uses the standalone.xml file. To start JBoss EAP with a standalone MicroProfile configuration, use the -c argument. For example, Additional Resources Starting and Stopping JBoss EAP Configuration Data 3.9.2. Updating standalone configurations with MicroProfile subsystems and extensions You can update standard standalone server configuration files with MicroProfile subsystems and extensions using the docs/examples/enable-microprofile.cli script. The enable-microprofile.cli script is intended as an example script for updating standard standalone server configuration files, not custom configurations. The enable-microprofile.cli script modifies the existing standalone server configuration and adds the following MicroProfile subsystems and extensions if they do not exist in the standalone configuration file: microprofile-config-smallrye microprofile-fault-tolerance-smallrye microprofile-health-smallrye microprofile-jwt-smallrye microprofile-metrics-smallrye microprofile-openapi-smallrye microprofile-opentracing-smallrye The enable-microprofile.cli script outputs a high-level description of the modifications. The configuration is secured using the elytron subsystem. The security subsystem, if present, is removed from the configuration. Prerequisites JBoss EAP XP is installed. Procedure Run the following CLI script to update the default standalone.xml server configuration file: Select a standalone server configuration other than the default standalone.xml server configuration file using the following command: The specified configuration file now includes MicroProfile subsystems and extensions.

Commands:
/subsystem=microprofile-opentracing-smallrye:add()
reload
/subsystem=microprofile-opentracing-smallrye:remove()
reload
docker run -d --name jaeger -p 6831:6831/udp -p 5778:5778 -p 14268:14268 -p 16686:16686 jaegertracing/all-in-one:1.16
/subsystem=microprofile-config-smallrye/config-source=props:add(properties={"name" = "jim"})
mkdir -p ~/config/prop-files/
cd ~/config/prop-files/
touch name
echo "jim" > name
/subsystem=microprofile-config-smallrye/config-source=file-props:add(dir={path=~/config/prop-files})
<subsystem xmlns="urn:wildfly:microprofile-config-smallrye:1.0"> <config-source name="file-props"> <dir path="/etc/config/prop-files"/> </config-source> </subsystem>
/subsystem=microprofile-config-smallrye/config-source=my-config-source:add(class={name=org.example.MyConfigSource, module=org.example})
<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>
/subsystem=microprofile-config-smallrye/config-source-provider=my-config-source-provider:add(class={name=org.example.MyConfigSourceProvider, module=org.example})
<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>
/extension=org.wildfly.extension.microprofile.fault-tolerance-smallrye:add
/subsystem=microprofile-fault-tolerance-smallrye:add
reload
/subsystem=microprofile-health-smallrye:check { "outcome" => "success", "result" => { "status" => "UP", "checks" => [] } }
http:// <host> : <port> /health
/subsystem=microprofile-health-smallrye:write-attribute(name=security-enabled,value=true)
reload
[standalone@localhost:9990 /] /subsystem=microprofile-health-smallrye:check { "outcome" => "success", "result" => { "status" => "UP", "checks" => [ { "name" => "boot-errors", "status" => "UP" }, { "name" => "server-state", "status" => "UP", "data" => {"value" => "running"} }, { "name" => "empty-readiness-checks", "status" => "UP" }, { "name" => "deployments-status", "status" => "UP" }, { "name" => "empty-liveness-checks", "status" => "UP" }, { "name" => "empty-startup-checks", "status" => "UP" } ] } }
/subsystem=microprofile-health-smallrye:read-attribute(name=empty-readiness-checks-status) { "outcome" => "success", "result" => expression "USD{env.MP_HEALTH_EMPTY_READINESS_CHECKS_STATUS:UP}" }
/subsystem=microprofile-health-smallrye:read-attribute(name=empty-liveness-checks-status) { "outcome" => "success", "result" => expression "USD{env.MP_HEALTH_EMPTY_LIVENESS_CHECKS_STATUS:UP}" }
/subsystem=microprofile-health-smallrye:read-attribute(name=empty-startup-checks-status) { "outcome" => "success", "result" => expression "USD{env.MP_HEALTH_EMPTY_STARTUP_CHECKS_STATUS:UP}" }
/subsystem=microprofile-health-smallrye:write-attribute(name=empty-readiness-checks-status,value=DOWN) { "outcome" => "success", "response-headers" => { "operation-requires-reload" => true, "process-state" => "reload-required" } }
/extension=org.wildfly.extension.microprofile.jwt-smallrye:add
/subsystem=microprofile-jwt-smallrye:add
reload
curl -v http://localhost:9990/metrics | grep -i type
/subsystem=microprofile-metrics-smallrye:write-attribute(name=security-enabled,value=true)
reload
./standalone.sh -Dwildfly.statistics-enabled=true
/subsystem=undertow:write-attribute(name=statistics-enabled,value=true)
mvn clean install wildfly:deploy
curl -v http://localhost:9990/metrics | grep request_count
jboss_undertow_request_count_total{server="default-server",http_listener="default",} 0.0
curl -v http://localhost:9990/metrics | grep request_count
jboss_undertow_request_count_total{server="default-server",http_listener="default",} 1.0
/extension=org.wildfly.extension.microprofile.openapi-smallrye:add()
/subsystem=microprofile-openapi-smallrye:add()
reload
curl -v -H'Accept: application/json' http://localhost:8080 /openapi < HTTP/1.1 200 OK {"openapi": "3.0.1" ... }
curl -v http://localhost:8080 /openapi?format=JSON < HTTP/1.1 200 OK
mkdir APPLICATION_ROOT /src/main/webapp/META-INF
curl http://localhost:8080/openapi?format=JSON > src/main/webapp/META-INF/openapi.json
echo "mp.openapi.scan.disable=true" > APPLICATION_ROOT /src/main/webapp/META-INF/microprofile-config.properties
mvn clean install
undeploy microprofile-openapi.war
deploy APPLICATION_ROOT /target/microprofile-openapi.war
/subsystem=microprofile-openapi-smallrye:remove()
[standalone@localhost:9990 /] /extension=org.wildfly.extension.microprofile.reactive-messaging-smallrye:add {"outcome" => "success"} [standalone@localhost:9990 /] /subsystem=microprofile-reactive-messaging-smallrye:add { "outcome" => "success", "response-headers" => { "operation-requires-reload" => true, "process-state" => "reload-required" } }
EAP_HOME /bin/standalone.sh -c=standalone-microprofile.xml
EAP_HOME /bin/jboss-cli.sh --file=docs/examples/enable-microprofile.cli
EAP_HOME /bin/jboss-cli.sh --file=docs/examples/enable-microprofile.cli -Dconfig=<standalone-full.xml|standalone-ha.xml|standalone-full-ha.xml>