Monitor

Configuration

To use the monitor fraction in your application, you need to add the following dependency:

<dependency>
    <groupId>org.wildfly.swarm</groupId>
    <artifactId>microprofile-health</artifactId>
</dependency>

Node Status

The monitoring fraction provides access to the runtime status on each node. The runtime information is exposed through a HTTP interface and gives access following information:

WebContext Description Content-Type

/node

Node specific identifiers and overall runtime status (i.e. reload and suspend states)

application/json

 

{
      "name" : "macbook-pro-thomas",
      "server-state" : "running",
      "suspend-state" : "RUNNING",
      "running-mode" : "NORMAL",
      "uuid" : "a8100296-573d-4b40-9648-e82bdb0041d9",
      "swarm-version" : "2018.3.0"
}

/heap

The JVM heap usage

application/json

 

{
    "heap-memory-usage" : {
        "init" : 268435456,
        "used" : 56067784,
        "committed" : 356515840,
        "max" : 3817865216
    },
    "non-heap-memory-usage" : {
        "init" : 2555904,
        "used" : 52717328,
        "committed" : 57622528,
        "max" : -1
    }
}

/threads

The JVM thread usage

application/json

 

{
    "thread-count" : 33,
    "peak-thread-count" : 47,
    "total-started-thread-count" : 49,
    "current-thread-cpu-time" : 66855000,
    "current-thread-user-time" : 64003000
}

/health

A list of available health endpoints

application/json

 

{
  "outcome": "UP",
  "checks": []
}

Health Check API

Health checks are implemented using regular JAX-RS API and exposing certain GET methods through the @Health annotation. Health check responses are expressed using the HealthStatus and CompositeHealthStatus API’s. Any health status response type will automatically converted to an application/json response content type and the HTTP status derived from the HealthStatus.<UP|DOWN> states:

package org.wildfly.swarm.examples.jaxrs.health;

import java.io.File;

import javax.ws.rs.GET;
import javax.ws.rs.Path;

import org.wildfly.swarm.monitor.Health;
import org.wildfly.swarm.monitor.HealthStatus;

@Path("/app")
public class HealthCheckResource {

    @GET
    @Path("/diskSpace")
    @Health
    public HealthStatus checkDiskspace() {
        File path = new File(".");
        long freeBytes = path.getFreeSpace();
        long threshold = 1024 * 1024 * 100; // 100mb
        return freeBytes>threshold ? HealthStatus.up() : HealthStatus.down().withAttribute("freebytes", freeBytes);
    }

    @GET
    @Path("/other")
    @Health(inheritSecurity = false)
    public HealthStatus checkSomethingElse() {
        return HealthStatus.up();
    }

}

Accessing the above endpoint will return a json encoded response like this:

curl --digest -u "<user>:<pass>" http://localhost:8080/health/app/diskSpace

{
    "freebytes": "1234567890"
}

Health Check HTTP Endpoints

Health checks (i.e. to integrate with external service registries) can be added by implementing JAX-RS endpoints and declaring them as a health endpoints through the use of the '@Health' annotation. Any GET method annotated with @Health will be accessible through /health/<subresource>

For instance if you provide an HTTP endpoint for /app/diskSpace, then it will be listed under /health and accessible through /health/app/diskSpace

curl http://localhost:8080/health

{
  "links": [
      "/health/app/diskSpace"
  ]
}

Secure access to @Health endpoints

In order to secure access to the HTTP endpoints you’ll need to include the 'management' fraction and configure a security realm. See Security Realms for further information.

Usually the security for the endpoints behind '/health' will be inherited. (i.e. the security realm settings you configured) But you can override this policy with @Health(inheritSecurity=false).

If security is inherited, then the JAX-RS endpoint annotated with @Health will not be directly accessible directly anymore (yields HTTP 403). If you don’t inherit the security, it’s up to your responsibility to secure the endpoint (or leave it unprotected) .

The combinations of using the @Health annotations with regard to the possible HTTP requests are outlined in the table below:

Request path @Health Annotation Outcome

/health

irrelevant

Any HTTP will require authentication, if the 'ManagementRealm' is configured. If you don’t configure a security realm this endpoint will not require authentication to access it. The @Health secure attribute is not relevant in this case.

/foo/bar/health

inheritSecurity=true

Any direct HTTP request to this endpoint will receive a 403 response.

/foo/bar/health

inheritSecurity=false

Any direct HTTP request to this endpoint will be passed through. Security for this endpoint is an obligation of the developer.