이 문서를 통해 아래 질문들에 답할 수 있게 됩니다.
- 자동 설정이 적용되었는지 확인하는 conditions report는 어떻게 읽는가?
- Bean이 생기지 않는 문제를 classpath, property, back-off 순서로 좁히는 방법은 무엇인가?
- Actuator와 debug 로그를 운영 문제 해결에 어떻게 활용해야 하는가?
개요
Boot 자동 설정을 이해했다는 것은 conditions report를 읽을 수 있다는 뜻에 가깝다. 자동 설정 문제는 대부분 “왜 이 Bean이 생겼는가” 또는 “왜 생기지 않았는가”의 문제다. 그 답은 조건 평가 결과에 있다.
Boot는 debug 모드와 Actuator conditions endpoint를 통해 자동 설정 매칭 결과를 보여 준다. 출력은 길지만, 관련 자동 설정 이름을 찾고 positive match와 negative match 이유를 읽으면 문제 범위를 빠르게 줄일 수 있다. 조건 리포트는 “Bean 목록”이 아니라 “자동 설정 후보가 왜 조건을 통과하거나 탈락했는지”를 보여 주는 자료다.
debug conditions report
애플리케이션을 --debug로 실행하면 조건 평가 리포트가 로그에 출력된다. 여기에는 어떤 자동 설정이 조건을 만족했는지, 어떤 조건 때문에 제외되었는지가 나온다.
예를 들어 DataSource가 생기지 않는다면 DataSourceAutoConfiguration을 찾는다. JDBC 드라이버 classpath가 없는지, url property가 없는지, 사용자가 다른 DataSource Bean을 등록했는지 같은 이유를 확인한다.
Actuator conditions endpoint
Actuator를 사용하면 런타임에 conditions endpoint로 자동 설정 매칭 결과를 확인할 수 있다. 운영 환경에서는 endpoint 노출과 보안 정책을 신중히 설정해야 하지만, 개발과 내부 진단에서는 매우 유용하다. 이 endpoint는 classpath, property, Bean 조건 등 내부 구조를 드러낼 수 있으므로 외부 공개 endpoint로 두면 안 된다.
conditions endpoint는 전체 자동 설정을 다 보여주므로 검색이 중요하다. 기능명이나 자동 설정 클래스명을 기준으로 좁힌다. WebMvc, Jackson, DataSource, Jpa, Security, Cache처럼 문제 영역을 나타내는 키워드를 먼저 찾는다.
디버깅 순서
첫째, classpath를 확인한다. Starter나 직접 의존성이 빠져 있으면 조건이 맞지 않는다.
둘째, property를 확인한다. 기능이 꺼져 있거나 다른 구현체로 지정되어 있을 수 있다.
셋째, 사용자 Bean을 확인한다. 직접 만든 Bean이 자동 설정을 back-off시켰을 수 있다.
넷째, 애플리케이션 종류를 확인한다. Servlet과 reactive 의존성이 섞이면 예상과 다른 웹 애플리케이션 타입이 선택될 수 있다.
다섯째, 자동 설정 exclude 여부를 확인한다. 과거 디버깅 중 추가한 exclude가 남아 있을 수 있다.
실전 팁
- conditions report는 전체를 읽지 말고 문제 기능의 자동 설정 이름을 검색한다.
- Bean이 없을 때 component scan만 의심하지 말고 자동 설정 조건을 먼저 확인한다.
- conditions report는 Bean 생성 순서 로그가 아니라 조건 평가 결과라는 점을 기억한다.
- 사용자 Bean을 추가한 PR에서는 어떤 자동 설정이 back-off되는지 함께 리뷰한다.
- Actuator endpoint는 보안 설정 없이 외부에 노출하지 않는다.
- 테스트에서 자동 설정 조건을 고정하고 싶다면
ApplicationContextRunner같은 도구를 사용한다.
위험 신호!
--debug로그를 한 번도 보지 않고 자동 설정 문제를 해결하려 한다.- Actuator endpoint를 운영 외부망에 무방비로 노출한다.
- conditions endpoint를 보고도 positive match와 실제 Bean 생성/사용 여부를 구분하지 않는다.
- 자동 설정 exclude가 왜 있는지 아무도 모른다.
- 사용자 Bean 하나를 추가한 뒤 관련 기본 커스터마이저가 모두 사라진다.
- classpath 충돌로 Servlet과 reactive 설정이 섞였는데 conditions report를 확인하지 않는다.
확인 질문
확인 질문
- conditions report가 알려 주는 핵심 정보는 무엇인가?
- 자동 설정 후보가 어떤 조건 때문에 적용되었거나 제외되었는지 알려 준다.
- 자동 설정 Bean이 없을 때 확인할 순서는 무엇인가?
- classpath, property, 사용자 Bean back-off, 애플리케이션 타입, exclude 여부를 확인한다.
- Actuator conditions endpoint를 사용할 때 주의할 점은 무엇인가?
- 내부 설정 정보가 노출될 수 있으므로 접근 제어와 노출 범위를 엄격히 관리해야 한다.