Springboot Actuator로 Health check 설정하기

SpringBoot로 만든 웹 애플리케이션이 서버에서 과연 잘 동작하는지 확인하고 싶습니다. SpringBoot에는 SpringBoot Actuator라는 모듈이 존재하는데, 이를 활용하면 애플리케이션 모니터링이 가능합니다. 이번 포스팅에서는 SpringBoot의 Actuator를 활용하여 애플리케이션을 모니터링하는 방법을 소개하겠습니다.

스프링 부트 액츄에이터 서비스 활성화

스프링 부트에서 액츄에이터는 애플리케이션의 health check 수행해주는 모듈입니다. 즉, 애플리케이션 모니터링 모듈이라고 보시면 됩니다. 스프링 부트에서 액츄에이터를 사용하려면, 무엇을 해야 할까요? 방법은 매우 간단합니다. 예전에 작성했던 Springboot로 RESTful API 서버 만들기 했던 예제를 바탕으로 액츄에이터를 사용해보겠습니다.  

[Java] SpringBoot를 활용한 RESTful API 서버 만들기

위의 예제에서는 아래 HTTP GET 요청에 대한 응답을 만들었습니다.

HTTP GET 요청 URL
http://localhost:8080/greeting

Response
{
	"id": 1,
	"content": "Hello, World!"
}

Springboot에서는 기본 내장 모듈로 jackson을 사용하므로, HTTP 모든 응답 데이터 포맷은 JSON으로 반환합니다. /greeting 요청에 대해 응답하는 스프링 부트 애플리케이션에 actuator를 사용하기 위해 프로젝트 설정을 해보겠습니다.

예제 프로젝트는 Gradle기반 빌드 환경이므로, Gradle 기준으로 설명하겠습니다. SpringBoot Actuator Repository의 README를 보시면, 단순히 Gradle의 Dependencies에 아래 항목을 추가해주면 Actuator를 사용할 수 있다고 합니다.

GitHub - spring-projects/spring-boot: Spring Boot

build.gradle file

dependencies {
	implementation 'org.springframework.boot:spring-boot-starter-web'
	implementation 'org.springframework.boot:spring-boot-starter-actuator' // Add module
	testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

build.gradle 파일에 org.springframework.boot:spring-boot-starter-actuator를 추가해준 뒤, 다시 Springboot를 실행하여 아래와 같이 actuator health 체크를 위한 HTTP GET 요청을 보냅니다. status가 UP으로 응답이 반환된다면, 스프링 부트 애플리케이션에 actuator 서비스가 활성화되어 있다는 것입니다.

Actuator 서비스 구동 확인 요청 URL

http://localhost:8080/actuator/health
or
curl localhost:8080/actuator/health


응답
{
	"status": "UP"
}

스프링 부트 프로젝트에 Actuator서비스 활성화 설정이 완료되었습니다.

스프링 부트 액츄에이터로 Health 체크하기

스프링 부트 액츄에이터로 애플리케이션의 상태를 모니터링할 수 있습니다. 우선, 애플리케이션의 health를 체크할 수 있는 항목이 무엇인지 확인해보겠습니다.

아래 URL을 GET 요청
http://localhost:8080/actuator

응답
{
    "_links": {
        "self": {
            "href": "http://localhost:8080/actuator",
            "templated": false
        },
        "health": {
            "href": "http://localhost:8080/actuator/health",
            "templated": false
        },
        "health-path": {
            "href": "http://localhost:8080/actuator/health/{*path}",
            "templated": true
        }
    }
}

http://localhost:8080/actuator를 실행하였는데, 모니터링할 수 있는 항목이 없습니다. 항목이 나타나지 않은 이유는 application.properties 또는 application.yml파일을 생성하여, 체크할 모니터링 항목을 설정해주지 않았기 때문입니다. 최근, 환경설정 파일은 yml파일(야믈)로 설정을 많이 하고, 가독성도 좋기 때문에 yml파일로 health check 항목을 확인해보겠습니다.

아래와 같이 yml파일을 생성하고, health check 가능한 모든 항목을 웹에서 노출하도록 설정하는 내용을 작성합니다.

// application.xml
management:
  endpoints:
    web:
      exposure:
        include: "*"

그리고 /actuator를 다시 호출해보면, health check가 가능한 많은 항목들이 나옵니다. 여러 항목들이 있지만, 여기서 사용자가 Health Check하길 원하는 항목을 YML 파일에서 설정가능합니다.

// 요청
http://localhost:8080/actuator

// 응답
{
    "_links": {
        "self": {
            "href": "http://localhost:8080/actuator",
            "templated": false
        },
        "beans": {
            "href": "http://localhost:8080/actuator/beans",
            "templated": false
        },
        "caches-cache": {
            "href": "http://localhost:8080/actuator/caches/{cache}",
            "templated": true
        },
        "caches": {
            "href": "http://localhost:8080/actuator/caches",
            "templated": false
        },
        "health": {
            "href": "http://localhost:8080/actuator/health",
            "templated": false
        },
        "health-path": {
            "href": "http://localhost:8080/actuator/health/{*path}",
            "templated": true
        },
        "info": {
            "href": "http://localhost:8080/actuator/info",
            "templated": false
        },
        "conditions": {
            "href": "http://localhost:8080/actuator/conditions",
            "templated": false
        },
        "configprops": {
            "href": "http://localhost:8080/actuator/configprops",
            "templated": false
        },
        "configprops-prefix": {
            "href": "http://localhost:8080/actuator/configprops/{prefix}",
            "templated": true
        },
        "env": {
            "href": "http://localhost:8080/actuator/env",
            "templated": false
        },
        "env-toMatch": {
            "href": "http://localhost:8080/actuator/env/{toMatch}",
            "templated": true
        },
        "loggers": {
            "href": "http://localhost:8080/actuator/loggers",
            "templated": false
        },
        "loggers-name": {
            "href": "http://localhost:8080/actuator/loggers/{name}",
            "templated": true
        },
        "heapdump": {
            "href": "http://localhost:8080/actuator/heapdump",
            "templated": false
        },
        "threaddump": {
            "href": "http://localhost:8080/actuator/threaddump",
            "templated": false
        },
        "metrics-requiredMetricName": {
            "href": "http://localhost:8080/actuator/metrics/{requiredMetricName}",
            "templated": true
        },
        "metrics": {
            "href": "http://localhost:8080/actuator/metrics",
            "templated": false
        },
        "scheduledtasks": {
            "href": "http://localhost:8080/actuator/scheduledtasks",
            "templated": false
        },
        "mappings": {
            "href": "http://localhost:8080/actuator/mappings",
            "templated": false
        }
    }
}

모니터링하고자 하는 항목을 yml 파일에 작성하고, health check에 접근하는 경로를 YML 설정 파일에서 base-path항목으로 변경가능합니다.

아래와 같이 나타난다면, SpringBoot 액츄에이터 설정은 완료된 것입니다.

SpringBoot Actuator에 관하여 자세히 알고 싶다면, 공식 레퍼런스를 참조하면 궁금한 점을 찾으실 수 있습니다.

Spring Boot Reference Documentation