Skip to content
Branch: master
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
src/main
README.md
pom.xml

README.md

KumuluzEE Health sample

Build a REST service which utilizes a built-in health framework to expose a health check and pack it as a KumuluzEE microservice

The objective of this sample is to demonstrate how to use the built-in health framework to expose basic health checks.

Requirements

In order to run this example you will need the following:

  1. Java 8 (or newer), you can use any implementation:

    • If you have installed Java, you can check the version by typing the following in a command line:

      java -version
      
  2. Maven 3.2.1 (or newer):

    • If you have installed Maven, you can check the version by typing the following in a command line:

      mvn -version
      
  3. Git:

    • If you have installed Git, you can check the version by typing the following in a command line:

      git --version
      

Prerequisites

In order to run this sample you will have to setup a local PostgreSQL database:

  • database host: localhost:5432
  • database name: customers
  • user: postgres
  • password: postgres

You can run the database inside docker:

docker run -d --name pg-health -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=customers -p 5432:5432 postgres:latest

The required tables will be created automatically upon running the sample.

Usage

The example uses maven to build and run the microservices.

  1. Build the sample using maven:

    $ cd kumuluzee-health
    $ mvn clean package
  2. Run the sample:

  • Uber-jar:

    $ java -jar target/${project.build.finalName}.jar

    in Windows environemnt use the command

    java -jar target/${project.build.finalName}.jar
  • Exploded:

    $ java -cp target/classes:target/dependency/* com.kumuluz.ee.EeApplication

    in Windows environment use the command

    java -cp target/classes;target/dependency/* com.kumuluz.ee.EeApplication

The application/service can be accessed on the following URL:

To shut down the example simply stop the processes in the foreground.

Tutorial

This tutorial will guide you through the steps required to use KumuluzEE Health and pack the application as a KumuluzEE microservice. We will extend the existing KumuluzEE JPA and CDI sample. Therefore, first complete the existing KumuluzEE JPA and CDI sample tutorial, or clone the KumuluzEE JPA and CDI sample code.

We will follow these steps:

  • Complete the tutorial for KumuluzEE JPA and CDI sample or clone the existing sample
  • Add Maven dependency
  • Implement Health Check Bean
  • Add Health configuration
  • Build the microservice
  • Run it

Add Maven dependency

Since your existing starting point is the existing KumuluzEE JPA and CDI sample, you should already have the dependencies for kumuluzee-bom, kumuluzee-core, kumuluzee-servlet-jetty, kumuluzee-jax-rs-jersey, kumuluzee-cdi-weld, kumuluzee-jpa-eclipselink and org.postgresql configured pom.xml.

Add the kumuluzee-health dependency:

<dependency>
    <groupId>com.kumuluz.ee.health</groupId>
    <artifactId>kumuluzee-health</artifactId>
    <version>${kumuluz-health.version}</version>
</dependency>

Implement Health Check Bean

Implement a class which implements HealthCheck and is annotated with @Readiness and @ApplicationScoped. The bean should contain a method call() which executes health check. The bean will be registered to the HealthRegistry automatically and called either by accessing health servlet or by periodic health checks which are logged to the logs.

Sample implementation of such a class (which could also be checked by a built in HttpHealthCheck):

import org.eclipse.microprofile.health.Readiness;
import org.eclipse.microprofile.health.HealthCheck;
import org.eclipse.microprofile.health.HealthCheckResponse;

import javax.enterprise.context.ApplicationScoped;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.logging.Logger;

@Readiness
@ApplicationScoped
public class GithubHealthCheckBean implements HealthCheck {

    private static final String url = "https://github.com/kumuluz/kumuluzee";

    private static final Logger LOG = Logger.getLogger(GithubHealthCheckBean.class.getSimpleName());

    @Override
    public HealthCheckResponse call() {
        try {

            HttpURLConnection connection = (HttpURLConnection) new URL(url).openConnection();
            connection.setRequestMethod("HEAD");

            if (connection.getResponseCode() == 200) {
                return HealthCheckResponse.named(GithubHealthCheckBean.class.getSimpleName()).up().build();
            }
        } catch (Exception exception) {
            LOG.severe(exception.getMessage());
        }
        return HealthCheckResponse.named(GithubHealthCheckBean.class.getSimpleName()).down().build();
    }
}

You can also use @Liveness instead of @Readiness. For more information about the difference see the KumuluzEE Health README.

Add Health configuration

For registering built in disk space and postgres data source health checks replace config.yaml file content with the following content:

kumuluzee:
  datasources:
    - jndi-name: jdbc/CustomersDS
      connection-url: jdbc:postgresql://localhost:5432/customers
      username: postgres
      password: postgres
      pool:
        max-size: 20
  health:
    servlet:
      mapping: /health
      enabled: true
    logs:
      enabled: true
      level: INFO
      period-s: 30
    checks:
      data-source-health-check:
        jndi-name: jdbc/CustomersDS
      disk-space-health-check:
        threshold: 100000000

Build the microservice and run it

To build the microservice and run the example, use the commands as described in previous sections.

The json output (http://localhost:8080/health/ready) should look similar to the one bellow:

{
  "status" : "UP",
  "checks" : [ {
    "name" : "DiskSpaceHealthCheck",
    "status" : "UP"
  }, {
    "name" : "DataSourceHealthCheck",
    "status" : "UP"
  }, {
    "name" : "GithubHealthCheckBean",
    "status" : "UP"
  } ]
}
You can’t perform that action at this time.