스프링 부트 공식 레퍼런스를 한글로 번역한 문서입니다.

전체 목차는 여기에 있습니다.

목차

• 12.12.1. Change the HTTP Port or Address of the Actuator Endpoints
• 12.12.2. Customize the ‘whitelabel’ Error Page
• 12.12.3. Sanitize Sensitive Values
• 12.12.4. Map Health Indicators to Micrometer Metrics

---

12.12. Actuator

스프링 부트에는 스프링 부트 액추에이터가 포함돼 있다. 이번 섹션에선 액추에이터를 사용할 때 많이 묻는 질문들에 답해본다.

12.12.1. Change the HTTP Port or Address of the Actuator Endpoints

독립 실행형 애플리케이션에선 기본적으로 Actuator HTTP 포트는 메인 HTTP 포트와 동일하게 설정된다. 다른 포트에서 수신^listen하도록 만드려면 외부 프로퍼티 management.server.port를 설정해라. 완전히 다른 네트워크 주소에서 수신^listen하려면 (management에는 내부 네트워크를 사용하고 사용자 애플리케이션에선 외부 네트워크를 사용하는 등), management.server.address를 서버가 바인딩할 수 있는 유효한 IP 주소로 설정할 수도 있다.

자세한 내용은 ManagementServerProperties 소스 코드와, “Production-ready features” 섹션에 있는 “Management 서버 포트 커스텀하기“를 참고해라.

12.12.2. Customize the ‘whitelabel’ Error Page

스프링 부트는 서버 에러가 발생했을 때 브라우저 클라이언트에게 보여줄 ‘whitelabel’ 에러 페이지를 마련해준다 (JSON이나 다른 미디어 타입을 받을 수 있는 머신 클라이언트는 적당한 에러 코드를 가지고 있는 응답을 볼 수 있을 거다).

디폴트 에러 페이지를 꺼버리려면 server.error.whitelabel.enabled=false를 설정해라. 이렇게 하면 사용 중인 서블릿 컨테이너의 기본값이 복원된다. 단, 스프링 부트는 그래도 에러 뷰 리졸브를 시도해보기 때문에, 완전히 비활성화하기보다는 자체 에러 페이지를 추가해야 할 거다.

에러 페이지를 재정의하는 방법은 사용하는 템플릿 기술에 따라 다르다. 예를 들어 Thymeleaf를 사용할 때는 error.html 템플릿을 추가하면 된다. FreeMarker를 사용한다면 error.ftlh 템플릿을 추가하면 된다. 대개는 error라는 이름으로 리졸브하는 View나, /error 경로를 처리하는 @Controller가 필요하다. 디폴트 설정 몇 가지를 바꿔주지 않는 한 ApplicationContext에서 BeanNameViewResolver를 찾을 수 있기 때문에, error라는 이름을 가진 @Bean을 등록하는 것도 한 가지 방법이 될 수 있다. 다른 옵션들은 ErrorMvcAutoConfiguration을 참고해라.

서블릿 컨테이너에 핸들러를 등록하는 자세한 방법은 “에러 핸들링” 섹션을 참고해라.

12.12.3. Sanitize Sensitive Values

env와 configprops 엔드포인트에서 반환하는 정보는 다소 민감한 정보일 수 있기 때문에, 특정한 패턴에 매칭되는 키들은 기본적으로 가려준다 (******으로 대체된다). 스프링 부트는 합리적인 기본값을 사용해 가려야할 키를 선별한다. “password”, “secret”, “key”, “token”, “vcap_services”, “sun.java.command”라는 단어로 끝나는 모든 키는 전부 가린다. 키에 credentials란 단어가 들어가있을 때도 (*credentials.*라는 정규 표현식으로 설정한다) 모두 가린다.

뿐만 아니라 스프링 부트는 다음 중 하나로 끝나는 키에서도 URI같은 값이 있다면 민감한 부분을 제거해준다:

• address
• addresses
• uri
• uris
• url
• urls

URI에 있는 민감한 정보는 <scheme>://<username>:<password>@<host>:<port>/ 포맷을 통해 식별한다. 예를 들어 myclient.uri=http://user1:password1@localhost:8081 프로퍼티의 경우, 민감 정보를 제거하고 난 결과는 http://user1:******@localhost:8081이다.

env, configprops 엔드포인트에서 사용하는 디폴트 패턴은 각각 management.endpoint.env.keys-to-sanitize와 management.endpoint.configprops.keys-to-sanitize를 통해 수정할 수 있다. 아니면 management.endpoint.env.additional-keys-to-sanitize와 management.endpoint.configprops.additional-keys-to-sanitize를 사용하면 패턴을 추가로 설정할 수 있다.

12.12.4. Map Health Indicators to Micrometer Metrics

스프링 부트 health indicator는 전반적인 시스템 상태를 나타내는 Status 타입을 반환한다. 특정 애플리케이션의 상태를 모니터링하고 상태 수준에 따라 알림을 발송하고 싶다면, Micrometer를 통해 이런 상태 정보를 메트릭으로 익스포트하면 된다. 기본적으로 스프링 부트에서 사용하는 상태 코드 “UP”, “DOWN”, “OUT_OF_SERVICE”, “UNKNOWN”이다. 이 상태 값을 익스포트하려면, Micrometer Gauge와 함께 사용할 수 있도록 몇 가지 숫자 셋으로 변환해줘야 한다.

다음은 이럴 때 필요한 exporter를 작성하는 한 가지 방법을 보여주는 예시다:

@Configuration(proxyBeanMethods = false)
public class MyHealthMetricsExportConfiguration {

    public MyHealthMetricsExportConfiguration(MeterRegistry registry, HealthEndpoint healthEndpoint) {
        // This example presumes common tags (such as the app) are applied elsewhere
        Gauge.builder("health", healthEndpoint, this::getStatusCode).strongReference(true).register(registry);
    }

    private int getStatusCode(HealthEndpoint health) {
        Status status = health.health().getStatus();
        if (Status.UP.equals(status)) {
            return 3;
        }
        if (Status.OUT_OF_SERVICE.equals(status)) {
            return 2;
        }
        if (Status.DOWN.equals(status)) {
            return 1;
        }
        return 0;
    }

}

---

Next :

Security
스프링 시큐리티와 관련된 how to 가이드

전체 목차는 여기에 있습니다.