Spring Boot 핵심 기능 5 - 모니터링 & 관리 (Actuator)

액츄에이터(Actuator)

의존성 추가(build.gradle)

implementation 'org.springframework.boot:spring-boot-starter-actuator'

 

  액츄에이터는 /actuator 경로를 통해서 기능을 제공합니다.

 

  액츄에이터는 헬스 상태 뿐만 아니라 수많은 기능을 제공합니다. 이런 기능이 웹 환경에 보이도록 application.yml에 다음을 추가합니다.

management:
  endpoints:
    web:
      exposure:
        include: "*"

 

  다시 실행해보면 액츄에이터가 제공하는 수 많은 기능들을 확인할 수 있습니다. 액츄에이터가 제공하는 기능 하나하나를 엔드포인트라고 합니다. 각각의 엔드포인트는 /actuator/{엔드포인트명} 과 같은 형식으로 접근할 수 있습니다.

• http://localhost:8080/actuator/health: 애플리케이션 헬스 정보
• http://localhost:8080/actuator/beans: 스프링 컨테이너에 등록된 빈

 

엔드포인트 설정

  엔드포인트를 사용하려면 다음 2가지 과정이 필요합니다.

1. 엔드포인트 활성화: 해당 기능 자체를 사용할지 말지 on, off를 선택하는 것입니다.
2. 엔드포인트 노출: 활성화된 엔드포인트를 HTTP에 노출할지, JMX에 노출할지 선택하는 것입니다.

 

  대부분의 엔드포인트는 기본으로 활성화 되어 있습니다(shutdown 제외). 특정 엔드포인트를 활성화 하려면 management.endpoint.{엔드포인트명}.enabled=true를 적용하면 됩니다. 다음은 shutdown 엔드포인트를 활성화하고 모든 엔드포인트를 웹에 노출하는 설정입니다.

management:
  endpoint:
    shutdown:
      enabled: true
  endpoints:
    web:
      exposure:
        include: "*"

  Postman으로 (POST) http://localhost:8080/actuator/shutdown 를 호출하면 실제 서버가 종료되는 것을 확인할 수 있습니다.

 

  다음은 스프링 공식 메뉴얼이 제공하는 예제입니다.

management:
  endpoints:
    jmx:
      exposure:
        include: "health,info"

  jmx에 health, info를 노출합니다.

management:
  endpoints:
    web:
      exposure:
        include: "*"
        exclude: "env,beans"

  web에 모든 엔드포인트를 노출하지만 env, beans는 제외합니다.

 

다양한 엔드포인트

• beans : 스프링 컨테이너에 등록된 스프링 빈을 보여줍니다.
• conditions : condition 을 통해서 빈을 등록할 때 평가 조건과 일치하거나 일치하지 않는 이유를 표시합니다.
• configprops : @ConfigurationProperties 를 보여줍니다.
• env : Environment 정보를 보여줍니다.
• health : 애플리케이션 헬스 정보를 보여줍니다.
• httpexchanges : HTTP 호출 응답 정보를 보여줍니다. HttpExchangeRepository 를 구현한 빈을 별도로 등록해야 합니다.
• info : 애플리케이션 정보를 보여줍니다.
• loggers : 애플리케이션 로거 설정을 보여주고 변경도 할 수 있습니다.
• metrics : 애플리케이션의 메트릭 정보를 보여줍니다.
• mappings : @RequestMapping 정보를 보여줍니다.
• threaddump : 쓰레드 덤프를 실행해서 보여줍니다.
• shutdown : 애플리케이션을 종료합니다. 이 기능은 기본으로 비활성화 되어 있습니다.

 

  전체 엔드포인트는 공식 메뉴얼을 참고하시면 됩니다.

 

헬스 정보

  헬스 정보를 사용하면 애플리케이션에 문제가 발생했을 때 문제를 빠르게 인지할 수 있습니다. 헬스 정보는 단순히 애플리케이션이 요청에 응답을 할 수 있는지 판단하는 것을 넘어 애플리케이션이 사용하는 데이터베이스가 응답하는지, 디스크 사용량에는 문제가 없는지 같은 다양한 정보들을 포함해서 만들어집니다.

 

  헬스 정보를 더 자세히 보려면 다음 옵션을 지정하면 됩니다.

management.endpoint.health.show-details=always

management:
  endpoint:
    health:
      show-details: always

 

  각 헬스 컴포넌트의 상태 정보만 간략히 보기 위해서는 다음 옵션을 사용하면 됩니다.

management.endpoint.health.show-components=always

management:
  endpoint:
    health:
      show-components: always

 

  자세한 헬스 기본 지원 기능은 공식 메뉴얼을 참고하시면 됩니다.

 

애플리케이션 정보

  info 엔드포인트는 애플리케이션의 기본 정보를 노출합니다. env, java, os는 기본으로 비활성화 되어 있습니다.

• java : 자바 런타임 정보
• os: OS 정보
• env : Environment 에서 info. 로 시작하는 정보
• build : 빌드 정보, META-INF/build-info.properties 파일이 필요합니다.
• git : git 정보, git.properties 파일이 필요합니다.

 

  처음에 실행하면 정보들이 보이지 않습니다. 다음은 java, os, env 기능을 활성화 합니다. management.info.<id>.enabled의 값을 true로 지정하면 활성화 됩니다. Environment에서 info.. 로 시작하는 정보를 출력합니다.

management:
  endpoints:
    web:
      exposure:
        include: "*"
  info:
    java:
      enabled: true
    os:
      enabled: true
    env:
      enabled: true
      
# Environment 에서 출력합니다.
info:
  app:
    name: actuator
    company: com.example

 

  빌드 정보를 노출하려면 빌드 시점에 META-INF/build-info.properties 파일을 만들어야 합니다. build.gradle에 다음을 추가하면 됩니다. build는 기본으로 활성화 되어 있기 때문에 해당 파일만 있으면 바로 확인이 가능합니다.

springBoot {
    buildInfo()
}

  빌드를 하면 build 폴더 안에 resources/main/META-INF/build-info.properties 파일을 확인할 수 있습니다.

 

  git정보를 노출하려면 git.properties 파일이 필요합니다. 프로젝트가 git 으로 관리되고 있어야 하며, 다음을 build.gradle에 추가합니다. git은 기본으로 활성화 되어 있기 때문에 해당 파일만 있으면 바로 확인이 가능합니다.

plugins {
    ...
    id "com.gorylenko.gradle-git-properties" version "2.4.1" //git info
}

  빌드를 하면 build 폴더 안에 resources/main/git.properties 파일을 확인할 수 있습니다. git에 대한 더 자세한 정보를 보고 싶다면 다음 옵션을 적용하면 됩니다.

management:
  info:
    git:
      mode: "full"

 

로거

  loggers 엔드포인트를 사용하면 로깅과 관련된 정보를 확인하고, 또 실시간으로 변경할 수 있습니다. 다음은 hello.controller 패키지와 그 하위는 debug 레벨을 출력하도록 하는 설정입니다. 로그를 별도로 설정하지 않으면 스프링 부트는 기본으로 INFO를 사용합니다.

logging:
  level:
    hello.controller: debug

  http://localhost:8080/log 실행 시 로그를 확인할 수 있고, http://localhost:8080/actuator/loggers/{로거이름} 으로 특정 로거 이름 기준으로 조회할 수 있습니다.

 

실시간 로그 레벨 변경

  loggers 엔드포인트를 사용하면 애플리케이션을 다시 시작하지 않고, 실시간으로 로그 레벨을 변경할 수 있습니다.

 

  다음과 같이 Postman 같은 프로그램으로 POST 요청을 보냅니다.

 

액츄에이터 포트 설정

management.server.port=9292

 

엔드포인트 경로 변경

management:
  endpoints:
    web:
      base-path: "/manage"

/actuator/{엔드포인트} 대신에 /manage/{엔드포인트}로 변경됩니다.

 

[참고정보]

스프링 부트 - 핵심 원리와 활용