스프링 부트 #5.Actuator

 

5. 스프링 부트 액츄에이터 : 생산 준비 기능

Spring Boot에는 응용 프로그램을 프로덕션 환경으로 푸시 할 때 모니터링하고 관리하는 데 도움이되는 여러 가지 추가 기능이 포함되어 있습니다. HTTP 엔드 포인트 또는 JMX를 사용하여 애플리케이션을 관리하고 모니터링하도록 선택할 수 있습니다. 감사, 상태 및 메트릭 수집도 응용 프로그램에 자동으로 적용될 수 있습니다.

5.1. 생산 준비 기능 활성화

이 spring-boot-actuator모듈은 모든 Spring Boot의 프로덕션 준비 기능을 제공합니다. 기능을 활성화하는 가장 간단한 방법은 spring-boot-starter-actuator'Starter'에 종속성을 추가하는 것 입니다.

액추에이터의 정의

액츄에이터는 물건을 움직이거나 제어하기위한 기계 장치를 의미하는 제조 용어입니다. 액츄에이터는 작은 변화로 많은 양의 모션을 생성 할 수 있습니다.

Maven 기반 프로젝트에 Actuator를 추가하려면 다음 'Starter'종속성을 추가하십시오.

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
</dependencies>

Gradle의 경우 다음 선언을 사용하십시오.

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
}

5.2. 엔드 포인트

액추에이터 엔드 포인트를 사용하면 애플리케이션을 모니터링하고 상호 작용할 수 있습니다. Spring Boot에는 여러 내장 엔드 포인트가 포함되어 있으며 사용자가 직접 추가 할 수 있습니다. 예를 들어, health엔드 포인트는 기본 애플리케이션 상태 정보를 제공합니다.

각 개별 엔드 포인트는 HTTP 또는 JMX를 통해 활성화 또는 비활성화 및 노출 (원격 액세스 가능) 될 수 있습니다 . 엔드 포인트는 사용 가능하고 노출 된 경우 사용 가능한 것으로 간주됩니다. 내장 엔드 포인트는 사용 가능한 경우에만 자동 구성됩니다. 대부분의 응용 프로그램은 HTTP를 통한 노출을 선택합니다. 여기서 접두사와 함께 엔드 포인트의 ID /actuator는 URL에 매핑됩니다. 예를 들어, 기본적으로 health엔드 포인트는에 매핑됩니다 /actuator/health.

다음과 같은 기술에 구애받지 않는 엔드 포인트를 사용할 수 있습니다.

신분증	기술
auditevents	현재 응용 프로그램에 대한 감사 이벤트 정보를 노출합니다. AuditEventRepository콩이 필요합니다 .
beans	애플리케이션에있는 모든 Spring Bean의 전체 목록을 표시합니다.
caches	사용 가능한 캐시를 노출합니다.
conditions	구성 및 자동 구성 클래스에서 평가 된 조건과 해당 클래스가 일치하거나 일치하지 않는 이유를 표시합니다.
configprops	모두의 조합 된 목록을 표시합니다 @ConfigurationProperties.
env	Spring에서 속성을 노출합니다 ConfigurableEnvironment.
flyway	적용된 Flyway 데이터베이스 마이그레이션을 표시합니다. 하나 이상의 Flyway콩이 필요합니다 .
health	응용 프로그램 상태 정보를 표시합니다.
httptrace	HTTP 추적 정보를 표시합니다 (기본적으로 마지막 100 개의 HTTP 요청-응답 교환). HttpTraceRepository콩이 필요합니다 .
info	임의의 응용 프로그램 정보를 표시합니다.
integrationgraph	스프링 통합 그래프를 보여줍니다. 에 대한 종속성이 필요합니다 spring-integration-core.
loggers	응용 프로그램에서 로거의 구성을 표시하고 수정합니다.
liquibase	적용된 Liquibase 데이터베이스 마이그레이션을 표시합니다. 하나 이상의 Liquibase콩이 필요합니다 .
metrics	현재 애플리케이션에 대한 '메트릭'정보를 표시합니다.
mappings	모든 @RequestMapping경로 의 조합 된 목록을 표시 합니다.
scheduledtasks	응용 프로그램에서 예약 된 작업을 표시합니다.
sessions	스프링 세션 지원 세션 저장소에서 사용자 세션을 검색하고 삭제할 수 있습니다. 스프링 세션을 사용하는 서블릿 기반 웹 애플리케이션이 필요합니다.
shutdown	응용 프로그램이 정상적으로 종료되도록합니다. 기본적으로 비활성화되어 있습니다.
threaddump	스레드 덤프를 수행합니다.

애플리케이션이 웹 애플리케이션 (Spring MVC, Spring WebFlux 또는 Jersey) 인 경우 다음 추가 엔드 포인트를 사용할 수 있습니다.

신분증	기술
heapdump	hprof힙 덤프 파일을 반환 합니다.
jolokia	JMX Bean을 HTTP를 통해 노출합니다 (Jolokia가 클래스 경로에 있고 WebFlux에서는 사용할 수없는 경우). 에 대한 종속성이 필요합니다 jolokia-core.
logfile	로그 파일의 내용을 반환합니다 ( logging.file.name또는 logging.file.path속성이 설정된 경우). Range로그 파일 내용의 일부를 검색하기 위해 HTTP 헤더 사용을 지원합니다 .
prometheus	Prometheus 서버에서 스크랩 할 수있는 형식으로 메트릭을 노출합니다. 에 대한 종속성이 필요합니다 micrometer-registry-prometheus.

Actuator의 엔드 포인트 및 요청 및 응답 형식에 대한 자세한 내용은 별도의 API 설명서 ( HTML 또는 PDF ) 를 참조하십시오 .

5.2.1. 엔드 포인트 활성화

기본적으로 제외한 모든 엔드 포인트 shutdown가 사용 가능합니다. 엔드 포인트 사용을 구성하려면 해당 management.endpoint.<id>.enabled특성을 사용하십시오 . 다음 예제는 shutdown엔드 포인트 를 사용 가능하게 합니다.

management.endpoint.shutdown.enabled=true

엔드 포인트 인 에이블먼트가 옵트 아웃이 아닌 옵트 인이 management.endpoints.enabled-by-default되도록 하려면 특성을 설정하고 false개별 엔드 포인트 enabled특성을 사용 하여 다시 옵트 인하십시오. 다음 예제는 info엔드 포인트를 사용 가능 하게하고 다른 모든 엔드 포인트를 사용 불가능하게합니다.

management.endpoints.enabled-by-default=false
management.endpoint.info.enabled=true

비활성화 된 엔드 포인트는 응용 프로그램 컨텍스트에서 완전히 제거됩니다. 엔드 포인트가 노출되는 기술 만 변경하려면 include및 exclude특성을 대신 사용하십시오 .

5.2.2. 엔드 포인트 노출

엔드 포인트는 민감한 정보를 포함 할 수 있으므로 노출시기에 대해 신중하게 고려해야합니다. 다음 표는 내장 엔드 포인트의 기본 노출을 보여줍니다.

신분증	JMX	편물
auditevents	예	아니
beans	예	아니
caches	예	아니
conditions	예	아니
configprops	예	아니
env	예	아니
flyway	예	아니
health	예	예
heapdump	해당 없음	아니
httptrace	예	아니
info	예	예
integrationgraph	예	아니
jolokia	해당 없음	아니
logfile	해당 없음	아니
loggers	예	아니
liquibase	예	아니
metrics	예	아니
mappings	예	아니
prometheus	해당 없음	아니
scheduledtasks	예	아니
sessions	예	아니
shutdown	예	아니
threaddump	예	아니

노출되는 엔드 포인트를 변경하려면 다음 기술 별 include및 exclude특성을 사용하십시오.

특성	기본
management.endpoints.jmx.exposure.exclude
management.endpoints.jmx.exposure.include	*
management.endpoints.web.exposure.exclude
management.endpoints.web.exposure.include	info, health

이 include특성은 노출 된 엔드 포인트의 ID를 나열합니다. 이 exclude특성은 노출해서는 안되는 엔드 포인트의 ID를 나열합니다. exclude속성 이 속성보다 우선 include합니다. 모두 include와 exclude속성은 엔드 포인트 ID의 목록을 구성 할 수 있습니다.

예를 들어, JMX에 대한 모든 엔드 포인트 노출을 중지하고 health및 info엔드 포인트 만 노출 시키 려면 다음 특성을 사용하십시오.

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

*모든 엔드 포인트를 선택하는 데 사용할 수 있습니다. 예를 들어, 제외하고 HTTP를 통해 모든 것을 폭로 env하고 beans다음과 같은 속성을 사용하여 엔드 포인트 :

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

* YAML에는 특별한 의미가 있으므로 다음 예제와 같이 모든 엔드 포인트를 포함 (또는 제외)하려면 따옴표를 추가하십시오. management: endpoints: web: exposure: include: "*"

애플리케이션이 공개적으로 노출되는 경우 엔드 포인트 도 보호 하는 것이 좋습니다 .

엔드 포인트가 노출되는시기에 대한 고유 한 전략을 구현하려는 경우 EndpointFilterBean을 등록 할 수 있습니다 .

5.2.3. HTTP 엔드 포인트 보안

다른 민감한 URL과 동일한 방식으로 HTTP 엔드 포인트를 보호해야합니다. Spring Security가 존재하면 스프링 보안의 컨텐츠 협상 전략을 사용하여 엔드 포인트가 기본적으로 보호됩니다. 예를 들어 특정 역할을 가진 사용자 만 액세스 할 수 있도록 HTTP 엔드 포인트에 대한 사용자 정의 보안을 구성하려는 경우 Spring Boot는 RequestMatcherSpring Security와 함께 사용할 수있는 편리한 오브젝트를 제공합니다 .

일반적인 스프링 보안 구성은 다음 예제와 유사합니다.

@Configuration(proxyBeanMethods = false)
public class ActuatorSecurity extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.requestMatcher(EndpointRequest.toAnyEndpoint()).authorizeRequests((requests) ->
                requests.anyRequest().hasRole("ENDPOINT_ADMIN"));
        http.httpBasic();
    }

}

앞의 예제는 EndpointRequest.toAnyEndpoint()요청을 모든 엔드 포인트와 일치시키는 데 사용 되며 모두 ENDPOINT_ADMIN역할을 갖도록합니다 . 에서 다른 여러 가지 matcher 메소드도 사용할 수 있습니다 EndpointRequest. 자세한 내용은 API 설명서 ( HTML 또는 PDF )를 참조하십시오.

방화벽 뒤에 응용 프로그램을 배포하는 경우 인증없이 모든 액추에이터 끝점에 액세스 할 수 있습니다. management.endpoints.web.exposure.include다음과 같이 속성 을 변경하면 됩니다.

application.properties

management.endpoints.web.exposure.include=*

또한 Spring Security가있는 경우 다음 예제와 같이 엔드 포인트에 대한 인증되지 않은 액세스를 허용하는 사용자 정의 보안 구성을 추가해야합니다.

@Configuration(proxyBeanMethods = false)
public class ActuatorSecurity extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.requestMatcher(EndpointRequest.toAnyEndpoint()).authorizeRequests((requests) ->
            requests.anyRequest().permitAll());
    }

}

5.2.4. 엔드 포인트 구성

끝점은 매개 변수를 사용하지 않는 읽기 작업에 대한 응답을 자동으로 캐시합니다. 엔드 포인트가 응답을 캐시하는 시간을 구성하려면 해당 cache.time-to-live특성을 사용하십시오 . 다음 예제는 beans엔드 포인트 캐시의 유효 기간을 10 초로 설정합니다.

application.properties

management.endpoint.beans.cache.time-to-live=10s

접두사 management.endpoint.<name>는 구성중인 엔드 포인트를 고유하게 식별하는 데 사용됩니다.

5.2.5. 액추에이터 웹 엔드 포인트 용 하이퍼 미디어

모든 엔드 포인트에 대한 링크와 함께 "검색 페이지"가 ​​추가됩니다. "검색 페이지"는 /actuator기본적으로 사용 가능합니다 .

사용자 지정 관리 컨텍스트 경로가 구성되면 "검색 페이지"가 ​​자동으로 /actuator관리 컨텍스트의 루트로 이동 합니다. 예를 들어 관리 컨텍스트 경로가 /management인 경우 검색 페이지를에서 사용할 수 있습니다 /management. 관리 컨텍스트 경로가로 설정 /되면 감지 페이지가 사용 불가능하여 다른 맵핑과의 충돌 가능성을 방지합니다.

5.2.6. CORS 지원

CORS ( Cross-Origin Resource Sharing )는 W3C 사양 으로, 어떤 종류의 도메인 간 요청이 승인되는지 유연하게 지정할 수 있습니다. Spring MVC 또는 Spring WebFlux를 사용하는 경우 이러한 시나리오를 지원하도록 Actuator의 웹 엔드 포인트를 구성 할 수 있습니다.

CORS 지원은 기본적으로 비활성화되어 있으며 management.endpoints.web.cors.allowed-origins속성이 설정된 후에 만 활성화 됩니다. 다음 구성 은 도메인 에서 허용 GET하고 POST호출 example.com합니다.

management.endpoints.web.cors.allowed-origins=https://example.com
management.endpoints.web.cors.allowed-methods=GET,POST

전체 옵션 목록은 CorsEndpointProperties 를 참조하십시오 .

5.2.7. 커스텀 엔드 포인트 구현

당신은 추가 할 경우 @Bean주석이 @Endpoint주석으로, 어떤 방법을 @ReadOperation, @WriteOperation또는 @DeleteOperation웹 응용 프로그램에서, 이상 HTTP뿐만 아니라를 자동으로 JMX를 통해 노출합니다. Jersey, Spring MVC 또는 Spring WebFlux를 사용하여 엔드 포인트를 HTTP를 통해 노출 할 수 있습니다. Jersey와 Spring MVC를 모두 사용할 수 있으면 Spring MVC가 사용됩니다.

당신은 또한 수 사용하여 쓰기 기술 특정 엔드 포인트 @JmxEndpoint나 @WebEndpoint. 이 엔드 포인트는 해당 기술로 제한됩니다. 예를 들어, @WebEndpointJMX가 아닌 HTTP를 통해서만 노출됩니다.

당신은을 사용하여 특정 기술 확장을 쓸 수 @EndpointWebExtension및 @EndpointJmxExtension. 이러한 주석을 통해 기술 별 작업을 제공하여 기존 엔드 포인트를 보강 할 수 있습니다.

마지막으로, 웹 프레임 워크 별 기능에 액세스해야하는 경우 JMX를 통해 사용할 수 없거나 다른 웹 프레임 워크를 사용할 때 Servlet 또는 Spring @Controller및 @RestController엔드 포인트를 구현할 수 있습니다 .

입력 받기

엔드 포인트에서의 조작은 해당 매개 변수를 통해 입력을받습니다. 웹을 통해 노출되는 경우 이러한 매개 변수의 값은 URL의 조회 매개 변수 및 JSON 요청 본문에서 가져옵니다. JMX를 통해 노출되면 매개 변수는 MBean 조작의 매개 변수에 맵핑됩니다. 기본적으로 매개 변수가 필요합니다. 로 주석을 달아 선택 사항으로 만들 수 있습니다 @org.springframework.lang.Nullable.

JSON 요청 본문의 각 루트 속성은 끝점의 매개 변수에 매핑 될 수 있습니다. 다음 JSON 요청 본문을 고려하십시오.

{
    "name": "test",
    "counter": 42
}

이것은 소요 쓰기 작업을 호출하는 데 사용할 수 있습니다 String name및 int counter매개 변수를.

엔드 포인트는 기술에 구애받지 않기 때문에 메소드 서명에 단순한 유형 만 지정할 수 있습니다. 특히 name및 counter속성을 정의하는 사용자 정의 유형으로 단일 매개 변수를 선언하는 것은 지원되지 않습니다.

입력을 조작 메소드의 매개 변수에 맵핑하려면 엔드 포인트를 구현하는 Java 코드를로 컴파일해야하고 엔드 포인트를 구현하는 -parametersKotlin 코드를로 컴파일해야합니다 -java-parameters. Spring Boot의 Gradle 플러그인을 사용하거나 Maven 및을 사용하는 경우 자동으로 발생합니다 spring-boot-starter-parent.

입력 타입 변환

엔드 포인트 조작 메소드로 전달 된 매개 변수는 필요한 경우 자동으로 필수 유형으로 변환됩니다. 동작 메소드를 호출하기 전에, 입력 JMX 통해 수신 또는 HTTP 요청의 예를 사용하여 필요한 형식으로 변환되어 ApplicationConversionService있는뿐만 아니라 Converter또는 GenericConverter콩과 자격을 @EndpointConverter.

사용자 정의 웹 엔드 포인트

온 조작 @Endpoint, @WebEndpoint또는 @EndpointWebExtension자동 뉴저지, 스프링 MVC, 또는 봄 WebFlux를 사용하여 HTTP를 통해 노출된다. Jersey와 Spring MVC를 모두 사용할 수 있으면 Spring MVC가 사용됩니다.

웹 엔드 포인트 요청 술어

웹 노출 엔드 포인트에서 각 조작에 대해 요청 술어가 자동으로 생성됩니다.

통로

술어의 경로는 엔드 포인트의 ID와 웹 노출 엔드 포인트의 기본 경로에 의해 결정됩니다. 기본 기본 경로는 /actuator입니다. 예를 들어, ID sessions가 있는 엔드 포인트 /actuator/sessions는 술어에서 경로로 사용합니다.

로 조작 방법의 하나 이상의 매개 변수에 주석을 달아 경로를 추가로 사용자 정의 할 수 있습니다 @Selector. 이러한 매개 변수는 경로 술어에 경로 변수로 추가됩니다. 엔드 포인트 조작이 호출 될 때 변수 값이 조작 메소드로 전달됩니다. 나머지 모든 경로 요소를 캡처하려는 경우 @Selector(Match=ALL_REMAINING)마지막 매개 변수에 추가 하고이 매개 변수를로 변환 가능한 유형으로 만들 수 있습니다 String[].

HTTP 메소드

술어의 HTTP 메소드는 다음 테이블에 표시된대로 조작 유형에 따라 결정됩니다.

조작	HTTP 메소드
@ReadOperation	GET
@WriteOperation	POST
@DeleteOperation	DELETE

소비

요청 본문을 사용 하는 @WriteOperation(HTTP POST)의 경우 술어의 소비 절은입니다 application/vnd.spring-boot.actuator.v2+json, application/json. 다른 모든 조작의 경우 소비 절이 비어 있습니다.

생산

는 술어의 절은에 의해 결정될 수 생산 produces의 특성 @DeleteOperation, @ReadOperation및 @WriteOperation주석. 이 속성은 선택 사항입니다. 사용하지 않으면 produce 절이 자동으로 결정됩니다.

조작 메소드가 리턴 void되거나 Voidproduce 절이 비어있는 경우 오퍼레이션 메소드가를 리턴 org.springframework.core.io.Resource하면 produce 절은 application/octet-stream입니다. 다른 모든 연산에 대해 produce 절은 application/vnd.spring-boot.actuator.v2+json, application/json입니다.

웹 엔드 포인트 응답 상태

엔드 포인트 조작의 기본 응답 상태는 조작 유형 (읽기, 쓰기 또는 삭제) 및 조작이 리턴하는 항목에 따라 다릅니다.

A @ReadOperation는 값을 반환하며 응답 상태는 200 (확인)입니다. 값을 반환하지 않으면 응답 상태는 404 (찾을 수 없음)입니다.

a @WriteOperation또는 @DeleteOperation값을 반환하면 응답 상태는 200 (확인)입니다. 값을 반환하지 않으면 응답 상태는 204 (No Content)입니다.

필수 매개 변수없이 또는 필수 유형으로 변환 할 수없는 매개 변수를 사용하여 조작을 호출하면 조작 메소드가 호출되지 않고 응답 상태는 400 (잘못된 요청)이됩니다.

웹 엔드 포인트 범위 요청

HTTP 범위 요청을 사용하여 HTTP 자원의 일부를 요청할 수 있습니다. Spring MVC 또는 Spring Web Flux를 사용하는 경우 org.springframework.core.io.Resource자동으로 범위 요청 을 리턴하는 오퍼레이션 .

Jersey를 사용할 때는 범위 요청이 지원되지 않습니다.

웹 엔드 포인트 보안

웹 엔드 포인트 또는 웹 특정 엔드 포인트 확장에서의 조작은 현재 java.security.Principal또는 org.springframework.boot.actuate.endpoint.SecurityContext메소드 매개 변수로 수신 할 수 있습니다 . 전자는 일반적으로 @Nullable인증 된 사용자와 인증되지 않은 사용자에게 서로 다른 동작을 제공하기 위해 사용됩니다 . 후자는 일반적으로 isUserInRole(String)방법을 사용하여 권한 확인을 수행하는 데 사용됩니다 .

서블릿 엔드 포인트

(A)는 Servlet주석 클래스 구현하여 엔드 포인트로 노출 될 수있다 @ServletEndpoint즉도 구현이 Supplier<EndpointServlet>. 서블릿 엔드 포인트는 서블릿 컨테이너와의 긴밀한 통합을 제공하지만 이식성을 희생합니다. 기존 Servlet엔드 포인트로 노출하기 위해 사용됩니다 . 새 엔드 포인트의 경우 가능할 때마다 @Endpoint및 @WebEndpoint주석을 선호해야합니다.

컨트롤러 엔드 포인트

@ControllerEndpoint그리고 @RestControllerEndpoint에만 스프링 MVC 또는 봄 WebFlux에 의해 노출되는 엔드 포인트를 구현하는 데 사용할 수 있습니다. 방법은 같은 스프링과 스프링 MVC WebFlux 표준 주석을 사용하여 매핑된다 @RequestMapping과 @GetMapping종점의 ID 경로에 대한 프리픽스로 사용되면서. 컨트롤러 엔드 포인트는 Spring의 웹 프레임 워크와보다 긴밀한 통합을 제공하지만 이식성을 희생합니다. @Endpoint및 @WebEndpoint주석이 가능한 것이 바람직 할 것이다.

5.2.8. 건강 정보

상태 정보를 사용하여 실행중인 응용 프로그램의 상태를 확인할 수 있습니다. 프로덕션 시스템이 다운 될 때 누군가에게 경고하기 위해 모니터링 소프트웨어에서 자주 사용됩니다. health엔드 포인트에 의해 노출되는 정보 는 다음 값 중 하나로 구성 할 수있는 management.endpoint.health.show-details및 management.endpoint.health.show-components특성 에 따라 다릅니다 .

이름	기술
never	세부 사항은 표시되지 않습니다.
when-authorized	세부 사항은 권한이있는 사용자에게만 표시됩니다. 권한이 부여 된 역할은을 사용하여 구성 할 수 있습니다 management.endpoint.health.roles.
always	세부 사항은 모든 사용자에게 표시됩니다.

기본값은 never입니다. 사용자는 하나 이상의 엔드 포인트 역할에있을 때 권한이 부여 된 것으로 간주됩니다. 엔드 포인트에 구성된 역할이없는 경우 (기본값) 모든 인증 된 사용자는 권한이 부여 된 것으로 간주됩니다. management.endpoint.health.roles속성을 사용하여 역할을 구성 할 수 있습니다 .

애플리케이션을 보호하고 사용하려는 경우 always보안 구성은 인증 된 사용자와 인증되지 않은 사용자 모두의 상태 엔드 포인트에 대한 액세스를 허용해야합니다.

건강 정보는의 콘텐츠에서 수집됩니다 HealthContributorRegistry(기본적으로에 HealthContributor정의 된 모든 인스턴스 ApplicationContext). Spring Boot에는 여러 가지 자동 구성 기능이 포함되어 HealthContributors있으며 직접 작성할 수도 있습니다.

A HealthContributor는 a HealthIndicator또는 a 일 수 CompositeHealthContributor있습니다. 를 HealthIndicator포함하여 실제 건강 정보를 제공합니다 Status. A CompositeHealthContributor는 다른 것의 합성을 제공합니다 HealthContributors. 기고자들은 종합적으로 전체 시스템 상태를 나타내는 트리 구조를 형성합니다.

기본적으로 최종 시스템 상태는 StatusAggregator정렬 된 상태 HealthIndicator목록을 기반으로 각 상태를 정렬합니다 . 정렬 된 목록의 첫 번째 상태는 전체 상태로 사용됩니다. 어떤이 경우 HealthIndicator받는 알려진 상태를 반환 StatusAggregator, UNKNOWN상태는 사용되지 않습니다.

는 HealthContributorRegistry런타임시 및 등록 취소의 건강 지표를 등록 할 수 있습니다.

자동 구성 상태 표시기

다음 HealthIndicators은 Spring Boot에서 적절한 경우 자동 구성됩니다.

이름	기술
CassandraHealthIndicator	Cassandra 데이터베이스가 작동 중인지 확인합니다.
CouchbaseHealthIndicator	Couchbase 클러스터가 작동 중인지 확인합니다.
DataSourceHealthIndicator	연결할 DataSource수 있는지 확인합니다 .
DiskSpaceHealthIndicator	디스크 공간이 부족한지 확인합니다.
ElasticSearchRestHealthContributorAutoConfiguration	Elasticsearch 클러스터가 작동 중인지 확인합니다.
HazelcastHealthIndicator	Hazelcast 서버가 작동 중인지 확인합니다.
InfluxDbHealthIndicator	InfluxDB 서버가 작동 중인지 확인합니다.
JmsHealthIndicator	JMS 브로커가 작동 중인지 확인합니다.
LdapHealthIndicator	LDAP 서버가 작동 중인지 확인합니다.
LivenessStateHealthIndicator	"Liveness"애플리케이션 가용성 상태를 노출합니다.
MailHealthIndicator	메일 서버가 작동 중인지 확인합니다.
MongoHealthIndicator	Mongo 데이터베이스가 작동 중인지 확인합니다.
Neo4jHealthIndicator	Neo4j 데이터베이스가 작동 중인지 확인합니다.
PingHealthIndicator	항상로 응답합니다 UP.
RabbitHealthIndicator	토끼 서버가 작동 중인지 확인합니다.
ReadinessStateHealthIndicator	"준비"응용 프로그램 가용성 상태를 표시합니다.
RedisHealthIndicator	Redis 서버가 작동 중인지 확인합니다.
SolrHealthIndicator	Solr 서버가 작동 중인지 확인합니다.

management.health.defaults.enabled속성 을 설정하여 모두 비활성화 할 수 있습니다 .

맞춤형 건강 지표 작성

사용자 정의 건강 정보를 제공하기 위해 HealthIndicator인터페이스 를 구현하는 Spring Bean을 등록 할 수 있습니다 . health()메소드 의 구현을 제공 하고 Health응답을 리턴해야합니다 . Health응답은 상태를 포함해야하고 선택적으로 표시 할 추가 정보를 포함 할 수 있습니다. 다음 코드는 샘플 HealthIndicator구현을 보여줍니다 .

import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;

@Component
public class MyHealthIndicator implements HealthIndicator {

    @Override
    public Health health() {
        int errorCode = check(); // perform some specific health check
        if (errorCode != 0) {
            return Health.down().withDetail("Error Code", errorCode).build();
        }
        return Health.up().build();
    }

}

제공된 식별자 HealthIndicator는 HealthIndicator접미사가 없는 Bean의 이름입니다 (있는 경우). 위의 예에서 상태 정보는이라는 항목에서 사용할 수 있습니다 my.

Spring Boot의 미리 정의 된 Status유형 외에도 새로운 시스템 상태를 나타내는 Health사용자 정의를 반환 할 수도 있습니다 Status. 이러한 경우 StatusAggregator인터페이스 의 사용자 정의 구현 도 제공하거나 management.endpoint.health.status.order구성 특성 을 사용하여 기본 구현을 구성해야합니다.

예를 들어, 구현 중 하나에서 새로운 Status코드 FATAL를 사용 한다고 가정합니다 HealthIndicator. 심각도 순서를 구성하려면 응용 프로그램 속성에 다음 속성을 추가하십시오.

management.endpoint.health.status.order=fatal,down,out-of-service,unknown,up

응답의 HTTP 상태 코드는 전반적인 상태를 반영합니다. 기본적으로, OUT_OF_SERVICE및 DOWN포함, 503에 모든 매핑되지 않은 건강 상태를지도 UP당신은 또한 HTTP를 통해 건강 엔드 포인트에 액세스하는 경우 사용자 정의 상태 매핑을 등록 할 수 있습니다 (200)에 매핑. 사용자 정의 매핑을 구성하면 DOWN및에 대한 기본 매핑이 비활성화 OUT_OF_SERVICE됩니다. 기본 매핑을 유지하려면 사용자 지정 매핑과 함께 명시 적으로 구성해야합니다. 예를 들어 다음 속성은 FATAL503 (서비스를 사용할 수 없음)에 매핑되고 DOWN및에 대한 기본 매핑을 유지합니다 OUT_OF_SERVICE.

management.endpoint.health.status.http-mapping.down=503
management.endpoint.health.status.http-mapping.fatal=503
management.endpoint.health.status.http-mapping.out-of-service=503

더 많은 제어가 필요한 경우 고유 한 HttpCodeStatusMapperBean을 정의 할 수 있습니다 .

다음 표는 내장 상태에 대한 기본 상태 매핑을 보여줍니다.

상태	매핑
내려가는	SERVICE_UNAVAILABLE (503)
OUT_OF_SERVICE	SERVICE_UNAVAILABLE (503)
쪽으로	기본적으로 매핑이 없으므로 http 상태는 200입니다.
알 수 없는	기본적으로 매핑이 없으므로 http 상태는 200입니다.

반응성 건강 지표

Spring WebFlux를 사용하는 것과 같은 반응 형 애플리케이션의 경우 ReactiveHealthContributor애플리케이션 상태를 얻기위한 비 차단 계약을 제공합니다. 전통적인 HealthContributor, 건강 정보는의 콘텐츠에서 ReactiveHealthContributorRegistry기본적으로 수집됩니다 (기본적으로에 정의 된 모든 인스턴스 HealthContributor및 ReactiveHealthContributor인스턴스 ApplicationContext). HealthContributors반응 형 API를 확인하지 않는 일반 규칙 은 탄력적 스케줄러에서 실행됩니다.

반응 형 응용 프로그램에서는 ReactiveHealthContributorRegistry런타임시 상태 표시기를 등록 및 등록 취소하는 데 사용해야합니다. 당신이 정기적으로 등록 해야하는 경우 HealthContributor, 당신은 그것을 사용하여 포장해야합니다 ReactiveHealthContributor#adapt.

반응 형 API에서 사용자 정의 상태 정보를 제공하기 위해 ReactiveHealthIndicator인터페이스 를 구현하는 Spring Bean을 등록 할 수 있습니다 . 다음 코드는 샘플 ReactiveHealthIndicator구현을 보여줍니다 .

@Component
public class MyReactiveHealthIndicator implements ReactiveHealthIndicator {

    @Override
    public Mono<Health> health() {
        return doHealthCheck() //perform some specific health check that returns a Mono<Health>
            .onErrorResume(ex -> Mono.just(new Health.Builder().down(ex).build()));
    }

}

오류를 자동으로 처리하려면에서 확장을 고려하십시오 AbstractReactiveHealthIndicator.

자동 구성된 ReactiveHealthIndicators

다음 ReactiveHealthIndicators은 Spring Boot에서 적절한 경우 자동 구성됩니다.

이름	기술
CassandraReactiveHealthIndicator	Cassandra 데이터베이스가 작동 중인지 확인합니다.
CouchbaseReactiveHealthIndicator	Couchbase 클러스터가 작동 중인지 확인합니다.
MongoReactiveHealthIndicator	Mongo 데이터베이스가 작동 중인지 확인합니다.
RedisReactiveHealthIndicator	Redis 서버가 작동 중인지 확인합니다.

필요한 경우 반응성 표시기가 일반 표시기를 대체합니다. 또한 HealthIndicator명시 적으로 처리되지 않은 항목은 자동으로 줄 바꿈됩니다.

건강 그룹

건강 지표를 여러 목적으로 사용할 수있는 그룹으로 구성하는 것이 유용한 경우가 있습니다.

상태 표시기 그룹을 만들려면이 management.endpoint.health.group.<name>속성을 사용하고 상태 표시기 ID 목록을 include또는에 지정할 수 있습니다 exclude. 예를 들어 데이터베이스 표시기 만 포함하는 그룹을 만들려면 다음을 정의 할 수 있습니다.

management.endpoint.health.group.custom.include=db

그런 다음을 눌러 결과를 확인할 수 있습니다 localhost:8080/actuator/health/custom.

기본적으로 그룹은 시스템 상태 StatusAggregator와 동일한 HttpCodeStatusMapper설정을 상속 받지만 그룹별로 정의 할 수도 있습니다. 필요한 경우 show-details및 roles속성 을 재정의 할 수도 있습니다 .

management.endpoint.health.group.custom.show-details=when-authorized
management.endpoint.health.group.custom.roles=admin
management.endpoint.health.group.custom.status.order=fatal,up
management.endpoint.health.group.custom.status.http-mapping.fatal=500
management.endpoint.health.group.custom.status.http-mapping.out-of-service=500

그룹과 함께 사용할 @Qualifier("groupname")사용자 정의 StatusAggregator또는 HttpCodeStatusMapperBean 을 등록해야하는 경우 사용할 수 있습니다 .

5.2.9. 쿠 버네 티스 프로브

Kubernetes에 배포 된 응용 프로그램은 컨테이너 프로브를 통해 내부 상태에 대한 정보를 제공 할 수 있습니다 . 에 따라 귀하는 Kubernetes 구성 의 kubelet 그 프로브를 호출하고 그 결과에 반응한다.

Spring Boot는 즉시 사용 가능한 응용 프로그램 가용성 상태를 관리합니다 . 는 Kubernetes 환경에서 배포 한 경우, 액추에이터는에서 "활동성"와 "준비"정보를 수집합니다 ApplicationAvailability인터페이스를 전용에 그 정보를 사용하여 건강 지표 : LivenessStateHealthIndicator와 ReadinessStateHealthIndicator. 이 지표는 글로벌 상태 엔드 포인트 ( "/actuator/health") 에 표시됩니다 . 또한 Health Groups : "/actuator/health/liveness"및을 사용하여 별도의 HTTP 프로브로 노출됩니다 "/actuator/health/readiness".

그런 다음 다음 엔드 포인트 정보를 사용하여 Kubernetes 인프라를 구성 할 수 있습니다.

livenessProbe:
  httpGet:
    path: /actuator/health/liveness
    port: <actuator-port>
  failureThreshold: ...
  periodSeconds: ...

readinessProbe:
  httpGet:
    path: /actuator/health/readiness
    port: <actuator-port>
  failureThreshold: ...
  periodSeconds: ...

<actuator-port>액추에이터 엔드 포인트가 사용 가능한 포트로 설정되어야합니다. 기본 웹 서버 포트이거나 "management.server.port"특성이 설정된 경우 별도의 관리 포트 일 수 있습니다.

이러한 상태 그룹은 응용 프로그램이 Kubernetes 환경에서 실행중인 경우에만 자동으로 활성화됩니다 . management.health.probes.enabled구성 특성을 사용하여 모든 환경에서이를 사용할 수 있습니다 .

응용 프로그램이 구성된 활성 기간보다 시작하는 데 시간이 오래 걸리면 Kubernetes "startupProbe"는 가능한 해결책으로 언급합니다 . 은 "startupProbe"반드시이 여기에 필요하지 않은 "readinessProbe"모든 시작 작업이 완료 될 때까지 참조 실패 애플리케이션 라이프 사이클 동안 어떻게 프로브 동작합니다을 .

Actuator 엔드 포인트가 별도의 관리 컨텍스트에 배치 된 경우 엔드 포인트가 기본 애플리케이션과 동일한 웹 인프라 (포트, 연결 풀, 프레임 워크 구성 요소)를 사용하지 않는다는 점에 유의하십시오. 이 경우 주 응용 프로그램이 제대로 작동하지 않더라도 (예 : 새 연결을 수락 할 수없는 경우) 프로브 검사에 성공할 수 있습니다.

Kubernetes Probes로 외부 상태 확인

Actuator는 "liveness"및 "readiness"프로브를 Health Groups로 구성합니다. 이는 모든 건강 그룹 기능 을 사용할 수 있음을 의미합니다. 예를 들어 추가 상태 표시기를 구성 할 수 있습니다.

management.endpoint.health.group.readiness.include=readinessState,customCheck

기본적으로 Spring Boot는 이러한 그룹에 다른 상태 표시기를 추가하지 않습니다.

"liveness"프로브는 외부 시스템의 상태 점검에 의존해서는 안됩니다. 응용 프로그램 의 라이브 상태 가 깨지면 Kubernetes는 응용 프로그램 인스턴스를 다시 시작하여 해당 문제를 해결하려고 시도합니다. 즉, 외부 시스템 (예 : 데이터베이스, 웹 API, 외부 캐시)에 오류가 발생하면 Kubernetes가 모든 응용 프로그램 인스턴스를 다시 시작하고 계단식 오류가 발생할 수 있습니다.

“준비”프로브의 경우, 외부 시스템 검사는 응용 프로그램 개발자가 신중하게 선택해야합니다. 즉, Spring Boot는 준비 프로브에 추가 상태 검사를 포함하지 않습니다. 응용 프로그램 인스턴스 의 준비 상태 인 경우준비가되지 않으면 Kubernetes는 트래픽을 해당 인스턴스로 라우팅하지 않습니다. 일부 외부 시스템은 응용 프로그램 인스턴스와 공유하지 않을 수 있으며이 경우 준비 프로브에 자연스럽게 포함될 수 있습니다. 다른 외부 시스템은 응용 프로그램에 필수적이지 않을 수 있습니다 (응용 프로그램에는 회로 차단기와 폴 백이있을 수 있음). 이러한 경우에는 반드시 포함시키지 않아야합니다. 불행하게도, 모든 응용 프로그램 인스턴스가 공유하는 외부 시스템이 일반적이므로 판단 요청을해야합니다. 준비 프로브에 포함시키고 외부 서비스가 다운 될 때 응용 프로그램이 작동하지 않을 것으로 예상합니다. 예를 들어 호출자에서 회로 차단기를 사용하여 스택에서 더 높은 장애를 처리합니다.

응용 프로그램의 모든 인스턴스가 준비되지 않은 경우 Kubernetes 서비스는 들어오는 연결 을 type=ClusterIP받거나 NodePort받지 않습니다. 연결이 없기 때문에 HTTP 오류 응답 (503 등)이 없습니다. 있는 서비스 type=LoadBalancer세력 또는 공급자에 따라 연결을 허용하지 않을 수 있습니다. 명시적인 Ingress 가있는 서비스 도 구현에 따라 달라지는 방식으로 응답합니다. Ingress 서비스 자체는 다운 스트림에서 "연결이 거부 된"연결을 처리하는 방법을 결정해야합니다. HTTP 503은로드 밸런서와 수신 모두에 해당 될 가능성이 높습니다.

또한 응용 프로그램이 Kubernetes 자동 확장을 사용하는 경우 자동 확장 프로그램 구성에 따라로드 밸런서에서 제거되는 응용 프로그램에 다르게 반응 할 수 있습니다.

응용 프로그램 수명주기 및 프로브 상태

Kubernetes Probes 지원의 중요한 측면은 응용 프로그램 수명주기와의 일관성입니다. Spring Boot는 시작 및 종료 중에 응용 프로그램 이벤트를 게시 합니다.

스프링 부트 애플리케이션이 시작될 때 :

응용 프로그램 시작 단계	활동 상태	준비 상태	노트
시작	BROKEN	REFUSING_TRAFFIC	Kubernetes는 "liveness"프로브를 확인하고 너무 오래 걸리면 응용 프로그램을 다시 시작합니다.
시작	CORRECT	REFUSING_TRAFFIC	응용 프로그램 컨텍스트가 새로 고쳐집니다. 응용 프로그램이 시작 작업을 수행하고 아직 트래픽을받지 않습니다.
준비된	CORRECT	ACCEPTING_TRAFFIC	시작 작업이 완료되었습니다. 애플리케이션이 트래픽을 수신 중입니다.

스프링 부트 애플리케이션이 종료 될 때 :

응용 프로그램 종료 단계	활동 상태	준비 상태	노트
달리는	라이브	준비된	종료가 요청되었습니다.
정상 종료	라이브	준비되지 않은	활성화 된 경우 정상 종료가 진행중인 요청을 처리합니다 .
종료 완료	부서진	준비되지 않은	응용 프로그램 컨텍스트가 닫히고 응용 프로그램이 트래픽을 처리 할 수 ​​없습니다.

Kubernetes 배포에 대한 자세한 내용은 Kubernetes 컨테이너 수명주기 섹션 을 확인하십시오 .

5.2.10. 신청 정보

응용 프로그램 정보에는에 InfoContributor정의 된 모든 Bean 에서 수집 된 다양한 정보 가 표시 ApplicationContext됩니다. Spring Boot에는 여러 개의 자동 구성 InfoContributorBean이 포함되어 있으며 직접 작성할 수 있습니다.

자동 구성된 InfoContributors

다음 InfoContributorBean은 적절한 경우 Spring Boot에 의해 자동 구성됩니다.

이름	기술
EnvironmentInfoContributor	키 Environment아래의 info키를 노출 시킵니다 .
GitInfoContributor	git.properties파일이 사용 가능한 경우 git 정보를 노출 합니다.
BuildInfoContributor	META-INF/build-info.properties파일이 사용 가능한 경우 빌드 정보를 노출 합니다.

management.info.defaults.enabled속성 을 설정하여 모두 비활성화 할 수 있습니다.

맞춤형 응용 프로그램 정보

스프링 특성 info을 설정 하여 엔드 포인트가 표시 하는 데이터를 사용자 정의 할 수 있습니다 info.*. 키 Environment아래의 모든 속성 info이 자동으로 노출됩니다. 예를 들어 application.properties파일에 다음 설정을 추가 할 수 있습니다 .

info.app.encoding=UTF-8
info.app.java.source=1.8
info.app.java.target=1.8

이러한 값을 하드 코딩하지 않고 빌드시 정보 속성을 확장 할 수도 있습니다 . Maven을 사용한다고 가정하면 다음과 같이 이전 예제를 다시 작성할 수 있습니다. info.app.encoding=@project.build.sourceEncoding@ info.app.java.source=@java.version@ info.app.java.target=@java.version@

힘내 커밋 정보

info엔드 포인트 의 또 다른 유용한 기능은 git프로젝트가 빌드 될 때 소스 코드 저장소 의 상태에 대한 정보를 공개하는 기능 입니다. 경우 GitProperties콩이, 사용할 수있는 git.branch, git.commit.id그리고 git.commit.time속성이 노출됩니다.

GitProperties빈은 자동 구성된 경우입니다 git.properties파일을 클래스 패스의 루트에 사용할 수 있습니다. 자세한 내용은 " git 정보 생성 "을 참조하십시오.

전체 자식 정보 (즉, 전체 콘텐츠 git.properties)를 표시하려면 management.info.git.mode다음과 같이 속성을 사용하십시오 .

management.info.git.mode=full

빌드 정보

경우 BuildProperties콩을 사용할 수의 info엔드 포인트는 빌드에 대한 정보를 게시 할 수 있습니다. META-INF/build-info.properties클래스 경로에서 파일을 사용할 수있는 경우에 발생합니다 .

Maven 및 Gradle 플러그인은 모두 해당 파일을 생성 할 수 있습니다. 자세한 내용은 " 빌드 정보 생성 "을 참조하십시오.

사용자 정의 정보 제공자 작성

커스텀 애플리케이션 정보를 제공하기 위해 InfoContributor인터페이스 를 구현하는 Spring Bean을 등록 할 수 있습니다 .

다음 예제 example는 단일 값으로 항목을 제공합니다.

import java.util.Collections;

import org.springframework.boot.actuate.info.Info;
import org.springframework.boot.actuate.info.InfoContributor;
import org.springframework.stereotype.Component;

@Component
public class ExampleInfoContributor implements InfoContributor {

    @Override
    public void contribute(Info.Builder builder) {
        builder.withDetail("example",
                Collections.singletonMap("key", "value"));
    }

}

info엔드 포인트에 도달 하면 다음과 같은 추가 항목이 포함 된 응답이 표시됩니다.

{
    "example": {
        "key" : "value"
    }
}

 

Spring Boot Reference Documentation Phillip Webb, Dave Syer, Josh Long, Stéphane Nicoll, Rob Winch, Andy Wilkinson, Marcel Overdijk, Christian Dupuis, Sébastien Deleuze, Michael Simons, Vedran Pavić, Jay Bryant, Madhura Bhave, Eddú Meléndez, Scott Frederick Legal 2.3.1.RELEASE Copyright © 2012-2020 Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.

출처 : https://docs.spring.io/spring-boot/docs/2.3.1.RELEASE/reference/htmlsingle/#production-ready