이전

스프링부트 액츄에이터

프로덕션 준비 기능이란?

전투에서 실패한 지휘관은 용서할 수 있지만 경계에서 실패하는 지휘관은 용서할 수 없다라는말이있다. 이말을 서비스를 운영하는 개발자에게 맞추어 보면 장애는 언제든지 발생할 수 있다. 하지만 모니터링(경계)은 잘 대응하는 것이 중요하다.

개발자가 애플리케이션을 개발할 때 기능 요구사항만 개발하는 것은 아니다. 서비스를 실제 운영 단계에 올리게 되면 개발자들이 해야하는 또 다른 중요한 업무가 있다. 바로 서비스에 문제가 없는지 모니터링하고 지표들을 심어서 감시하는 활동들이다.

운영 환경에서 서비스할 때 필요한 이런 기능들을 프로덕션 준비 기능이라 한다. 쉽게 이야기해서 프로덕션을 운영에 배포할 때 준비해야 하는 비 기능적 요소들을 뜻한다.

  • 지표(metric), 추적(trace), 감사(auditing)
  • 모니터링

좀 더 구제적으로 설명하자면, 애플리케이션이 현재 살아있는지, 로그 정보는 정상 설정 되었는지, 커넥션 풀은 얼마나 사용되고 있는지 등을 확인할 수 있어야 한다.

스프링 부트가 제공하는 액추에이터는 이런 프로덕션 준비 기능을 매우 편리하게 사용할 수 있는 다양한 편의 기능들을 제공한다. 더 나아가서 마이크로미터, 프로메테우스, 그라파나 같은 최근 유행하는 모니터링 시스템과 매우 쉽게 연동할 수 있는 기능도 제공한다.

참고로 액추에이터는 시스템을 움직이거나 제어하는 데 쓰이는 기계 장치라는 뜻이다. 여러 설명보다 한번 만들어서 실행해보는 것이 더 빨리 이해가 될 것이다.

액츄에이터

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

액츄에이터 기능을 웹에 노출

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

액츄에이터가 제공하는 수 많은 기능을 확인할 수 있다. 액츄에이터가 제공하는 기능 하나하나를 엔드포인트라 한다. health 는 헬스 정보를, beans 는 스프링 컨테이너에 등록된 빈을 보여준다.

각각의 엔드포인트는 /actuator/{엔드포인트명} 과 같은 형식으로 접근할 수 있다.

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

엔드포인트 설정

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

  1. 엔드포인트 활성화
  2. 엔드포인트 노출

엔드포인트를 활성화 한다는 것은 해당 기능 자체를 사용할지 말지 on, off를 선택하는 것이다. 엔드포인트를 노출하는 것은 활성화된 엔드포인트를 HTTP에 노출할지 아니면 JMX에 노출할지 선택하는 것이다. 엔드포인트를 활성화하고 추가로 HTTP를 통해서 웹에 노출할지, 아니면 JMX를 통해서 노출할지 두 위치에 모두 노출할지 노출 위치를 지정해주어야 한다. 물론 활성화가 되어있지 않으면 노출도 되지 않는다. 그런데 엔드포인트는 대부분 기본으로 활성화 되어 있다.( shutdown 제외) 노출이 되어 있지 않을 뿐이다. 따라서 어떤 엔드포인트를 노출할지 선택하면 된다. 참고로 HTTP와 JMX를 선택할 수 있는데, 보통 JMX 는 잘 사용하지 않으므로 HTTP에 어떤 엔드포인트를 노출할지 선택하면 된다.

application.yml - shutdown 엔드포인트 활성화

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

특정 엔드포인트를 활성화 하려면 management.endpoint.{엔드포인트명}.enabled=true 를 적용하면 된다.

http://localhost:4463/actuator/shutdown

{
    "message": "Shutting down, bye..."
}

다양한 엔드포인트

각각의 엔드포인트를 통해서 개발자는 애플리케이션 내부의 수 많은 기능을 관리하고 모니터링 할 수 있다. 스프링 부트가 기본으로 제공하는 다양한 엔드포인트에 대해서 알아보자. 다음은 자주 사용하는 기능 위주로 정리했다.

엔드포인트 목록

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

헬스 정보

헬스 정보를 사용하면 애플리케이션에 문제가 발생했을 때 문제를 빠르게 인지할 수 있다. http://localhost:4463/actuator/health

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

management:
  endpoint:
    health:
      show-details: always

각각의 항목이 아주 자세하게 노출되는 것을 확인할 수 있다. 이렇게 자세하게 노출하는 것이 부담스럽다면 show-details 옵션을 제거하고 대신에 다음 옵션을 사용하면 된다. management.endpoint.health.show-components=always

참고로 액츄에이터는 db , mongo , redis , diskspace , ping 과 같은 수 많은 헬스 기능을 기본으로 제공한다.

애플리케이션 정보

info 엔드포인트는 애플리케이션의 기본 정보를 노출한다.

기본으로 제공하는 기능들은 다음과 같다.

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

info: 
  app:  
    name: hello-actuator
    company: yh

management.info.env.enabled 를 추가하고, info.. 관련 내용을 추가했다.

build 이번에는 빌드 정보를 노출해보자. 빌드 정보를 노출하려면 빌드 시점에 META-INF/build-info.properties 파일을 만들어야 한다. gradle 을 사용하면 다음 내용을 추가하면 된다.

build.gradle - 빌드 정보 추가

springBoot {
    buildInfo()
}

이렇게 하고 빌드를 해보면 build 폴더안에 resources/main/META-INF/build-info.properties 파일을 확인할 수 있다.

git 앞서본 build 와 유사하게 빌드 시점에 사용한 git 정보도 노출할 수 있다. git 정보를 노출하려면 git.properties 파일이 필요하다. build.gradle - 빌드 정보 추가

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

git 에 대한 더 자세한 정보를 보고 싶다면 다음 옵션을 적용하면 된다.

management:
  info:
    git:
      mode: "full"

로거

package hello.controller;

import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@Slf4j
@RestController
public class LogController {
    @GetMapping("/log")
    public String log() {
        log.trace("trace log");
        log.debug("debug log");
        log.info("info log");
        log.warn("warn log");
        log.error("error log");
        return "ok";
    }
}

logging:
  level:
    hello.controller: debug

hello.controller 패키지와 그 하위는 debug 레벨을 출력하도록 했다. 이제 앞서 만든 LogController 클래스도 debug 레벨의 영향을 받는다.

더 자세히 조회하기 다음과 같은 패턴을 사용해서 특정 로거 이름을 기준으로 조회할 수 있다. http://localhost:8080/actuator/loggers/{로거이름}

실시간 로그 레벨 변경 개발 서버는 보통 DEBUG 로그를 사용하지만, 운영 서버는 보통 요청이 아주 많다. 따라서 로그도 너무 많이 남기 때문에 DEBUG 로그까지 모두 출력하게 되면 성능이나 디스크에 영향을 주게 된다. 그래서 운영 서버는 중요하다고 판단되는 INFO 로그 레벨을 사용한다. 그런데 서비스 운영중에 문제가 있어서 급하게 DEBUG 나 TRACE 로그를 남겨서 확인해야 확인하고 싶다면 어떻게 해야할까? 일반적으로는 로깅 설정을 변경하고, 서버를 다시 시작해야 한다. loggers 엔드포인트를 사용하면 애플리케이션을 다시 시작하지 않고, 실시간으로 로그 레벨을 변경할 수 있다.

다음을 Postman 같은 프로그램으로 POST로 요청해보자(꼭! POST를 사용해야 한다.) POST http://localhost:8080/actuator/loggers/hello.controller POST로 전달하는 내용 JSON , content/type 도 application/json 으로 전달해야 한다.

{
    "configuredLevel": "TRACE"
}

요청에 성공하면 204 응답이 온다.(별도의 응답 메시지는 없다.)

HTTP 요청 응답 기록

HTTP 요청과 응답의 과거 기록을 확인하고 싶다면 httpexchanges 엔드포인트를 사용하면 된다. HttpExchangeRepository 인터페이스의 구현체를 빈으로 등록하면 httpexchanges 엔드포인트를 사용할 수 있다.

(주의! 해당 빈을 등록하지 않으면 httpexchanges 엔드포인트가 활성화 되지 않는다)

스프링 부트는 기본으로 InMemoryHttpExchangeRepository 구현체를 제공한다.

@Bean
public InMemoryHttpExchangeRepository httpExchangeRepository() {
  return new InMemoryHttpExchangeRepository();
}

이 구현체는 최대 100개의 HTTP 요청을 제공한다. 최대 요청이 넘어가면 과거 요청을 삭제한다. setCapacity() 로 최대 요청수를 변경할 수 있다.

실행해보면 지금까지 실행한 HTTP 요청과 응답 정보를 확인할 수 있다. 참고로 이 기능은 매우 단순하고 기능에 제한이 많기 때문에 개발 단계에서만 사용하고, 실제 운영 서비스에서는 모니터링 툴이나 핀포인트, Zipkin 같은 다른 기술을 사용하는 것이 좋다.

액츄에이터와 보안

보안 주의 액츄에이터가 제공하는 기능들은 우리 애플리케이션의 내부 정보를 너무 많이 노출한다. 그래서 외부 인터넷 망이 공개된 곳에 액츄에이터의 엔드포인트를 공개하는 것은 보안상 좋은 방안이 아니다. 액츄에이터의 엔드포인트들은 외부 인터넷에서 접근이 불가능하게 막고, 내부에서만 접근 가능한 내부망을 사용하는 것이 안전하다.

액츄에이터를 다른 포트에서 실행 예를 들어서 외부 인터넷 망을 통해서 8080 포트에만 접근할 수 있고, 다른 포트는 내부망에서만 접근할 수 있다면 액츄에이터에 다른 포트를 설정하면 된다. 액츄에이터의 기능을 애플리케이션 서버와는 다른 포트에서 실행하려면 다음과 같이 설정하면 된다. 이 경우 기존 8080 포트에서는 액츄에이터를 접근할 수 없다.

액츄에이터 포트 설정 management.server.port=9292