| = MicroProfile Custom Health Check |
| :index-group: MicroProfile |
| :jbake-type: page |
| :jbake-status: published |
| |
| This is an example of how to use MicroProfile Custom Health Check in TomEE. |
| |
| [discrete] |
| ==== Health Feature |
| |
| Health checks are used to probe the state of services and resources that an application might depend on or even to expose its |
| state, e.g. in a cluster environment, where an unhealthy node needs to be discarded (terminated, shutdown) and eventually |
| replaced by another healthy instance. |
| |
| By default, https://github.com/eclipse/microprofile-health[microprofile-health-api] provides a basic output of a node by |
| simply hitting the endpoint http://host:port/health. |
| |
| [source,json] |
| ---- |
| {"checks":[],"outcome":"UP","status":"UP"} |
| ---- |
| |
| To provide a customized output, Let's say we have an application that uses a Weather API, and if the service becomes |
| unavailable, we should report the service as DOWN. |
| |
| To begin with a customized output, is needed to implement the interface https://github.com/eclipse/microprofile-health/blob/master/api/src/main/java/org/eclipse/microprofile/health/HealthCheck.java[HealthCheck], |
| make the class a managed bean by annotating it with `@ApplicationScoped` plus with `@Health` annotation to active the custom check. |
| See more here https://github.com/apache/geronimo-health/blob/master/geronimo-health/src/main/java/org/apache/geronimo/microprofile/impl/health/cdi/GeronimoHealthExtension.java[GeronimoHealthExtension.java] |
| |
| [source,java] |
| ---- |
| @Health |
| @ApplicationScoped |
| public class WeatherServiceHealthCheck implements HealthCheck { |
| |
| @Inject WeatherGateway weatherGateway; |
| |
| @Override |
| public HealthCheckResponse call() { |
| HealthCheckResponseBuilder responseBuilder = HealthCheckResponse.named("OpenWeatherMap"); |
| try { |
| WeatherApiStatus status = weatherGateway.getApiStatus(); |
| return responseBuilder.withData("weatherServiceApiUrl", status.getUrl()) |
| .withData("weatherServiceApiVersion", status.getVersion()) |
| .withData("weatherServiceMessage", status.getMessage()) |
| .up().build(); |
| } catch (WeatherException e) { |
| return responseBuilder.withData("weatherServiceErrorMessage", e.getMessage()).down().build(); |
| } |
| } |
| } |
| ---- |
| |
| In the example above, the health probe name is https://openweathermap.org/appid[OpenWeatherMap] (_illustrative only_) which provides a |
| subscription plan to access its services and if the limit of calls is exceeded the API becomes unavailable until it's renewed. |
| |
| [discrete] |
| === Examples |
| |
| .Running the application |
| ---- |
| mvn clean install tomee:run |
| ---- |
| |
| [discrete] |
| ==== Example 1 |
| |
| When hitting /health endpoint, OpenWeatherMap tell us that our remaining calls are running out and we should take |
| an action before it gets unavailable. |
| |
| ---- |
| curl http://localhost:8080/mp-custom-healthcheck/health |
| ---- |
| |
| [source,json] |
| ---- |
| { |
| "checks":[ |
| { |
| "data":{ |
| "weatherServiceApiVersion":"2.5", |
| "weatherServiceMessage":"Your account will become unavailable soon due to limitation of your |
| subscription type. Remaining API calls are 1", |
| "weatherServiceApiUrl":"http://api.openweathermap.org/data/2.5/" |
| }, |
| "name":"OpenWeatherMap", |
| "state":"UP" |
| } |
| ], |
| "outcome":"UP", |
| "status":"UP" |
| } |
| ---- |
| |
| [discrete] |
| ==== Example 2 |
| |
| Weather API still working fine. |
| |
| ---- |
| curl http://localhost:8080/mp-custom-healthcheck/weather/day/status |
| ---- |
| |
| [source,text] |
| ---- |
| Hi, today is a sunny day! |
| ---- |
| |
| [discrete] |
| ==== Example 3 |
| |
| When hitting one more time /health endpoint, OpenWeatherMap tell us that our account is temporary blocked and this |
| service is being reported as DOWN. |
| |
| ---- |
| curl http://localhost:8080/mp-custom-healthcheck/health |
| ---- |
| |
| [source,json] |
| ---- |
| { |
| "checks":[ |
| { |
| "data":{ |
| "weatherServiceErrorMessage":"Your account is temporary blocked due to exceeding of |
| requests limitation of your subscription type. Please choose the proper subscription |
| http://openweathermap.org/price" |
| }, |
| "name":"weatherservice", |
| "state":"DOWN" |
| } |
| ], |
| "outcome":"DOWN", |
| "status":"DOWN" |
| } |
| ---- |
| |
| [discrete] |
| ==== Example 4 |
| |
| Weather API has stopped. |
| |
| ---- |
| curl http://localhost:8080/mp-custom-healthcheck/weather/day/status |
| ---- |
| |
| [source,text] |
| ---- |
| Weather Service is unavailable at moment, retry later. |
| ---- |
| |
| [discrete] |
| ===== Running the tests |
| |
| You can also try it out using the link:src/test/java/org/superbiz/rest/WeatherServiceTest.java[WeatherServiceTest.java] available in the project. |
| |
| ---- |
| mvn clean test |
| ---- |
| |
| ---- |
| [INFO] Results: |
| [INFO] |
| [INFO] Tests run: 4, Failures: 0, Errors: 0, Skipped: |
| ---- |