1 Context
- 1.1 Need
- 1.2 Previous Decisions
- 1.3 Alternative Proposals
2 Decision
- 2.1 Protocol Design
- 2.2 Rationale
3 Implementation Guidance
- 3.1 Spring Way
  - 3.1.1 pom.xml
  - 3.1.2 application.properties
  - 3.1.3 Request
  - 3.1.4 Response
4 Related JIRAs

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	Feb 24, 2021
Owner	@Marc Johnson @Oleksandr_Dekin (for Spring Way implementation guidance)

NOTICE

This decision has been migrated to the Technical Council's Decision Log as part of a consolidation effort. See: DR-000007 - Back End Module Health Check Protocol

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: https://folio-org.atlassian.net/browse/OKAPI-904. 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

https://folio-org.atlassian.net/browse/MSEARCH-65