📚 스프링 액추에이터(Spring Actuator)

• 스프링 부트가 제공하는 강력한 모니터링 및 관리 도구
• 마이크로미터, 프로메테우스, 그라파나 같은 모니터링 시스템과 매우 쉽게 연동 가능

의존성 주입

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

📌 동작 확인

• 의존성을 주입하면 http://localhost:8080/actuator 를 실행했을 때 이러한 정보들이 나오는 것을 확인 할 수 있다.

{
  "_links": {
    "self": {
      "href": "http://localhost:8080/actuator",
        "templated": false
   },
     "health-path": {
       "href":
       "http://localhost:8080/actuator/health/{*path}",
         "templated": true
   },
     "health": {
       "href": "http://localhost:8080/actuator/health",
         "templated": false
   }
}

화면에 보이는 http://localhost:8080/actuator/health를 실행해보면

{"status": "UP"}

를 확인 할 수있는 데 이 정보는 서버가 잘 동작하고 있는지 애플리케이션 헬스 상태를 보여준다.
하지만 이건 헬스 상태만 보여주는 것이고

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

을 설정해주고(참고로 shutdown을 제외한 모든 엔드포인트를 웹에 노출하는 설정이다.) http://localhost:8080/actuator를 호출하면

{
  "_links": {
    "self": {
      "href": "http://localhost:8080/actuator",
      "templated": false
    },
    "beans": {
      "href": "http://localhost:8080/actuator/beans",
      "templated": false
    },
    "caches": {
      "href": "http://localhost:8080/actuator/caches",
      "templated": false
    },
    "caches-cache": {
      "href": "http://localhost:8080/actuator/caches/{cache}",
      "templated": true
    },
    "health-path": {
      "href": "http://localhost:8080/actuator/health/{*path}",
      "templated": true
    },
    "health": {
      "href": "http://localhost:8080/actuator/health",
      "templated": false
    },
    "info": {
      "href": "http://localhost:8080/actuator/info",
      "templated": false
    },
    "conditions": {
      "href": "http://localhost:8080/actuator/conditions",
      "templated": false
    },
    "configprops-prefix": {
      "href": "http://localhost:8080/actuator/configprops/{prefix}",
      "templated": true
    },
    "configprops": {
      "href": "http://localhost:8080/actuator/configprops",
      "templated": false
    },
    "env": {
      "href": "http://localhost:8080/actuator/env",
      "templated": false
    },
    "env-toMatch": {
      "href": "http://localhost:8080/actuator/env/{toMatch}",
      "templated": true
    },
    "loggers": {
      "href": "http://localhost:8080/actuator/loggers",
      "templated": false
    },
    "loggers-name": {
      "href": "http://localhost:8080/actuator/loggers/{name}",
      "templated": true
    },
    "heapdump": {
      "href": "http://localhost:8080/actuator/heapdump",
      "templated": false
    },
    "threaddump": {
      "href": "http://localhost:8080/actuator/threaddump",
      "templated": false
    },
    "metrics": {
      "href": "http://localhost:8080/actuator/metrics",
      "templated": false
    },
    "metrics-requiredMetricName": {
      "href": "http://localhost:8080/actuator/metrics/{requiredMetricName}",
      "templated": true
    },
    "scheduledtasks": {
      "href": "http://localhost:8080/actuator/scheduledtasks",
      "templated": false
    },
    "mappings": {
      "href": "http://localhost:8080/actuator/mappings",
      "templated": false
    }
  }
}

이렇게 많은 기능들을 확인 가능하다.

엔드포인트(EndPoint)

• 액추에이터가 제공하는 기능 하나하나를 엔드포인트(EndPoint)라고 한다.
• 각각의 엔드포인트(EndPoint)는 /actuator/{엔드포인트명}으로 접근이 가능하다.
  예시) http://localhost:8080/actuator/health

📌 엔드포인트 설정

대부분의 엔드포인트(EndPoint)는 활성화 되어있지만(shutdown 제외) 설정으로 어떤 엔드포인트를 노출할지 선택이 가능하다.

특정 엔드포인트 설정

management:
 endpoint:
  shutdown:
   enabled: true

• 특정 엔드포인트를 활성화 하기 위해서는 management.endpoint.{엔드포인트명}.enabled=true 적용
• shutdown을 활성화 시키고 http://localhost:8080/actuator/shutdown POST 요청하면 서버가 종료

📌 다양한 엔드포인트

• beans: 스프링 컨테이너에 등록된 스프링 빈을 보여준다.
• conditions: 빈을 등록할 때 평가 조건과 일치하거나 일치하지 않는 이유를 보여준다.
• configprops: @ConfigurationProperties 정보를 보여준다.
• env: 애플리케이션의 환경(Environment) 정보를 보여준다.
• health: 애플리케이션의 헬스 상태를 보여준다.
• httpexchanges: HTTP 호출 및 응답 정보를 제공한다. (HttpExchangeRepository를 구현한 빈 필요)
• info: 애플리케이션 정보를 보여준다.
• loggers: 로거 설정을 확인하고 변경할 수 있다.
• metrics: 애플리케이션의 메트릭 정보를 보여준다.
• mappings: @RequestMapping 정보를 보여준다.
• threaddump: 쓰레드 덤프를 실행하여 보여준다.
• shutdown: 애플리케이션을 종료한다. (기본적으로 비활성화되어 있음)

Endpoints

1) health

http://localhost:8080/actuator/health

애플리케이션에 문제가 발생하면 빠르게 문제 파악 가능

좀 더 자세하게 보기 위해서는 다음과 같은 설정 필요

management:
 endpoint:
  health:
   show-details: always

각각의 항목이 아주 자세하게 노출되는것이 부담스러우면

management:
 endpoint:
  health:
   show-components: always

show-details 제거

헬스 이상 상태

{
  "status": "DOWN",
  "components": {
    "db": {
      "status": "DOWN"
    },
    "diskSpace": {
      "status": "UP"
    },
    "ping": {
      "status": "UP"
    }
  }
}

• 헬스 컴포넌트중에 하나라도 문제가 발생하면 전체 상태는 Down

추가적으로 db,mongo,redis,diskspace,ping 같은 수 많은 헬스 기능 제공

• Auto-configured HealthIndicators
• Writing Custom HealthIndicators

2) Info

애플리케이션 기본 정보를 노출

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

처음 실행하면 정보가 보이지 않는다. 따라서 설정해준다.

java,OS 정보 확인

application.yml

management:
 info:
  java:
   enabled: true
os:
 enabled: true

• management.info.<id>.enabeld 값 true지정

http://localhost:8080/actuator/info 실행

env

application.yml

management:
 info:
  env:
   enabled: true
info:
 app:
  name: hello-actuator
   company: yh

build

빌드 정보 노출을 위해서는 META-INF/build-info.properties 을 생성

build.gradle - 빌드 정보 추가

springBoot {
  buildInfo()
}

{
  "build": {
    "artifact": "actuator",
    "name": "actuator",
    "time": "2023-01-01T00:00:00.000Z",
    "version": "0.0.1-SNAPSHOT",
    "group": "hello"
  }
}

loggers

loggers 엔드포인트를 사용하면 로깅과 관련된 정보를 확인하고, 또 실시간으로 변경 가능

package yuhan.actuatorstart;

@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";
    }

}

application.yml 설정

logging:
  level:
    yuhan.actuatorstart: debug

• LogController 클래스도 debug 레벨의 영향을 받는다.

http://localhost:8080/actuator/loggers 을 실행해보면

{
  "levels": [
    "OFF",
    "ERROR",
    "WARN",
    "INFO",
    "DEBUG",
    "TRACE"
  ],
  "loggers": {
    "ROOT": {
      "configuredLevel": "INFO",
      "effectiveLevel": "INFO"
    },
    "_org.springframework": {
      "effectiveLevel": "INFO"
    },
    "yuhan": {
      "effectiveLevel": "INFO"
    },
    "yuhan.ActuatorApplication": {
      "effectiveLevel": "INFO"
    },
    "yuhan.actuatorstart": {
      "configuredLevel": "DEBUG",
      "effectiveLevel": "DEBUG"
    },
    " yuhan.actuatorstart.LogController": {
      "effectiveLevel": "DEBUG"
    }
  }
}

이렇게 로그 정보들을 확인 할 수 있다.

🤔

• 로그를 별도로 설정하지 않으면 스프링 부트는 기본으로 INFO를 사용
  우리는 yuhan.actuatorstart 는 DEBUG
  로 설정했다.
• 그래서 해당 부분에서 configuredLevel이 DEBUG로 설정된 것을 확인할 수 있다. 그리고 그 하위도 DEBUG 레벨이 적용
• http://localhost:8080/actuator/loggers/yuhan.actuatorstart로 더 자세한 조회 가능

‼️ 실시간 로그 레벨 변경

운영 서버는 보통 요청도 많고 로그도 너무 많이 남기 때문에 DEBUG로 출력하게 되면 성능이나 디스크에 영향을 준다. 그래서 운영 서버는 중요하다고 판단되는 INFO 로그 레벨을 사용

• loggers 엔드포인트를 사용하면 애플리케이션을 다시 시작하지 않고, 실시간으로 로그 레벨을 변경 가능

http://localhost:8080/actuator/loggers/yuhan.actuatorstar 에다가 POST 로 전송하고

{
 "configuredLevel": "TRACE"
}

GET으로 요청해서 확인해보면 configuredLevel 이 TRACE
http://localhost:8080/actuator/loggers/yuhan.actuatorstar
로 변경된 것을 확인할 수 있다.

{
 "configuredLevel": "TRACE",
 "effectiveLevel": "TRACE"
}

📌 액추에이터와 보안

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

액츄에이터를 다른 포트에서 실행

• 예를 들어서 외부 인터넷 망을 통해서 8080 포트에만 접근할 수 있고, 다른 포트는 내부망에서만 접근할 수 있다면 액추에이터에 다른 포트를 설정

액츄에이터 포트 설정

management.server.port=9292

참고 :

• 김영한 - 스프링 부트 - 핵심 원리와 활용
• 액추에이터 (Spring Boot Actuator)