Context

Need

System operators need to be able to understand if a module instance is healthy enough to be able to participate in the system. FOLIO needs a standard way of allowing operators to determine this.

Previous Decisions

4 years ago RAML Module Builder defined the /admin/health  endpoint for checking the health of a module. More recently this was included in the formal expectations of a module. Both of these state that the module should always respond with a 200 status code.

Alternative Proposals

John Malconian has proposed that instead of the "health" endpoint, two endpoints: for readiness and liveness check. See the proposal here: OKAPI-904 - Getting issue details... STATUS . The proposal has been implemented in Okapi but has not seen much uptake.

Decision

All back end modules included in the 2021 R2 (and later) distribution must provide a health check endpoint

Protocol Design

The health check endpoint must be provided at the path /admin/health 

The endpoint must respond with a status code 200

The response may include a body of any form

Rationale

This topic was discussed at the /wiki/spaces/TLG/pages/754372.

It was agreed that:

• The existing path should continue to be used given that system operators already rely on it for some modules
• A module is considered healthy if it can respond to requests to the health check endpoint, no other criteria applies at this point
• Discussion about any additional criteria for the health of a back end module has been deferred

Implementation Guidance

Spring Way

For comfortable using health check in spring way - we can use dependency: `spring-boot-starter-actuator`. Just add it in pom.xml:

  <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-actuator</artifactId>
      <version>2.3.4.RELEASE</version>
  </dependency>

By default, the health endpoint is mapped to `/actuator/health`. To change it we should add property in the application.properties:

management.endpoints.web.base-path=/admin

Also swagger automatically generate endpoint on the UI if you use swagger UI:

Example of using:

GET /admin/health HTTP/1.1
Host: localhost:8080

{
	"status": "UP"
}

Documentation: https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-features.html

Related JIRAs

• MSEARCH-65 - Getting issue details... STATUS