김영한님의 스프링 부트 - 핵심 원리와 활용을 정리한 내용입니다.

Actuator Endpoints

Spring Boot가 기본으로 제공하는 엔드포인트들은 다음과 같다.

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

📌 https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html#actuator.endpoints

http://localhost:8080/actuator 를 실행하면 위와 같은 엔드포인트 정보를 얻을 수 있다.

엔드포인트를 활성화하고 노출까지 둘다 적용해야 사용할 수 있다.

health

헬스 정보를 사용하면 애플리케이션의 문제를 파악할 수 있다.

헬스 정보를 더 자세히 보기 위한 옵션은 다음과 같다.

# application.yml
management:
  endpoint:
    health:
      show-details: always

참고로 헬스 컴포넌트 중 하나라도 문제가 있다면 전체 상태는 DOWN 된다.

애플리케이션 정보

info 엔드포인트를 활성화 및 노출하면 애플리케이션의 기본 정보를 노출한다.

• java: Java Runtime 정보 (default: false)
• os: OS 정보 (default: false)
• env: Environment에서 info.로 시작하는 정보 (default: false)
• build: 빌드 정보, META-INF/build-info.properties 파일이 필요함
• git: git 정보, git.properties 파일이 필요함

yml에 다음과 같이 지정하면 위와 같이 확인할 수 있다.

# application.yml
management:
  info:
    java:
      enabled: true
    os:
      enabled: true

logger

loggers 엔드포인트를 사용하면 로깅과 관련된 정보를 확인하고, 실시간으로 변경할수도 있다.

실시간 로그 레벨 변경

개발 서버는 보통 DEBUG 로그를 사용하지만, 운영 서버는 요청이 아주 많다. 따라서 이 레벨의 로그를 사용하면 로그가 너무 많이 남기 때문에 성능이나 디스크에 영향을 주게 된다. 그래서 운영 서버는 중요하다고 판단되는 INFO 로그 레벨을 사용한다.

하지만, 운영 중 문제가 있어 급하게 로그 레벨을 변경해야 한다면 설정을 변경하고 서버를 다시 시작해야 하는데 loggers 엔드포인트를 사용하면 재부팅 없이 실시간으로 로그 레벨을 변경할 수 있다.

별도의 설정 없이 http://localhost:8080/actuator/loggers에 들어가서 확인하면, INFO 레벨로 설정된 것을 확인할 수 있다.

Postman으로 특정 로거 이름을 기준으로 조회하면 다음과 같다.

이제 엔드포인트를 사용해 실시간으로 로그 레벨을 변경해보자. 꼭 다음과 같이 POST로 요청해야 한다.

• content/type: application/json
• body: "configuredLevel": "TRACE"

이후 조회 시 다음과 같이 변경됨을 확인할 수 있다.

HTTP 요청 응답 기록

httpexchanges 엔드포인트를 사용하면 HTTP 요청/응답의 과거 기록을 확인할 수 있다.

이를 위해 반드시 HttpExchangeRepository 인터페이스의 구현체를 빈으로 등록해야 한다.
Spring Boot는 기본으로 InMemoryHttpExchangeRepository 구현체를 제공한다.

/**
 * Actuator의 endpoint를 활성화 하기 위한 설정 클래스입니다.
 *
 * @author hakhyeonsong
 */
@Configuration
public class ActuatorConfig {

    /**
     * httpexchanges endpoint를 활성화 하기 위한 Bean을 등록합니다.
     *
     * @return HTTP 요청/응답 기록을 저장하고 있는 HttpExchangeRepository
     * @author hakhyeonsong
     */
    @Bean
    public HttpExchangeRepository httpExchangeRepository() {
        return new InMemoryHttpExchangeRepository();
    }
}

이 후 actuator를 확인해보면 다음과 같이 httpexchanges가 활성화 됨을 확인할 수 있다.

실제로 다른 요청들을 보낸 후 해당 엔드포인트에 접속하면 기록을 확인할 수 있다.

이 기능은 매우 단순하고 제한이 많기에 운영 서비스에선 모니터링 툴이나 다른 기술을 사용하도록 하자.

Actuator 보안

Actuator가 제공하는 기능들은 애플리케이션의 내부 정보를 너무 많이 노출한다. 외부 인터넷 망이 공개된 곳에 해당 엔드포인트들을 공개하는 것은 보안상 좋지 않다. 외부 인터넷에서 접근이 불가하게 막고, 내부에서만 접근 가능하도록 사용하는 것이 안전하다.

Actuator를 다른 포트에서 실행

management:
  server:
    port: 9292

Actuator에선 애플리케이션 서버와는 다른 포트에서 실행할 수 있도록 위와 같은 기능을 제공한다.

포트 분리가 어렵다면?

포트 분리가 어려워 어쩔 수 없이 외부 인터넷 망을 통해 접근해야 한다면 /actuator 경로에 Servlet Filter, Spring Interceptor, Spring Security를 통해 인증된 사용자만 접근 가능하도록 개발해야 한다.

// WebSecurityConfig 샘플
protected void configure(HttpSecurity http) throws Exception {
    http
        .authorizeRequests() // 접근에 대한 인증 설정
          .antMatchers("/login", "/signup", "/user").permitAll() // 누구나 접근 허용
          .antMatchers("/actuator/**").hasRole("ADMIN") // ADMIN만 접근 가능
          .anyRequest().authenticated() // 나머지 요청들은 권한의 종류에 상관 없이 권한이 있어야 접근 가능
        .and()
          .logout() // 로그아웃
            .logoutSuccessUrl("/login") // 로그아웃 성공시 리다이렉트 주소
            .invalidateHttpSession(true) // 세션 날리기
    ;
}

다음 내용을 추가로 참고해보자.

• Security Actuator 안전하게 사용하기 - 우아한기술블로그
• [Spring] /actuator 엔드포인트에 인터셉터 적용 문제

References

• 김영한님의 스프링 부트 - 핵심 원리와 활용
• Security Actuator 안전하게 사용하기 - 우아한기술블로그
• [Spring] /actuator 엔드포인트에 인터셉터 적용 문제