Chapter 3. Administer MicroProfile in JBoss EAP
3.1. MicroProfile OpenTracing administration
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:/subsystem=microprofile-opentracing-smallrye:add()
Reload the server for the changes to take effect.
reload
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./subsystem=microprofile-opentracing-smallrye:remove()
Reload the server for the changes to take effect.
reload
3.1.3. Adding the microprofile-opentracing-smallrye
subsystem
You can enable the microprofile-opentracing-smallrye
subsystem by adding it to the server configuration. Use the add
operation in the management CLI to enable the MicroProfile OpenTracing feature globally for a given the server.
Procedure
Add the subsystem.
/subsystem=microprofile-opentracing-smallrye:add()
Reload the server for the changes to take effect.
reload
3.1.4. Installing Jaeger
Install Jaeger using docker
.
Prerequisites
-
docker
is installed.
Procedure
Install Jaeger using
docker
by issuing the following command in CLI:$ docker run -d --name jaeger -p 6831:6831/udp -p 5778:5778 -p 14268:14268 -p 16686:16686 jaegertracing/all-in-one:1.16
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:
/subsystem=microprofile-config-smallrye/config-source=props:add(properties={"name" = "jim"})
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:
$ mkdir -p ~/config/prop-files/
Navigate to the directory:
$ cd ~/config/prop-files/
Create a file
name
to store the value for the propertyname
:$ touch name
Add the value of the property to the file:
$ echo "jim" > name
Create a ConfigSource in which the file name is the property and the file contents the value of the property:
/subsystem=microprofile-config-smallrye/config-source=file-props:add(dir={path=~/config/prop-files})
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 namedorg.example.MyConfigSource
that is provided by a JBoss module namedorg.example
.If you want to use a
ConfigSource
from theorg.example
module, add the<module name="org.eclipse.microprofile.config.api"/>
dependency to thepath/to/org/example/main/module.xml
file./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 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
:/subsystem=microprofile-config-smallrye/config-source-provider=my-config-source-provider:add(class={name=org.example.MyConfigSourceProvider, module=org.example})
The command creates a
config-source-provider
for the implementation class namedorg.example.MyConfigSourceProvider
that is provided by a JBoss Module namedorg.example
.If you want to use a
config-source-provider
from theorg.example
module, add the<module name="org.eclipse.microprofile.config.api"/>
dependency to thepath/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:
/extension=org.wildfly.extension.microprofile.fault-tolerance-smallrye:add
Enable the
microprofile-fault-tolerance-smallrye
subsystem using the following managenent command:/subsystem=microprofile-fault-tolerance-smallrye:add
Reload the server with the following management command:
reload
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:
/subsystem=microprofile-health-smallrye:check { "outcome" => "success", "result" => { "status" => "UP", "checks" => [] } }
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:.
http://<host>:<port>/health
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 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 attempt to access the /health
endpoint triggers an authentication prompt.
3.4.5. Readiness probes that determine server health and readiness
JBoss EAP XP 3.0.0 supports three readiness probes to determine server health and readiness.
-
server-status
- returnsUP
when the server-state isrunning
. -
boot-errors
- returnsUP
when the probe detects no boot errors. -
deployment-status
- returnsUP
when the status for all deployments isOK
.
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:
[standalone@localhost:9990 /] /subsystem=microprofile-health-smallrye:check { "checks": [ { "name": "empty-readiness-checks", "status": "UP" }, { "name": "empty-liveness-checks", "status": "UP" }, { "data": { "value": "running" }, "name": "server-state", "status": "UP" }, { "name": "deployments-status", "status": "UP" }, { "name": "boot-errors", "status": "UP" } ], "status": "UP" }
Additional resources
3.4.6. Global status when probes are not defined
The :empty-readiness-checks-status
and :empty-liveness-checks-status
management attributes 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 or live. By default, applications 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 forliveness
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 the:check
operation that check bothreadiness
andliveness
probes also take into account these attributes.
You can also modify these attributes as shown in the following example:
/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" } }
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:
/extension=org.wildfly.extension.microprofile.jwt-smallrye:add
Enable the
microprofile-jwt-smallrye
subsystem:/subsystem=microprofile-jwt-smallrye:add
Reload the server:
reload
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:
$ curl -v http://localhost:9990/metrics | grep -i type
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 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 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:
$ ./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 the
curl
command and filter forrequest_count
:$ curl -v http://localhost:9990/metrics | grep request_count
Expected 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 from the CLI again:
$ curl -v http://localhost:9990/metrics | grep request_count
Expected output:
jboss_undertow_request_count_total{server="default-server",http_listener="default",} 1.0
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:
/extension=org.wildfly.extension.microprofile.openapi-smallrye:add()
Enable the
microprofile-openapi-smallrye
subsystem using the following management command:/subsystem=microprofile-openapi-smallrye:add()
Reload the server.
reload
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:$ curl -v -H'Accept: application/json' http://localhost:8080/openapi < HTTP/1.1 200 OK ... {"openapi": "3.0.1" ... }
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:$ curl -v http://localhost:8080/openapi?format=JSON < HTTP/1.1 200 OK ...
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:
$ mkdir APPLICATION_ROOT/src/main/webapp/META-INF
APPLICATION_ROOT is the directory containing the
pom.xml
configuration file for the application.Query the OpenAPI endpoint, redirecting the output to a file:
$ curl http://localhost:8080/openapi?format=JSON > src/main/webapp/META-INF/openapi.json
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:
$ echo "mp.openapi.scan.disable=true" > APPLICATION_ROOT/src/main/webapp/META-INF/microprofile-config.properties
Rebuild the application:
$ mvn clean install
Deploy the application again using the following management CLI commands:
Undeploy the application:
undeploy microprofile-openapi.war
Deploy the application:
deploy APPLICATION_ROOT/target/microprofile-openapi.war
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:/subsystem=microprofile-openapi-smallrye:remove()
3.8. Standalone server configuration
3.8.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 3.0.0 does not support the use of domain.xml
files or domain mode.
Configuration File | Purpose | Included capabilities | Excluded capabilities |
---|---|---|---|
| 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. |
| 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:
|
|
Includes default subsystems and adds the | Excludes subsystems necessary for messaging. | |
| This standalone file supports applications that use MicroProfile. |
Includes the | Excludes subsystems necessary for messaging. |
|
Includes the | ||
| Support for every possible subsystem. | Includes subsystems for messaging and high availability in addition to default subsystems. | |
| 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,
$ EAP_HOME/bin/standalone.sh -c=standalone-microprofile.xml
Additional Resources
3.8.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-openapi-smallrye
-
microprofile-jwt-smallrye
-
microprofile-fault-tolerance-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:$ EAP_HOME/bin/jboss-cli.sh --file=docs/examples/enable-microprofile.cli
Select a standalone server configuration other than the default
standalone.xml
server configuration file using the following command:$ EAP_HOME/bin/jboss-cli.sh --file=docs/examples/enable-microprofile.cli -Dconfig=<standalone-full.xml|standalone-ha.xml|standalone-full-ha.xml>
- The specified configuration file now includes MicroProfile subsystems and extensions.