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

[im1sun]

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

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

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

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

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

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

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

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

2.프로젝트 설정

프로젝트 설정 순서

1. actuator-start 의 폴더 이름을 actuator 로 변경하자.
2. 프로젝트 임포트

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가 나오면 정상 동작

3.액츄에이터 시작

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

build.gradle - 추가

implementation 'org.springframework.boot:spring-boot-starter-actuator' //actuator 추가

동작 확인

• 기본 메인 클래스 실행(ActuatorApplication.main() )
• 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
        }
    }
}

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

화면에 보이는 health 결과를 제공하는 다음 URL도 실행해보자.
http://localhost:8080/actuator/health

{"status": "UP"}

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

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

액츄에이터 기능을 웹에 노출
application.yml - 추가

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

동작 확인

• 기본 메인 클래스 실행(ActuatorApplication.main() )
• 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
        }
    }
}

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

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

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

4.엔드포인트 설정

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

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

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

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

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

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

"*" 옵션은 모든 엔드포인트를 웹에 노출하는 것이다. 참고로 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으로 호출하면 동작하지 않는다.
물론 이 기능은 주의해서 사용해야 한다. 그래서 기본으로 비활성화 되어 있다.

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

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

• jmx 에 health,info 를 노출한다.

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

• web 에 모든 엔드포인트를 노출하지만 env , beans 는 제외한다.

5.다양한 엔드포인트

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

엔드포인트 목록

• 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 는 뒤에서 더 자세히 알아보겠다.

6.헬스 정보

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

기본 동작

{"status": "UP"}

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

헬스 정보를 더 자세히 보려면 다음 옵션을 지정하면 된다.
management.endpoint.health.show-details=always

management:
    endpoint:
        health:
            show-details: always

show-details 옵션

{
    "status": "UP",
    "components": {
        "db": {
            "status": "UP",
            "details": {
                "database": "H2",
                "validationQuery": "isValid()"
            }
        },
        "diskSpace": {
            "status": "UP",
            "details": {
                "total": 994662584320,
                "free": 303418753024,
                "threshold": 10485760,
                "path": ".../spring-boot/actuator/actuator/.",
                "exists": true
            }
        },
        "ping": {
            "status": "UP"
        }
    }
}

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

management.endpoint.health.show-components=always

management:
    endpoint:
        health:
            show-components: always

show-components 옵션

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

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

헬스 이상 상태
헬스 컴포넌트 중에 하나라도 문제가 있으면 전체 상태는 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