Note
|
This repository contains the guide documentation source. To view the guide in published form, view it on the Open Liberty website. |
Explore how to report and check the health of a microservice with MicroProfile Health.
You will learn how to use MicroProfile Health to report the health status of microservices and take appropriate actions based on this report.
MicroProfile Health allows services to report their health, and it publishes the overall health status to a defined
endpoint. A service reports UP
if it is available and reports DOWN
if it is unavailable. MicroProfile Health reports
an individual service status at the endpoint and indicates the overall status as UP
if all the services are UP
. A service
orchestrator can then use the health statuses to make decisions.
A service checks its own health by performing necessary self-checks and then reports its overall status by implementing the API provided by MicroProfile Health. A self-check can be a check on anything that the service needs, such as a dependency, a successful connection to an endpoint, a system property, a database connection, or the availability of required resources. MicroProfile offers checks for both liveness and readiness.
You will add liveness and readiness checks to the system
and inventory
services, which
have been provided for you, and implement what is necessary to report health status by
using MicroProfile Health.
The finish
directory in the root directory of this guide contains two services that are configured
to use MicroProfile Health. Feel free to give them a try before you proceed.
To try out the services, navigate to the finish
directory and then run the Maven install
and
liberty:start-server
goals to build the services and run them in Open Liberty:
cd finish mvn install liberty:start-server
The system
and inventory
services can be found at the following URLs:
Visit the http://localhost:9080/health URL to see the
overall health status of the application, as well as the aggregated data of the liveness
and readiness checks. Two checks show the state of the system
service, and the other two
checks show the state of the inventory
service. As you might expect, both services are in the
UP
state, and the overall health status of the application is in the UP
state.
You can also access the /health/ready
endpoint by visiting the http://localhost:9080/health/ready
URL to view the data from the readiness health checks. Similarly, access the /health/live
endpoint by visiting the http://localhost:9080/health/live
URL to view the data from the liveness health checks.
When you are done checking out the services, stop the Open Liberty server by running the following command:
mvn liberty:stop-server
Navigate to the start
directory to begin.
A health report will be generated automatically for all services that enable MicroProfile Health. The
mpHealth
feature has already been enabled for you in the src/main/liberty/config/server.xml
file.
All services must provide an implementation of the HealthCheck
interface, which will be used to
verify their health. MicroProfile Health offers health checks for both readiness and liveness.
A readiness check allows third-party services, such as Kubernetes, to determine whether a microservice
is ready to process requests. For example, a readiness check might check dependencies,
such as database connections. A liveness check allows third-party services to determine
whether a microservice is running. If the liveness check fails, the application can be
terminated. For example, a liveness check might fail if the application runs out of memory.
server.xml
link:finish/src/main/liberty/config/server.xml[role=include]
Create theSystemReadinessCheck
class.src/main/java/io/openliberty/guides/system/SystemReadinessCheck.java
SystemReadinessCheck.java
link:finish/src/main/java/io/openliberty/guides/system/SystemReadinessCheck.java[role=include]
The @Readiness
annotation indicates that this particular bean is a readiness health check procedure.
By pairing this annotation with the ApplicationScoped
context from the Contexts and
Dependency Injections API, the bean is discovered automatically when the http://localhost:9080/health
endpoint receives a request.
The call()
method is used to return the health status of a particular service.
In this case, you are simply checking if the server name is defaultServer
and
returning UP
if it is, and DOWN
otherwise. The
HealthCheckResponse.named()
method is used to indicate what service the health
check is done for. Overall, this is a very simple implementation of the call()
method. In a real development environment, you would want to orchestrate much more meaningful
health checks.
Create theSystemLivenessCheck
class.src/main/java/io/openliberty/guides/system/SystemLivenessCheck.java
SystemLivenessCheck.java
link:finish/src/main/java/io/openliberty/guides/system/SystemLivenessCheck.java[role=include]
The @Liveness
annotation indicates that this is a liveness health check procedure.
In this case, you are checking the heap memory usage. If more than 90% of the maximum memory
is being used, a status of DOWN
will be returned.
Create theInventoryReadinessCheck
class.src/main/java/io/openliberty/guides/inventory/InventoryReadinessCheck.java
InventoryReadinessCheck.java
link:finish/src/main/java/io/openliberty/guides/inventory/InventoryReadinessCheck.java[role=include]
This time, you are checking whether or not the service is in maintenance or if it’s down.
For simplicity, the custom io_openliberty_guides_inventory_inMaintenance
MicroProfile Config property defined in the resources/CustomConfigSource.json
file is used to indicate whether the service is in maintenance or not. This file has already
been created for you. To check if the service is down, simply make a HTTP GET request to
the system
service and check the status returned by the response. You make a GET request
to the system
service rather than the inventory
service because the inventory
service
depends on the system
service. In other words, the inventory
service wouldn’t work if
the system
service is down. If the status is not 200, then the service is not running.
Based on these two factors, the isHealthy()
method returns whether
or not the inventory
service is healthy.
If you are curious about the injected inventoryConfig
object or if
you want more information on MicroProfile Config, see
Configuring microservices.
Create theInventoryLivenessCheck
class.src/main/java/io/openliberty/guides/inventory/InventoryLivenessCheck.java
InventoryLivenessCheck.java
link:finish/src/main/java/io/openliberty/guides/inventory/InventoryLivenessCheck.java[role=include]
As with the system
liveness check, you are checking the heap memory usage. If more
than 90% of the maximum memory is being used, a DOWN
status is returned.
CustomConfigSource.json
link:finish/resources/CustomConfigSource.json[role=include]
While the server is running, navigate to the http://localhost:9080/health URL to find the aggregated liveness and readiness health reports on the two services.
You can also navigate to the http://localhost:9080/health/ready URL to view the readiness health report, or the http://localhost:9080/health/live URL to view the liveness health report.
Put the inventory
service in maintenance by setting the io_openliberty_guides_inventory_inMaintenance
property to true
in the resources/CustomConfigSource.json
file. Because
this configuration file is picked up dynamically, simply refresh the http://localhost:9080/health
URL you will see that the state of the inventory
service has changed to DOWN
. The
overall state of the application has also changed to DOWN
as a result. Point to the
http://localhost:9080/inventory/systems URL to verify that the inventory
service is
indeed in maintenance. Set the io_openliberty_guides_inventory_inMaintenance
property back to false
once you are done.
CustomConfigSource.json
link:finish/resources/CustomConfigSource.json[role=include]
You will implement several test methods, testIfServicesAreUp()
, testReadiness()
, testLiveness()
, and
testIfInventoryServiceIsDown()
, to validate the health of the system
and inventory
services.
Create theHealthTest
class.src/test/java/it/io/openliberty/guides/health/HealthTest.java
HealthTest.java
link:finish/src/test/java/it/io/openliberty/guides/health/HealthTest.java[role=include]
Let’s break down the test cases:
-
The
testIfServicesAreUp()
test case compares the generated health report with the actual status of the services. -
The
testReadiness()
test case compares the generated health report for the readiness checks with the actual status of the services. -
The
testLiveness()
test case compares the generated health report for the liveness checks with the actual status of the services. -
The
testIfInventoryServiceIsDown()
test case puts theinventory
service in maintenance by setting theio_openliberty_guides_inventory_inMaintenance
property totrue
and comparing the generated health report with the actual status of the services.
A few more tests have been included to verify the basic functionalitiy of the system
and inventory
services. They can be found under the src/test/java/it/io/openliberty/guides/inventory/InventoryEndpointTest.java
and src/test/java/it/io/openliberty/guides/system/SystemEndpointTest.java
files.
If a test failure occurs, then you might have introduced a bug into the code. These tests
will run automatically as a part of the Maven build process when you run the mvn install
command. You can also run these tests separately from the build by using the mvn verify
command, but first make sure that the server is stopped.
CustomConfigSource.json
link:finish/resources/CustomConfigSource.json[role=include]
InventoryEndpointTest.java
link:finish/src/test/java/it/io/openliberty/guides/inventory/InventoryEndpointTest.java[role=include]
SystemEndpointTest.java
link:finish/src/test/java/it/io/openliberty/guides/system/SystemEndpointTest.java[role=include]
-------------------------------------------------------
T E S T S
-------------------------------------------------------
Running it.io.openliberty.guides.health.HealthTest
Tests run: 4, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 3.504 sec - in it.io.openliberty.guides.health.HealthTest
Running it.io.openliberty.guides.inventory.InventoryEndpointTest
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.326 sec - in it.io.openliberty.guides.inventory.InventoryEndpointTest
Running it.io.openliberty.guides.system.SystemEndpointTest
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.011 sec - in it.io.openliberty.guides.system.SystemEndpointTest
Results :
Tests run: 6, Failures: 0, Errors: 0, Skipped: 0
To see whether the tests detect a failure, manually change the configuration of
io_openliberty_guides_inventory_inMaintenance
from false
to true
in the resources/CustomConfigSource.json
file. Re-run the Maven build. You will see a
test failure occur because the initial status of the inventory
service is DOWN
.
You just learned how to add health checks to report the states of microservices by using MicroProfile Health in Open Liberty. Then, you wrote tests to validate the generated health report.
Feel free to try one of the related MicroProfile guides. They demonstrate additional technologies that you can learn and expand on top of what you built here.