액추에이터 활용하기

애플리케이션을 개발하는 단계를 지나 운영 단계에 접어들면 애플리케이션이 정상적으로 동작하는지 모니터링하는 환경을 구축하는 것이 매우 중요해집니다. 스프링 부트 액추에이터는 HTTP 엔포인트나 JMX를 활용해 애플리케이션을 모니터링하고 관리할 수 있는 기능을 제공합니다.

프로젝트 생성 및 액추에이터 종속성 추가

dependencies {
	// 스프링 액추에이터는 애플리케이션에 대한 모니터링 정보를 엔드포인트를 통해 제공한다.
    implementation 'org.springframework.boot:spring-boot-starter-actuator'

이렇게 생성되는 것을 볼 수 있습니다.

스프링 actuator

스프링 액추에이터는 애플리케이션에 대한 모니터링 정보를 엔드포인트를 통해 제공한다. db, matrix 등의 상태 정보를 제공하며 만약 actuator/health(기본값) 을 통해 접근하면 애플리케이션의 건강 상태를 (up, down.. 등으로) 제공 받을 수 있다. 또한 다양한 설정을 통해 사용자에 맞게 수정 가능하다.

엔드포인트

액추에이터의 앤드포인트는 애플리케이션의 모니터링을 사용하는 경로입니다. 스프링 부트에는 여러 내장 엔드포인트가 포함돼 있으며, 커스텀 엔드포인트를 추가할 수 있습니다. 액추에이터를 추가하면 기본적으로 엔드포인트 URI로 /actuator가 추가되며 이 뒤에 경로를 추가해 상세 내역에 접근합니다. 만약 /actuator 경로가 아닌 다른 경로를 사용하고 싶다면 application.properties 파일에 작성합니다.

자주 활용되는 액추에이터의 앤드포인트는 다음과 같습니다.

만약 Spring MVC, Spring WebFlux, Jersey을 사용한다면 추가로 다음과 같은 엔드포인트를 사용할 수 있습니다.

앤드포인트 활성화 여부와 노출 여부를 설정할 수 있습니다. 활성화는 기능 자체를 활성화할 것인지를 결정하는 것으로, 비활성화된 엔드포인트는 애플리케이션 컨텍스트에서 완전히 제거됩니다. 엔드포인트를 활성화하려면 application.properties에 속성을 추가합니다. 간단한 예로 다음과 같이 작성할 수 있습니다.

## 엔트포인트 활성화
management.endpoint.shutdown.enabled=true
management.endpoint.caches.enabled=false

위 예제의 설정은 엔드포인트의 shutdown 기능은 활성화하고 caches 기능은 비활성화하겠다는 의미입니다.

또한 액추에이터 설정을 통해 기능 활성화/비활성화가 아니라 엔드포인트의 노출 여부만 설정하는 것도 가능합니다. 노출 여부는 JMX를 통한 노출과 HTTP를 통한 노출이 있어 다음과 같이 설정이 구분됩니다.

# 엔드포인트 노출 설정
# HTTP 설정
management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=threaddump, heapdump
# JMX 설정
management.endpoints.jmx.exposure.include=*
management.endpoints.jmx.exposure.exclude=threaddump, heapdump

web과 jmx 환경에서 엔드포인트를 전체적으로 노출하며, 스레드 덤프와 힙 덤프 기능은 제외하겠다는 의미입니다. 엔드포인트는 애플리케이션에 관한 민감한 정보를 가지고 있어서 노출 설정을 신중하게 고려해야 합니다.

노출 설정에 대한 기본값

server:
  port: 9090

---
management:
  endpoint:
    # true로 설정하면, 애플리케이션의 상태를 나타내는 /actuator/health 엔드포인트가 활성화됩니다.
    # 이 엔드포인트는 일반적으로 애플리케이션의 건강 상태를 나타내는데 사용됩니다.
    health:
      enabled: false
    # true로 설정하면 애플리케이션의 빈정보를 나타내는 /actuator/beans 엔드포인트 활성화
    beans:
      enabled: false
      # true로 설정하면 애플리케이션의 캐시 정보를 나타내는 /actuator/caches 엔드포인트가 활성화됩니다.
    caches:
      enabled: true
      # true로 설정하면, /actuator/heapdump 엔드포인트를 통해 힙 덤프를 생성할 수 있습니다.
      # 이는 애플리케이션의 힙 메모리 상태를 분석하기 위해 사용됩니다.
    heapdump:
      enabled: true
  # 활성화할 관리 엔드포인트를 명시적으로 지정하는데 사용됩니다.
  endpoints:
    web:
      exposure:
        # *는 모든 엔드포인트를 활성화하고, exclude에 명시된 엔드포인트는 제외됩니다.
        include: "*"
        exclude:
          - health
          - beans

이렇게 설정할 때

기존꺼보다 더 많이 나오고 health랑 beans가 안나오는 것을 볼 수 있습니다.

그러면 include랑 exclude랑 같이하면 뭐가 우선순위가 있을까?
exclude가 우선순위가 더 높습니다.

보안 문제

actuator를 통해 application의 다양한 정보를 확인할 수 있고 특정 endpoint에서는 실시간 변경도 가능하게 해줍니다. 따라서 보안상 문제가 있을 수 있으므로 spring security 혹은 이와 유사한 방법으로 위험을 해결하도록 해야합니다. 가장 쉬운 방법은 security를 통해 /actuator url에 대해 http basic auth을 적용해서 id, pw가 맞아야만 pass되도록 하면 됩니다.

액추에이터 기능 살펴보기

액추에이터를 활성화하고 노출 지점도 설정하고 나면 애플리케이션에서 해당 기능을 사용할 수 있습니다. 모든 기능을 살펴보기 위해서는 다른 의존성을 추가하거나 몇 가지 설정을 추가해야하기 때문에 기능 추가 없이 액추에이터 설정만으로 볼 수 있는 기능을 살펴보겠습니다.

애플리케이션 기본정보(/info)

액추에이터의 /info 엔드포인트를 활용하면 가동 중인 애플리케이션의 정보를 볼 수 있습니다. 제공하는 정보의 범위는 애플리케이션에서 몇 가지 방법을 거쳐 제공할 수도 있으나 application.properties 파일에 info.로 시작하는 속성 값들을 정의하는 것이 가장 쉬운 방법입니다.

# 액추에이터 info 정보 설정
info.organization.name=wikibooks
info.contact.email=thinkground.flature@gamil.com
info.contact.phoneNumber=010-1234-5678

애플리케이션 상태(/health)

/health 엔드포인트를 활용하면 애플리케이션의 상태를 확인할 수 있습니다. 별도의 설정이 없이 접근하면 다음과 같이 나옵니다.

{"status" : "UP"}

만약 애플리케이션에 데이터베이스가 연동돼 있으면 인프라 관련 상태까지 확인할 수 있습니다.

빈 정보 확인(/beans)

액추에이터의 /beans 엔드포인트를 사용하면 스프링 컨테이너에 등록된 스프링 빈의 전체 목록을 표시할 수 있습니다. 이 엔드포인트는 JSON 형식으로 빈의 정보를 반환합니다.

스프링 부트의 자동설정 내역 확인(/conditions)

스프링 부트의 자동설정 조건 내역을 확인하려면 /conditions 엔드포인트를 사용합니다.

스프링 환경변수 정보(/env)

/env 엔드포인트는 스프링의 환경변수 정보를 확인하는 데 사용됩니다. 기본적으로 application.yml 파일의 변수들이 표시되며, OS, JVM의 환경변수도 함께 표시됩니다. 만약 일부 내용에 포함된 민감한 정보를 가리기 위해서는 management.endpoint.env.keys-to-sanitize 속성을 사용하면 됩니다. 해당 속성에 넣을 수 잇는 값은 단순 문자열이나 정규식을 활용합니다.

로깅 레벨 확인(/loggers)

애플리케이션 로깅 레벨 수준이 어떻게 설정되어 있는지 확인하려면 /loggers 엔드포인트를 사용할 수 있습니다.

endpoint cache

http에 etag와 같은 캐시 방법이 존재하듯이 endpoint에도 cache방법이 있습니다.

이런식으로 하면되는데 시가은 하루 1d, 1시간 1h, 1분 1m, 1초 1s이렇게 설정하면 됩니다.