[액추에이터] - 액추에이터(Actuator) 시작하기

 

 

 

 

🧐 프로덕션 준비 기능

애플리케이션을 개발할 때에는 기능적은 요구사항만을 개발하는 것이 아닙니다.

서비스를 실제 배포한 이후 서비스에 문제가 없는지 모니터링하는 활동들이 추가로 필요합니다.

운영 환경에서 애플리케이션을 실행할 때 필요한 이러한 기능들을 프로덕션 준비 기능이라 합니다.

즉 프로덕션을 운영에 배포할 때 준비해야 하는 비 기능적 요소들을 의미합니다.

 

다음과 같은 것들이 프로덕션 준비 기능에 속합니다.

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

이들은 애플리케이션이 현재 살아있는지, 로그 정보는 정상적으로 설정되었는지, 커넥션 풀은 얼마나 사용되고 있는지 등을 확인하는데 사용됩니다.

 

 

 

 

 

 

 

 

 

 

🧐 스프링 부트 액추에이터

스프링 부트가 제공하는 액추에이터는 프로덕션 준비 기능을 위한 다양한 기능들을 제공합니다.

또한 마이크로미터, 프로메테우스, 그라파나와 같은 최근 유행하는 모니터링 시스템들과도 쉽게 연동할 수 있도록 지원합니다.

 

 

 

 

 

 

 

 

 

 

 

🧐 액추에이터 시작하기

⚙️ Build.gradle

plugins {
	id 'java'
	id 'org.springframework.boot' version '3.0.6'
	id 'io.spring.dependency-management' version '1.1.0'
}

group = 'actuator.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '17'

configurations {
	compileOnly {
		extendsFrom annotationProcessor
	}
}

repositories {
	mavenCentral()
}

dependencies {
	implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
	implementation 'org.springframework.boot:spring-boot-starter-web'
	implementation 'org.springframework.boot:spring-boot-starter-actuator' //actuator 추가

	compileOnly 'org.projectlombok:lombok'
	runtimeOnly 'com.h2database:h2'
	annotationProcessor 'org.projectlombok:lombok'
	testImplementation 'org.springframework.boot:spring-boot-starter-test'

	//test lombok 사용
	testCompileOnly 'org.projectlombok:lombok'
	testAnnotationProcessor 'org.projectlombok:lombok'
}

tasks.named('test') {
	useJUnitPlatform()
}

간단히 actuator, jpa, web, lombok, h2만을 추가하였습니다.

 

 

 

 

 

프로젝트를 시작한 뒤, http://localhost:8080/actuator로 요청을 보내면 다음과 같은 화면을 볼 수 있습니다.

 

나와있는 주소들 중 http://localhost:8080/actuator/health 로 접속을 하면 다음과 같은 화면을 볼 수 있습니다.

 

위 기능은 형재 서버가 잘 동작하고 있는지 애플리케이션의 헬스 상태를 나타냅니다.

 

 

아무런 설정을 하지 않은 상태에서 확인할 수 있는 기능들을 헬스 상태를 확인할 수 있는 기능 뿐입니다.

 

액추에이터는 헬스 상태 뿐만 아니라 다른 많은 기능들을 제공하는데, 이들을 웹 환경에서 볼 수 있도록 하기 위해 다음과 같이 설정할 수 있습니다.

 

⚙️ application.yml

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

이후 다시 http://localhost:8080/actuator로 요청을 보내면 다음과 같은 결과를 얻을 수 있습니다.

 

액추에이터가 제공하는 수많은 기능들을 확인할 수 있습니다.

이들에 대한 설명은 공식 문서를 참고해주세요.

 

 

 

 

 

액추에이터가 제공하는 기능 하나하나를 엔드포인트라 부릅니다.

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

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

 

 

 

 

 

 

 

 

 

🧐 엔드포인트 설정

엔드포인트를 사용하려면 엔트포인트를 활성화하고, 이를 노출시켜야 합니다.

엔드포인트를 활성화 한다는 것은 해당 기능 자체를 사용할지 말지를 선택하는 것입니다.

엔드포인트를 노출한다는 것은 활성화된 엔드포인트를 HTTP에 노출할지 혹은 JMX에 노출할지 선택하는 것을 의미합니다.

 

엔드포인트를 활성화하고 추가로 HTTP를 통해서 웹에 노출할지, 아니면 JMX를 통해서 노출할지, 혹은 두 위치 모두에 노출할지 등 노출 위치를 지정해주어야 합니다.

 

활성화가 되어 있지 않으면 노출은 되지 않습니다.

즉 활성화가 선행되어야 합니다.

 

 

엔드포인트는 대부분 기본으로 활성화되어 있습니다.

shutdown을 제외한 엔드포인트는 모두 기본적으로 활성화되어 있으며, 단지 노출이 되어 있지 않을 뿐입니다.

따라서 어떤 엔드포인트를 노출할지 선택하면 됩니다.

참고로 HTTP와 JMX를 선택할 수 있는데, 보통 JMX는 잘 사용하지 않으므로 HTTP에 어떤 엔드포인트를 노출할지 선택하면 됩니다.

 

 

 

 

⚙️ application.yml - 모든 엔드포인트를 웹에 노출

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

* 옵션은 모든 엔드포인트를 웹에 노출하는 것입니다. 참고로 shutdown 엔드포인트는 기본으로 활성화 되어 있지 않기 때문에 노출도 되지 않습니다.

 

 

 

 

 

 

 

 

🤔 엔드포인트 활성화하기

management.endpoint.{엔드포인트명}.enabled=true를 통해 특정 엔드포인트를 활성화할 수 있습니다.

 

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

management:
  endpoint:
    shutdown:
      enabled: true # shutdown 엔드포인트 활성화
      
  endpoints:
    web:
      exposure:
        include: "*"

 

 

 

 

 

 

 

 

🤔 엔드포인트 노출하기

management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=env,beans

위와 같은 설정을 통해 엔드포인트의 노출 여부를 설정할 수 있으며, 예를 들어 위 예시의 경우 env와 beans를 제외한 모든 엔드포인트를 노출한다는 의미가 됩니다.

 

 

xml에 대해 설정하기 위해서는 web을 xml로 설정하면 됩니다.

management.endpoints.jmx.exposure.include=health,info

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

🧐 헬스 정보 - health 엔드포인트

헬스 정보를 사용하면 애플리케이션에 문제가 발생했을 때 문제를 빠르게 인지할 수 있습니다.

위에서 살펴봤지만, /actuator/health로 접속하면 다음과 같은 결과를 얻을 수 있습니다.

 

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

 

 

다음과 같은 속성을 통해서 헬스 정보를 더 자세히 확인할 수 있습니다.

management:
  endpoint:
    health:
      show-details: always # 기본은 never이며, when-authorized 라는 옵션도 존재

 

 

결과는 다음과 같습니다.

 

 

 

 

 

show-details는 너무 상세하기 때문에, 조금 더 간단히 보기 위해서는 show-components를 설정할 수 있습니다.

management:
  endpoint:
    health:
      show-components: always

 

결과는 다음과 같습니다.

 

 

 

이외에도 자세한 헬스 관련 기능은 다음 공식문서를 통해 확인할 수 있습니다.

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

 

 

 

헬스 기능을 직접 구현할 수도 있는데, 이러한 방법에 대해서도 공식 문서를 통해 확인할 수 있습니다.

https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html#actuator.endpoints.health.writing-custom-health-indicators

 

 

 

 

 

 

 

 

 

 

🧐 애플리케이션 정보 - info 엔드포인트

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

기본적으로 제공하는 기능들은 java, os, env, build, git 이며 각각에 대한 설명은 다음과 같습니다.

 

 

📕 java

자바 런타임 정보를 제공합니다.

기본으로 비활성화 되어있습니다.

 

다음과 같은 설정을 통해 활성화를 진행할 수 있습니다.

management:
  info:
    java:
      enabled: true

조회 결과는 다음과 같습니다.

 

 

 

 

 

 

 

 

📙 os

OS(운영체제) 정보를 제공합니다.

기본으로 비활성화 되어있습니다.

 

다음과 같은 설정을 통해 활성화를 진행할 수 있습니다.

management:
  info:
    os:
      enabled: true

조회 결과는 다음과 같습니다.

 

 

 

 

 

 

 

📒 env

Enviroment에서 info 로 시작하는 정보를 제공합니다.

기본으로 비활성화 되어있습니다.

 

다음과 같은 설정을 통해 활성화를 진행할 수 있습니다.

management:
  endpoints:
    web:
      exposure:
        include: "*"
        
  info:
    env:
      enabled: true


info:
  app:
    name: mallang  # info.~~~ 이므로 보여진다.

some:
  env: no show  # info로 시작하지 않으므로 보여지지 않는다.

 

결과는 다음과 같습니다.

 

 

 

 

 

 

 

📗 build

빌드 정보를 제공합니다.

META-INF/build-info.properties 파일이 필요합니다.

기본으로 활성화 되어있습니다.

 

 

해당 정보를 보기 위해서는 build.gradle에 다음과 같은 코드를 추가해주어야 합니다.

(다음 링크 참고)

springBoot {
	buildInfo()
}

 

이후 빌드 시 다음과 같이 build/resources/main/META-INF/build.info.properties 파일이 생성이 됩니다.

 

 

 

/actuator/info로 들어가면 다음과 같은 정보를 확인할 수 있습니다.

 

 

 

 

 

 

 

 

📘 git

git 정보를 제공합니다.

git.properties 파일이 필요합니다.

기본으로 활성화 되어있습니다.

 

이를 위해서는 우선 다음과 같이 git properties 플러그인이 필요합니다.

(다음 링크 참고)

plugins {
	id 'java'
	id 'org.springframework.boot' version '3.0.6'
	id 'io.spring.dependency-management' version '1.1.0'
	id "com.gorylenko.gradle-git-properties" version "2.4.1"  // git info 추가
}

 

 

 

이후 빌드하면 다음과 같이 git.properties 파일이 생성된 것을 알 수 있습니다.

 

 

/actuator/info로 들어가면 다음과 같은 정보를 확인할 수 있습니다.

 

 

 

다음과 같이 설정하면 git에 대한 더 자세한 정보를 볼 수 있습니다.

management:
  info:
    git:
      mode: full

 

결과는 다음과 같습니다.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

🧐 로그 정보 - loggers 엔드포인트

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

이는 코드를 통해 알아보도록 하겠습니다.

 

 

 

다음과 같이 간단한 컨트롤러를 하나 생성했습니다.

@Slf4j
@RestController
public class LogController {

    @GetMapping("/log")
    String log() {
        log.trace("trace");
        log.debug("debug");
        log.info("info");
        log.warn("warn");
        log.error("error");

        return "ok";
    }
}

 

 

 

 

 

기본적으로 요청을 보낸다면, 로그 결과는 다음과 같습니다.

기본 설정된 로그 레벨이 info이기 때문에 위와 같은 결과가 나온 것입니다.

 

 

 

 

 

 

이제 로그 레벨 설정을 진행하도록 하겠습니다.

logging:
  level:
    컨트롤러_전체_패키지_경로: debug

위와 같이 설정한 이후 다시 요청을 보내면 결과는 아래와 같습니다.

 

 

 

 

 

현재 상태에서 loggers 엔드포인트를 호출하면 결과는 다음과 같습니다.

 

 

 

 

 

 

 

 

 

🤔 더 자세히 조회하기

다음과 같이 특정 로거 이름을 기준으로 조회하는 것도 가능합니다.

/actuator/loggers/{로거이름}

예를 들어 /actuator/loggers/actuator.example.actuator 처럼 조회하면 결과는 다음과 같습니다.

 

 

 

 

 

 

 

 

 

🤔 실시간 로그 레벨 변경

개발 서버는 보통 DEBUG 로그를 사용합니다.

그러나 운영 서버는 요청이 매우 많으므로 DEBUG 로그까지 모두 출력하게 된다면 성능이나 디스크에 영향을 줄 수 있습니다.

따라서 운영 서버에는 DEBUG 대신 INFO 로그 레벨을 주로 사용합니다.

 

 

 

그런데 서비스 운영 중에 문제가 생겨서 급하게 DEBUG나 TRACE 로그를 남겨서 확인하고 싶은 부분이 있다면 어떻게 해야할까요?

일반적으로는 로깅 설정을 변경하고 서버를 다시 시작해야 합니다.

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

 

다음 요청을 포스트맨을 통해 POST 메서드를 사용하여 요청해보도록 하겠습니다.

POST - http://localhost:8080/actuator/loggers/actuator.example.actuator
content-type : application/json
body
{
     "configuredLevel": "TRACE"
}

이후 다시  /actuator/loggers/actuator.example.actuator 로 들어가면 다음과 같이 로그 레벨이 변경된 것을 알 수 있습니다.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

🧐 HTTP 요청 응답 기록 - httpexchanges 엔드포인트

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

httpexchange 엔드포인트는 HttpExchangedRepository 인터페이스의 구현체를 빈으로 등록하면 사용할 수 있습니다.

(이때 HttpExchangedRepository 빈이 등록되지 않으면 httpexchange 엔드포인트가 활성화되지 않습니다.)

 

 

 

 

다음과 같이 예시를 위한 이미 정의되어있는 간단한 InMemory 구현체를 사용하도록 하겠습니다.

@SpringBootApplication
public class ActuatorApplication {

	public static void main(String[] args) {
		SpringApplication.run(ActuatorApplication.class, args);
	}

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

 

 

 

 

 

이후 log 로 요청을 보낸 뒤, /actuator/httpexchanges로 들어가면 결과는 다음과 같습니다.

 

참고로 해당 기능은 매우 단순하고 기능에 제한이 많기 때문에 개발 단계에서만 사용하고,
실제 운영 서비스에서는 모니터링 툴이나 핀포인트, Zipkin 같은 다른 기술을 사용하는 것이 좋습니다.

 

 

 

 

 

 

 

 

 

 

 

 

🧐 액추에이터와 보안

액추에이터가 제공하는 기능들은 확인했던것과 같이 애플리케이션의 내부 정보를 너무 많이 노출한다는 문제점이 있습니다.

따라서 외부 인터넷 망이 공개된 곳에 액추에이터의 엔드포인트를 공개하는 것은 보안상 좋지 않은 방법입니다.

 

액추에이터의 엔드포인트들은 외부 인터넷에서 접근이 불가능하게 막고, 내부에서만 접근 가능한 내부망을 사용하는 것이 안전합니다.

 

 

 

 

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

예를 들어 외부 인터넷 망을 통해서는 8080 포트에만 접근할 수 있고,

다른 포트는 내부망에서만 접근할 수 있다면, 액추에이터는 다른 포트를 설정하면 됩니다.

management.server.port=설정할 포트번토

 

 

 

 

 

📙 액추에이터 URL 경로에 인증 설정하기

상황에 따라서는 포트를 분리하는 것이 어렵고, 어쩔 수 없이 외부 인터넷 망을 통해서 접근해야 하는 경우가 있을 수 있습니다.

이러한 경우 /actuator 경로에 서블릿 필터, 스프링 인터셉터 또는 스프링 시큐리티를 통해서 인증된 사용자만 접근 가능하도록 추가 개발이 필요합니다.

 

 

 

 

 

 

 

 

 

 

🧐 참고 - 엔트포인트 경로 변경

management:
  endpoints:
    web:
      base-path: /XXX

 

 

 

 

 

 

 

 

 

📚 Reference

[스프링 부트 - 핵심 원리와 활용. 섹션 8] - 김영한님