Spring Boot Actuator - 1. 시작하기

애플리케이션을 운영하다 보면 단순히 서버가 켜져 있다는 사실만으로는 안심할 수 없다. 

사용자는 접속이 되는데 실제로 데이터 베이스 연결이 끊겨 있다거나 외부 API 호출이 실패하는 경우도 있다. 운영자는 이런 상황을 빠르게 감지하고 대응할 수 있어야 한다. 

이때 필요한 것이 애플리케이션 상태 모니터링인데 Spring Boot는 이런 요구를 충족하기 위한 모듈을 제공한다.

그것이 바로 Spring Boot Actuator이다.

이번 포스팅에서는 Actuator의 기본 개념과 시작 방법을 다루며 몇 차례에 걸쳐 Actuator에 대한 포스팅을 작성해 보고자 한다.

 

Spring Boot Actuator란?

Spring Boot Actuator는 애플리케이션의 내부 상태를 확인하고 관리할 수 있는 운영/관리 기능 집합이라고 할 수 있다.

개발자가 이러한 기능을 직접 개발하지 않아도 다음과 같은 기본 기능으로 제공이 된다.

• 헬스 체크 (health check) : 애플리케이션과 주요 의존성이 정상 동작 중인지 확인할 수 있다.
• 환경 정보 (environment) : 현재 애플리케이션에 설정된 프로퍼티와 적용된 환경 변수 정보를 얻을 수 있다.
• 메트릭 (metrics) : CPU, 메모리, 스레드, HTTP 요청 수와 같은 성능 지표 정보를 얻을 수 있다.
• 로그 레벨 제어 (loggers) : 애플리케이션 실행 중에 동적으로 로그 레벨을 변경할 수 있다.
• 빈, 매핑 정보 확인(beans, mappings) : 어떤 bean이 등록되어 있고 어떤 URL이 어떤 Controller와 매핑되어 있는지 확인할 수 있다.
• ...

의존성 (Dependency)

Spring Boot Actuator를 사용하기 위해서는 다음과 같은 의존성이 필요하다.

gradle

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
}

 

maven

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
</dependencies>

 

actuator 의존성을 추가하면 애플리케이션의 /actuator 엔드포인트가 기본적으로 활성화된다.

 

actuator 기본 엔드포인트 실행

애플리케이션을 실행 후 /actuator를 호출해 보면 다음과 같은 응답을 받을 수 있다.

 

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
    }
  }
}

현재 /actuator를 통해서 노출되는 엔드포인트는 /actuator/health 임을 알 수 있는데 이는 기본적으로 노출을 허용하는 엔드포인트다.

 

GET http://localhost:8080/actuator/health를 호출하면 현재 애플리케이션의 라이브 상태를 확인할 수 있다.

{"status":"UP"}

UP : 정상 동작

DOWN : 문제 발생

UNKNOWN : 상태 확인 불가 (이것도 문제일 것이다.)

 

애플리케이션에서 사용하는 인프라 의존성의 경우에도 해당 인프라 서비스에 대한 health check를 확인할 수 있다.

예를 들어 애플리케이션이 redis를 사용한다면 redis에 대한 health check에 대한 정보도 얻을 수 있다. 이는 actuator autoconfiguration에 의해서 가능하다. 무조건 의존성만 추가되었다고 해서 가능한 것은 아니고 각 서비스마다 health check가 활성화되기 위한 조건이 있는데 대부분 비슷할 것이다.

 

아래 내용을 이해하는데

2023.09.22 - [스프링부트] - spring boot actuator health endpoints delay check

spring boot actuator health endpoints delay check

이 포스팅이 도움이 될지 모르겠다.

 

우선 redis health check 활성화 조건은 다음과 같다.

• management.health. <name>. enabled=true
  • <name> 부분은 서비스이름이 들어간다. 여기서는 redis. 즉 management.health.redis.enabled=true
• RedisConnectionFactory 클래스가 클래스 패스에 존재해야 한다.
• RedisConnectionFactory 클래스가 빈으로 등록되어 있어야 한다.
  • 위 두 가지 항목은 spring-boot-starter-data-redis 의존성이 추가되면 자동 구성에 의해서 조건이 충족된다.

사용자가 redis에 대한 health check 조건을 활성화하기 위해서 해야 할 일은 management.health.redis.enabled=true로 설정하는 것이다.

또한 의존성 서비스에 대해서 헬스 체크 정보를 출력하기 위해서는 management.endpoint.health.show-details 설정이 필요하다.

설정 값은 다음 세 가지 값이 제공된다.

• ALWAYS: 누구에게나 상세 노출 (개발용)
• WHEN_AUTHORIZED: 인증 + 권한이 있을 때만 상세 노출 (권장)
• NEVER: 항상 요약만

management:
  endpoint:
    health:
      show-details: always
  health:
    redis:
      enabled: true
# 아래 설정을 통해 ConnectionDetails 추상화에 사용되고 RedisConnectionFactory가 만들어질 것이다.
spring:
  data:
    redis:
      host: localhost
      port: 6379

 

GET http://localhost:8080/actuator/health를 호출하면 다음과 같은 응답을 얻을 수 있다.

{
  "status": "UP",
  "components": {
    "diskSpace": {
      "status": "UP",
      "details": {
        ...
      }
    },
    "ping": {
      "status": "UP"
    },
    "redis": {
      "status": "UP",
      "details": {
        "version": "8.2.1"
      }
    }
  }
}

 

GET http://localhost:8080/actuator/health/redis를 호출할 수도 있다.

{
  "status":"UP",
  "details":{
    "version":"8.2.1"
  }
}

GET http://localhost:8080/actuator/info 엔드포인트는 애플리케이션의 기본 정보를 응답한다.

Spring Boot 3.2. 기준 info 엔드포인트는 기본 노출 엔드포인트가 아니라서 management.endpoints.web[jmx].exposure.include 설정에 info를 추가해야 한다. 기본값은 빈 객체지만, application.yml 에서 원하는 정보를 추가할 수 있다.

management:
  endpoints:
    web:
      exposure:
        include: health, info
  endpoint:
    health:
      show-details: always
  health:
    redis:
      enabled: true
  info:
    java:
      enabled: true
    os:
      enabled: true

spring:
  data:
    redis:
      host: localhost
      port: 6379

위 설정은 info에 java, os 정보를 응답하도록 설정하였다.

GET http://localhost:8080/actuator/info를 호출하면 다음과 같은 응답을 얻을 수 있다.

{
  "java": {
    "version": "17.0.6",
    "vendor": {
      "name": "Eclipse Adoptium",
      "version": "Temurin-17.0.6+10"
    },
    "runtime": {
      "name": "OpenJDK Runtime Environment",
      "version": "17.0.6+10"
    },
    "jvm": {
      "name": "OpenJDK 64-Bit Server VM",
      "vendor": "Eclipse Adoptium",
      "version": "17.0.6+10"
    }
  },
  "os": {
    "name": "Mac OS X",
    "version": "15.6.1",
    "arch": "aarch64"
  }
}

 

엔드포인트 노출 제어

운영 환경에서는 모든 엔드포인트를 노출하는 것이 보안상 위험하기 때문에 반드시 노출 범위를 제한해야 한다.

management:
  endpoints:
    web:
      exposure:
        include: health, info
  endpoint:
    health:
      show-details: always

위 설정은 엔트포인트를 health, info 만 노출하도록 설정한다.

 

exposure.include : 노출할 엔드포인트 지정

exposure.exclude : 제외할 엔드포인트 지정

대부분의 실무 환경에서는 외부에는 health, info 만 노출하고, 나머지 엔드포인트는 내부 관리자 네트워크에서만 확인한다.

 

Spring Boot Actuator에 대해서 간단히 소개를 했다. Actuator에 대한 내용은 양이 상당히 많기 때문에 여러 포스팅으로 나눠서 할 예정이다. 다음 포스팅에서는 Spring Boot Actuator에서 제공하는 주요 엔드포인트를 소개할 예정이다.

 

끝.