spring boot logging

Spring Boot에는 일반적으로 Spring 프레임워크의 spring-jcl 모듈에서 제공하는 Commons Logging API를 제외하고는 필수 로깅 종속성이 없다. Logback을 사용하려면 클래스 경로에 Logback과 spring-jcl을 포함시켜야 한다.

이를 위해서 spring-boot-sterter-logging 종속성을 추가하면 된다. 웹 애플리케이션의 경우 spring-boot-starter-web이 spring-boot-starter-logging 종속성을 포함하고 있기 때문에 spring-boot-starter-web 종속성만 추가하면 Logback을 사용할 수 있다.

정확하게 말하자면 spring-boot-starter-logging 의존성은 spring-boot-starter 의존성에 포함되어 있고

spring-boot-starter-web 의존성이 spring-boot-starter 의존성을 포함하고 있다.

 

Spring Boot에는 클래스 경로의 내용을 기반으로 로깅을 구성하려고 시도하는 LoggingSystem 추상화가 있다. Logback을 사용할 수 있는 경우 Logback이 첫 번째로 선택되어 사용된다.

 

기본적으로 Spring Boot는 시스템의 기본 위치에서 네이티브 구성을 선택하지만(Logback의 경우 classpath:logback.xml), logging.config 속성을 사용하여 구성 파일의 위치를 설정할 수 있다.

 

 

파일 출력

기본적으로 Spring Boot는 콘솔에만 로깅하고 로그 파일을 작성하지 않는다. 콘솔 출력 이외에 로그 파일을 기록하려면 logging.file.name 또는 logging.file.path 속성을 설정해야 한다.

디폴트로 로그 파일의 rotate 사이즈는 10MB이며 로그 레벨은 ERROR, WARN, INFO 레벨 로그가 기록된다.

 

logging.file.name

지정된 로그 파일에 로그를 기록한다. 설정은 절대 경로 혹은 상대 경로가 될 수 있다.

logging:
  file:
    name: log/application.log

현재 디렉터리를 기준으로 log/application.log 파일에 로그를 기록한다.

 

logging.file.path

지정된 디렉터리에 spring.log 파일을 기록한다. 설정은 절대 경로 혹은 상대 경로가 될 수 있다.

logging:
  file:
    path: log

현재 디렉터리를 기준으로 log/spring.log 파일에 로그를 기록한다.

logging.* 속성은 실제로 사용되는 로깅 인프라와는 독립적이다. 따라서 특정 구성 키
(예: 로그백을 위한 logback.configurationFile)는 Spring Boot에서 관리되지 않는다.

 

파일 Rotation

Logback을 사용하는 경우 application.properties 혹은 application.yml 파일을 사용하여 로그 lotation 설정을 상세하게 할 수 있다. 그 외 다른 모든 로깅 시스템의 경우 직접 rotation 설정을 구성해야 한다.

(ex. Log4j2를 사용하는 경우 log4j2.xml 또는 log4j2-spring.xml 파일에 설정을 추가할 수 있다.)

지원되는 rotation 정책 설정은 아래와 같다.

logging.logback.rollingpolicy.file-name-pattern	The filename pattern used to create log archives.
logging.logback.rollingpolicy.clean-history-on-start	If log archive cleanup should occur when the application starts.
logging.logback.rollingpolicy.max-file-size	The maximum size of log file before it is archived.
logging.logback.rollingpolicy.total-size-cap	The maximum amount of size log archives can take before being deleted.
logging.logback.rollingpolicy.max-history	The maximum number of archive log files to keep (defaults to 7).

출처: https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.logging.file-rotation

 

로그 레벨

지원되는 모든 로깅 시스템은 logging.level.<logger>=<로그레벨>을 사용하여 application.yml 혹은 application.properties 에서 로그 레벨을 설정할 수 있다.

로그 레벨은 TRACE, DEBUG, INFO, WARN, ERROR, FATAL, OFF 가 지원되며 root 로거는 logging.level.root로 설정한다.

 

logging:
  level:
    root: "warn"
    org.springframework.web: "debug"
    org.hibernate: "error"

로그 레벨은 환경 변수로도 설정이 가능하다.

환경 변수 LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_WEB=DEBUG는 logging.level.org.springframework.web=DEBUG와 동일하게 동작한다.

하지만 환경 변수의 접근 방식은 패키지 수준 로깅 설정에서만 동작한다. 릴랙스 바인딩은 항상 환경 변수를 소문자로 변환하기 때문에 이러한 방식으로 개별 클래스에 대한 로깅을 구성할 수 없다. 

 

로그 그룹

여러 로깅 대상 패키지를 하나의 로그 그룹으로 정의할 수 있다.

logging:
  group:
    tomcat: "org.apache.catalina,org.apache.coyote,org.apache.tomcat"
  level:
    tomcat: "trace"

Spring Boot에서는 사전에 정의된 로깅 그룹이 포함되어 있다.

web	org.springframework.core.codec org.springframework.http org.springframework.web org.springframework.boot.actuate.endpoint.web org.springframework.boot.web.servlet.ServletContextInitializerBeans
sql	org.springframework.jdbc.core org.hibernate.SQL org.jooq.tools.LoggerListener

출처 https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.logging.log-groups

 

Custom Log Configuration

application.yml 에서 지원하는 로깅 관련 설정 외에 Logback에 사용자 지정 설정을 적용해야 하는 경우 표준 Logback 구성 파일을 추가해야 한다. Logback이 찾을 수 있도록 classpath root에 logback.xml 파일을 추가할 수 있다. Spring Boot Logback 확장을 사용하려는 경우 logback-spring.xml을 사용할 수도 있다.

org.springframework.boot.logging.LoggingSystem 시스템 속성을 사용하여 Spring Boot에서 특정 로깅 시스템을 사용하도록 강제할 수 있다. 값은 LoggingSystem 구현의 정규화된 클래스 이름이어야 한다. 값을 none으로 사용하여 Spring Boot의 로깅 구성을 비활성화할 수도 있다.

Log4J2LoggingSystem을 사용하려는 경우에는 아래 종속성이 필요하다.

<!-- 
log4j2 로깅 시스템을 사용하려는 경우 
spring-boot-starter-logging 종속성을 제거하지 않으면 
class org.apache.logging.slf4j.SLF4JLoggerContext cannot be cast 오류가 발생한다.
그냥 Spring Boot에서 기본으로 적용되는 Logback 로깅 시스템을 사용하는 것에 제일 
좋을 것 같다.
-->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-logging</artifactId>
        </exclusion>
    </exclusions>
</dependency>

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

Log4J2LoggingSystem을 사용하도록 설정
-Dorg.springframework.boot.logging.LoggingSystem=org.springframework.boot.logging.log4j2.Log4J2LoggingSystem

LogbackLoggingSystem을 사용하도록 설정 (default)
-Dorg.springframework.boot.logging.LoggingSystem=org.springframework.boot.logging.logback.LogbackLoggingSystem

JavaLoggingSystem을 사용하도록 설정
-Dorg.springframework.boot.logging.LoggingSystem=org.springframework.boot.logging.java.JavaLoggingSystem

시스템 속성에 대한 처리는 org.springframework.boot.context.logging.LoggingApplicationListener 클래스에서 처리한다.

각 로깅 시스템은 아래 표와 같이 파일을 로딩한다.

Logging System	Customization
Logback (LogbackLoggingSystem)	logback-spring.xml, logback-spring.groovy, logback.xml 혹은 logback.groovy
Log4j2 (Log4J2LoggingSystem)	log4j2-spring.xml 혹은 log4j2.xml
Java (JavaLoggingSystem)	logging.properties

표준 구성 위치를 사용하는 경우 Spring이 로그 초기화를 완전히 제어할 수 없기 때문에 가능하면 로깅 구성에 -spring suffix가 붙은 파일을 사용하는 것이 좋다.

실행 가능한 jar에서 실행할 때 Java Util Logging 클래스 로딩에 문제가 있다. 가급적 실행 가능한 jar에서 실행할 때는 이를 피하는 것이 좋다.

사용자 정의 설정을 위해서 일부 설정항목은 Spring 환경에서 system property로 전송된다. system property로 전송되는 property는 사용자 정의 로깅 설정에서 사용할 수 있다.

예를 들어 application.yml 에서 logging.file.path 설정은 LOG_PATH system property로 전송되고 사용자 정의 설정에서는 ${LOG_PATH} (=logging.file.path)와 같은 형태로 사용할 수 있다.

또한 logging.file.path는 환경 변수 LOGGING_FILE_PATH와 맵핑되므로 LOGGING_FILE_PATH 환경 변수 역시 LOG_PATH system property로 전송되어 사용자 정의 로깅 설정에서 사용할 수 있다.

system property로 전송되는 속성은 아래와 같다.

Spring Environment	System Property	Comments
logging.exception-conversion-word	LOG_EXCEPTION_CONVERSION_WORD	The conversion word used when logging exceptions.
logging.file.name	LOG_FILE	If defined, it is used in the default log configuration.
logging.file.path	LOG_PATH	If defined, it is used in the default log configuration.
logging.pattern.console	CONSOLE_LOG_PATTERN	The log pattern to use on the console (stdout).
logging.pattern.dateformat	LOG_DATEFORMAT_PATTERN	Appender pattern for log date format.
logging.charset.console	CONSOLE_LOG_CHARSET	The charset to use for console logging.
logging.threshold.console	CONSOLE_LOG_THRESHOLD	The log level threshold to use for console logging.
logging.pattern.file	FILE_LOG_PATTERN	The log pattern to use in a file (if LOG_FILE is enabled).
logging.charset.file	FILE_LOG_CHARSET	The charset to use for file logging (if LOG_FILE is enabled).
logging.threshold.file	FILE_LOG_THRESHOLD	The log level threshold to use for file logging.
logging.pattern.level	LOG_LEVEL_PATTERN	The format to use when rendering the log level (default %5p).
PID	PID	The current process ID (discovered if possible and when not already defined as an OS environment variable).

Logback을 사용한다면 아래 속성들도 system property로 전송된다.

Spring Environment	System Property	Comments
logging.logback.rollingpolicy.file-name-pattern	LOGBACK_ROLLINGPOLICY_FILE_NAME_PATTERN	Pattern for rolled-over log file names (default ${LOG_FILE}.%d{yyyy-MM-dd}.%i.gz).
logging.logback.rollingpolicy.clean-history-on-start	LOGBACK_ROLLINGPOLICY_CLEAN_HISTORY_ON_START	Whether to clean the archive log files on startup.
logging.logback.rollingpolicy.max-file-size	LOGBACK_ROLLINGPOLICY_MAX_FILE_SIZE	Maximum log file size.
logging.logback.rollingpolicy.total-size-cap	LOGBACK_ROLLINGPOLICY_TOTAL_SIZE_CAP	Total size of log backups to be kept.
logging.logback.rollingpolicy.max-history	LOGBACK_ROLLINGPOLICY_MAX_HISTORY	Maximum number of archive log files to keep.

출처 https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.logging.custom-log-configuration

 

Logback을 위한 Logging 설정

Spring Boot에는 고급 구성에 도움이 될 수 있는 Logback에 대한 여러 가지 확장이 포함되어 있다. logback-spring.xml 구성 파일에서 이러한 확장을 사용할 수 있다.

표준 logback.xml 구성 파일은 너무 일찍 로드되므로 이 파일에서 확장을 사용할 수 없다. logback-spring.xml 파일에 구성하거나 logging.config 속성에 확장 설정 파일을 정의해야 한다.

Profile 지정 설정

<springProfile> 태그를 사용하면 활성 Spring 프로파일을 기반으로 구성 섹션을 선택적으로 포함하거나 제외할 수 있다. 프로파일 섹션은 <configuration> 요소 내 어디에서나 지원된다. name 속성을 사용하여 구성을 수락하는 프로파일을 지정한다.

<springProfile> 태그에는 프로파일 이름 또는 프로파일 표현식이 포함될 수 있다. 프로파일 표현식을 사용하면 보다 복잡한 프로파일 로직을 표현할 수 있다. 

<springProfile name="staging">
    <!-- configuration to be enabled when the "staging" profile is active -->
</springProfile>

<springProfile name="dev | staging">
    <!-- configuration to be enabled when the "dev" or "staging" profiles are active -->
</springProfile>

<springProfile name="!production">
    <!-- configuration to be enabled when the "production" profile is not active -->
</springProfile>

 

Environment 속성

<springProperty> 태그를 사용하면 Spring 환경의 속성을 logback 내에서 사용할 수 있다.

이 태그는 logback 구성에서 application.properties 혹은 application.yml의 값을 사용하려는 경우에 유용하다.

이 태그는 logback 표준 <property> 태그와 비슷한 방식으로 동작한다. 하지만 직접 값을 지정하는 대신에 Spring property의 source 환경을 지정한다.

Spring property가 설정되지 않은 경우 defaultValue 속성을 사용하여 default 값을 지정할 수 있다.

<springProperty scope="context" name="fluentHost" source="myapp.fluentd.host"
        defaultValue="localhost"/>
<appender name="FLUENT" class="ch.qos.logback.more.appenders.DataFluentAppender">
    <remoteHost>${fluentHost}</remoteHost>
    ...
</appender>

source 속성은 kebab case(ex. property-name)로 지정해야 한다.

 

Configure Logback for Logging

Spring Boot는 자체 구성에 포함할 수 있는 다양한 logback 구성을 제공한다. 이러한 구성은 특정 일반적인 Spring Boot 규칙을 다시 적용할 수 있도록 설계되었다.

 

org.springframework.boot:spring-boot 종속성에 포함된 org/springframework/boot/logging/logback/ 경로에 제공되는 파일은 아래와 같다.

• defaults.xml - 변환 규칙, 패턴 속성 및 일반적인 로거 구성을 제공한다.
• console-appender.xml - 콘솔 로그 패턴을 사용하여 ConsoleAppender를 추가한다.
• file-appender.xml - FILE_LOG_PATTERN 및 ROLLING_FILE_NAME_PATTERN system 속성과 함께 RollingFileAppender를 추가한다.
• base.xml - 이전 버전의 Spring Boot와의 호환성을 위해 제공된다.

logback-spring.xml 파일에는 다음과 같이 Spring Boot에서 기본적으로 제공되는 파일을 include 하여 사용할 수 있다.

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <include resource="org/springframework/boot/logging/logback/defaults.xml"/>
    <include resource="org/springframework/boot/logging/logback/console-appender.xml" />
    <root level="INFO">
        <appender-ref ref="CONSOLE" />
    </root>
    <logger name="org.springframework.web" level="DEBUG"/>
</configuration>

 

Configure Logback for File-only Output

console 로깅을 비활성화하고 출력을 파일에만 쓰려면 아래 예시와 같이 console-appender.xml이 아닌 file-appender.xml을 가져오는 사용자 정의 logback-spring.xml 이 필요하다.

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <include resource="org/springframework/boot/logging/logback/defaults.xml" />
    <property name="LOG_FILE" value="${LOG_FILE:-${LOG_PATH:-${LOG_TEMP:-${java.io.tmpdir:-/tmp}}/}spring.log}"/>
    <include resource="org/springframework/boot/logging/logback/file-appender.xml" />
    <root level="INFO">
        <appender-ref ref="FILE" />
    </root>
</configuration>

위 예시에서는 ${LOG_FILE} system property를 사용하기 때문에 logging.file.name 설정이 필요하다.

${LOG_FILE}이 없는 경우 ${LOG_PATH}를 사용하고 없으면 ${LOG_TEMP}를 사용하는 식이다.

logging:
  file:
    name: "myapplication.log"

 

지금까지 Spring Boot의 기본 로깅에 대한 정리와 Logback 확장 설정에 대해서 간단히 알아보았다.

이후에는 logback에 대해서 상세한 SPEC을 정리할 것이다.

 

---

참고링크

https://docs.spring.io/spring-boot/docs/current/reference/html/howto.html#howto.logging

“How-to” Guides

https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.logging

Core Features