Page tree
Skip to end of metadata
Go to start of metadata

Status

DONE

Stakeholders

Back End Developers, System Operators

Outcome

All back end modules included in 2021 R2 or later must provide a health check endpoint

Created date

  

Owner

Marc Johnson Oleksandr Dekin (for Spring Way implementation guidance)

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 2021-02-24 Technical Leads meeting.

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:

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:

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


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


Example of using:

Request
GET /admin/health HTTP/1.1
Host: localhost:8080
Response
{
	"status": "UP"
}

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

Related JIRAs