[스프링 핵심 원리와 활용] 섹션9. 액츄에이터 (1)

[seyeop03]

0x01. 프로덕션 준비 기능이란?

1.1. 프로덕션 준비 기능 = 비 기능적 요소

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

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

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

• 비 기능적 요구사항
  1. 지표(metric), 추적(trace), 감사(auditing)
     • 지표(metric) ⇒ CPU 사용량
     • 추적(trace) ⇒ 로그
     • 감사(auditing) ⇒ 고객 활동 추적
  2. 모니터링(monitoring)

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

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

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

1.2. 프로젝트 설정

프로젝트 설정 순서

1. actuator-start 의 폴더 이름을 actuator 로 변경하자.
2. 프로젝트 임포트
3. File ⇒ Open ⇒ 해당 프로젝트의 build.gradle 선택 ⇒ Open as Project 선택

• build.gradle

  plugins {
      id 'java'
      id 'org.springframework.boot' version '3.0.2'
      id 'io.spring.dependency-management' version '1.1.0'
  }
  
  group = 'hello'
  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()
  }
  

• 스프링 부트에서 다음 라이브러리를 선택했다.

  • Spring Boot Actuator, Spring Web, Spring Data JPA, H2 Database, Lombok

• 테스트 코드에서 lombok을 사용할 수 있도록 설정을 추가했다.

Spring Boot Actuator 라이브러리를 추가한 부분을 확인하자.

• 동작 확인
  • 기본 메인 클래스 실행 : ActuatorApplication.main()
  • http://localhost:8080/ 호출해서 Whitelabel Error Page가 나오면 정상 동작

0x02. 액추에이터

2.1. 액추에이터 시작

액추에이터가 제공하는 프로덕션 준비 기능을 사용하려면 스프링 부트 액추에이터 라이브러리를 추가해야 하는데, 우리는 이미 앞의 프로젝트 설정에서 추가해두었다.

• 동작 확인
  • 기본 메인 클래스 실행 : ActuatorApplication.main()
  • http://localhost:8080/actuator 실행

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

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

  • self 는 자기 자신

  • health 는 우리 서버가 건강하게 잘 작동하냐 안작동하냐에 대한 헬스 상태 정보를 제공해준다.

    • DB는 문제가 없는지, ping은 잘 들어가는지 등등..
    • 화면에 보이는 health 결과를 제공하는 다음 URL도 실행해보자.

    {"status":"UP"}

지금 눈에 보이는 기능은 헬스 상태를 확인할 수 있는 기능 뿐이다. 액추에이터는 헬스 상태 뿐만 아니라 수많은 기능을 제공하는데, 이런 기능이 웹 환경에서 보이도록 노출해야 한다. yml 파일에 다음과 같이 적자.

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

• 동작 확인

  • 기본 메인 클래스 실행 : ActuatorApplication.main()

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

  • http://localhost:8080/actuator 실행 결과

    {
      "_links": {
        "self": {
          "href": "http://localhost:8080/actuator",
          "templated": false
        },
        "beans": {
          "href": "http://localhost:8080/actuator/beans",
          "templated": false
        },
        "caches-cache": {
          "href": "http://localhost:8080/actuator/caches/{cache}",
          "templated": true
        },
        "caches": {
          "href": "http://localhost:8080/actuator/caches",
          "templated": false
        },
        "health": {
          "href": "http://localhost:8080/actuator/health",
          "templated": false
        },
        "health-path": {
          "href": "http://localhost:8080/actuator/health/{*path}",
          "templated": true
        },
        "info": {
          "href": "http://localhost:8080/actuator/info",
          "templated": false
        },
        "conditions": {
          "href": "http://localhost:8080/actuator/conditions",
          "templated": false
        },
        "configprops": {
          "href": "http://localhost:8080/actuator/configprops",
          "templated": false
        },
        "configprops-prefix": {
          "href": "http://localhost:8080/actuator/configprops/{prefix}",
          "templated": true
        },
        "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-requiredMetricName": {
          "href": "http://localhost:8080/actuator/metrics/{requiredMetricName}",
          "templated": true
        },
        "metrics": {
          "href": "http://localhost:8080/actuator/metrics",
          "templated": false
        },
        "scheduledtasks": {
          "href": "http://localhost:8080/actuator/scheduledtasks",
          "templated": false
        },
        "mappings": {
          "href": "http://localhost:8080/actuator/mappings",
          "templated": false
        }
      }
    }

액추에이터가 제공하는 수 많은 기능을 확인할 수 있다. 액추에이터가 제공하는 기능 하나하나를 엔드포인트라 한다. 각각의 엔드 포인트는 /actuator/{엔드포인트명} 과 같은 형식으로 접근할 수 있다.

• ex)
  • http://localhost:8080/actuator/health : 애플리케이션 헬스 정보를 보여준다.
  • http://localhost:8080/actuator/beans : 스프링 컨테이너에 등록된 빈을 한눈에 다 보여준다.
  • http://localhost:8080/actuator/mappings : 컨트롤러에 매핑된 정보를 보여준다.

2.2. 엔드포인트 설정

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

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

엔드포인트를 활성화 한다는 것은 해당 기능 자체를 사용할지 말지 on, off 를 선택하는 것이다.
엔드포인트를 노출하는 것은 활성화된 엔드포인트를 HTTP에 노출할지 아니면 JMX에 노출할지 선택하는 것이다. 엔드포인트를 활성화하고 추가로 HTTP를 통해서 웹에 노출할지, 아니면 JMX를 통해서 노출할지 두 위치에 모두 노출할지 노출 위치를 지정해주어야 한다.

물론 활성화가 되어있지 않으면 노출도 되지 않는다.

그런데 엔드포인트는 대부분 기본으로 활성화되어 있다. (shutdown 제외) 노출이 되어 있지 않을 뿐이다.
따라서 어떤 엔드포인트를 노출할지 선택하면 된다. 참고로 HTTP와 JMX를 선택할 수 있는데, 보통 JMX는 잘 사용하지 않으므로 HTTP에 어떤 엔드포인트를 노출할지 선택하면 된다.

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

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

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

엔드포인트 활성화 + 엔드포인트 노출이 둘다 적용되어야 사용할 수 있다.

(1) shutdown 엔드포인트 활성화

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

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

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

이제 Postman 같은 것을 사용해서 HTTP POST 로 http://localhost:8080/actuator/shutdown 를 호출하면 다음 메시지와 함께 실제 서버가 종료되는 것을 확인할 수 있다.

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

참고로 HTTP GET으로 호출하면 동작하지 않는다.
물론 이 기능은 주의해서 사용해야 한다. 활성화돼있으면 해커들이 그냥 저 엔드포인트 호출 시 모두 꺼버릴 수 있다.. ㅋ 사실 그래서 기본으로 비활성화 되어 있다. 외부 인터넷 망에서 요청이 못 들어오도록 막고, 내부에서만 필요한 경우에만 사용하자!

(2) 엔드포인트 노출

스프링 공식 메뉴얼이 제공하는 예제를 통해서 엔드포인트 노출 설정을 알아보자

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

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

2.3. 다양한 엔드포인트들

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

엔드포인트 목록

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

전체 엔드포인트는 https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html#actuator.endpoints 를 참고하자.

health, info, loggers, httpexchanges, metrics 는 뒤에서 더 자세히 알아보겠다.

• metrics 는 매우 거대한 주제이기 때문에 Chapter 9. 에서 다룬다.

2.4. 헬스 정보 (/actuator/health)

• http://localhost:8080/actuator/health

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

(1) 기본 동작

{"status": "UP"}

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

(2) 컴포넌트 헬스 정보 자세히 보기 : health.show-details

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

management:
	endpoint:
		health:
			show-details: always

endpoints 가 아니라 endpoint 이다. 개별 속성을 디테일하게 설정할 때는 endpoint를 쓴다.

show-details 옵션

{
	"status": "UP", //아래 기능들이 조합되어서 모두 살아있으면 UP, 하나라도 DOWN이면 DOWN
	"components": {
		"db": {
			"status": "UP", //DB가 살아있는지 죽었는지
			"details": {
				"database": "H2",
				"validationQuery": "isValid()" //JDBC 에서 제공, 애플리케이션에서 DB에 확인 요청
			}
		}
	},
	"diskSpace": {
		"status": "UP", //디스크 용량이 꽉 찼는지 아닌지
		"details": {
			"total": 994662584320,
			"free": 303418753024,
			"threshold": 10485760,
			"path": ".../spring-boot/actuator/actuator/.",
			"exists": true
		}
	},
	"ping": {
		"status": "UP"
	}
}

각각의 항목이 아주 자세하게 노출되는 것을 확인할 수 있다.

(3) 각 컴포넌트 헬스 상태 정보만 간략하게 보기 : show-components

위처럼 자세하게 노출하는 것이 부담스럽다면 show-details 옵션을 제거하고 대신에 다음 옵션을 사용하면 된다.

management:
	endpoint:
		health:
			# show-details: always
			show-components: always

show-components 옵션

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

각 헬스 컴포넌트의 상태 정보만 간략하게 노출한다.

(4) 헬스 이상 상태

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

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

여기서는 DB 에 문제가 발생했다. 하나라도 문제가 있으면 DOWN 으로 보기 때문에 이 경우 전체 상태의 status 도 DOWN 이 된다.

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

참고 - 자세한 헬스 기본 지원 기능은 다음 공식 메뉴얼을 참고하자
https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html#actuator.endpoints.health.auto-configured-health-indicators

참고 - 헬스 기능 직접 구현하기
원하는 경우 직접 헬스 기능을 구현해서 추가할 수 있다. 직접 구현하는 일이 많지는 않기 때문에 필요한 경우 다음 공식 메뉴얼을 참고하자
https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html#actuator.endpoints.health.writing-custom-health-indicators