[[MicroProfile_Health_SmallRye]]
= MicroProfile Health Subsystem Configuration

Support for https://microprofile.io/project/eclipse/microprofile-health[MicroProfile Health] is provided by
 the _microprofile-health-smallrye_ subsystem.

[[required-extension-microprofile-health-smallrye]]
== Required Extension

This extension is included in the standalone-microprofile configurations included in the
WildFly distribution.

You can also add the extension to a configuration without it either by adding
an `<extension module="org.wildfly.extension.microprofile.health-smallrye"/>`
element to the xml or by using the following CLI operation:

[source,options="nowrap"]
----
[standalone@localhost:9990 /]/extension=org.wildfly.extension.microprofile.health-smallrye:add
----

It depends on the base health extension `org.wildfly.extension.health` that must be installed.

== Management Operations

The healthiness of the application server can be queried by calling 3 different operations:

* `check` to check both the liveness and readiness of the runtime
* `check-live` to check only the liveness of the runtime
* `check-ready` to check only the readiness of the runtime


[source,options="nowrap"]
----
[standalone@localhost:9990 /] /subsystem=microprofile-health-smallrye:check
{
    "outcome" => "success",
    "result" => {
        "status" => "UP",
        "checks" => [
            {
                "name" => "empty-liveness-checks",
                "status" => "UP"
            },
            {
                "name" => "server-state",
                "status" => "UP",
                "data" => {"value" => "running"}
            },
            {
                "name" => "boot-errors",
                "status" => "UP"
            },
            {
                "name" => "deployments-status",
                "status" => "UP"
            },
            {
                "name" => "empty-readiness-checks",
                "status" => "UP"
            }
        ]
    }
}
----
<1> this `outcome` means that the management operation is successful
<2> this `outcome` corresponds to the health check, `UP` if the application server is healthy, `DOWN` else.

== HTTP Endpoints

The MicroProfile Health Check specifications defines three HTTP endpoints:

* `/health` to test both the liveness and readiness of the application server.
* `/health/live` to test the liveness of the application server
* `/health/ready` to test the readiness of the application server.

The Health HTTP endpoints are accessible on WildFly HTTP management interface (e.g. http://localhost:9990/health[http://localhost:9990/health]).

=== Secured Access to the HTTP endpoints

Secured access to the HTTP endpoint is controlled by the `security-enabled` attribute of the `/subsystem=microprofile-health-smallrye` resource.
The value of this attribute will override the `security-enabled` attribute of the `/subsystem=health` resource (documented in <<health-http-endpoint,Health subsystem configuration guide>>).
If it is set to `true`, the HTTP client must be authenticated.

If the application server is healthy, it will return a `200 OK` response:

[source,shell]
----
$ curl -v http://localhost:9990/health
< HTTP/1.1 200 OK
...
{"status":"UP","checks":[{"name":"empty-liveness-checks","status":"UP"},{"name":"server-state","status":"UP","data":{"value":"running"}},{"name":"boot-errors","status":"UP"},{"name":"deployments-status","status":"UP"},{"name":"empty-readiness-checks","status":"UP"}]}
----

If the application server  is not healthy, it returns `503 Service Unavailable`

[source,shell]
----
$ curl -v http://localhost:9990/health
< HTTP/1.1 503 Service Unavailable
...
{"outcome":"DOWN","checks":[{"name":"myFailingProbe","state":"DOWN","data":{"foo":"bar"}}]}
----

=== Secured Access to the HTTP endpoints

Secured access to the HTTP endpoint is controlled by the `security-enabled` attribute of the `/subsystem=microprofile-health-smallrye` resource.
The value of this attribute will override the `security-enabled` attribute of the `/subsystem=health` resource (documented in <<health-http-endpoint,Health subsystem configuration guide>>).
If it is set to `true`, the HTTP client must be authenticated.

If security has been enabled, the HTTP client must pass the credentials corresponding to a management user
created by the `add-user` script. For example:

[source,shell]
----
$ curl -v --digest -u myadminuser:myadminpassword http://localhost:9990/health
< HTTP/1.1 200 OK
...
{"status":"UP","checks":[{"name":"empty-liveness-checks","status":"UP"},{"name":"server-state","status":"UP","data":{"value":"running"}},{"name":"boot-errors","status":"UP"},{"name":"deployments-status","status":"UP"},{"name":"empty-readiness-checks","status":"UP"}]}
----

If the authentication fails, the  server will reply with a `401 NOT AUTHORIZED` response.

=== Default Server Procedures

WildFly provides some readiness procedures that are checked to determine if the application server is ready to serve requests:

* `boot-errors` checks that there were no errors during the server boot sequence
* `deployments-status` checks that all deployments were deployed without errors
* `server-state` checks that the server state is `running`
* `empty-readiness-checks` determines the status when there are no readiness check procedures deployed to the server. The outcome of this procedure is determined by the `empty-readiness-checks-status` attribute. If the attribute is
   `UP` (by default), the server can be ready when there are no readiness checks in the deployments. Setting the `empty-readiness-checks-status` attribute to `DOWN` will make this procedure fail when there are no readiness checks in the deployments.

If a deployment does not provide any readiness checks, WildFly will automatically add one for each deployment (named `ready-<deployment name>`) which always returns `UP`.

[NOTE]
====
This allows applications that does not provide readiness checks to still be able to inform cloud containers when they are ready to serve requests.
Setting empty-readiness-checks-status` to `DOWN` ensures that the server will not be ready until the application is deployed. At that time, the `ready-<deployment name>`
will be added (which returns `UP`) and the `empty-readiness-checks` procedure will no longer be checked as there is no a readiness check procedure provided by the deployment.
====

WildFly also provide a liveness procedure that is checked to determine if the application server is live:

* `empty-liveness-checks` determines the status when there are no liveness check procedures deployed to the server. The outcome of this procedure is determined by the `empty-liveness-checks-status` attribute. If the attribute is
`UP` (by default), the server can be live when there are no liveness checks in the deployments.  Setting the `empty-liveness-checks-status` attribute to `DOWN` will make this procedure fail when there are no liveness checks in the deployments.

It is possible to disable all these server procedures by using the MicroProfile Config property `mp.health.disable-default-procedures`.

[NOTE]
====
The MicroProfile Config property `mp.health.disable-default-procedures` is read at 2 different times:

1. __When the server starts__, to determine if its server procedures should be disabled or enabled. It can be set using the system property `mp.health.disable-default-procedures` or the environment variable `MP_HEALTH_DISABLE_DEFAULT_PROCEDURES`. Setting this property in a deployment is ignored at that time.
2. __When an application is deployed__, to determine if WildFly should add a readiness check if the deployment does not provide any. At that time, setting this property in a `microprofile-config.properties` file in the deployment would be taken into account. (with the usual priority rules for MicroProfile Config properties).
====

== Component Reference

The MicroProfile Health implementation is provided by the SmallRye Health project.

****

* https://microprofile.io/project/eclipse/microprofile-health[MicroProfile Health]
* http://github.com/smallrye/smallrye-health/[SmallRye Health]

****