[Spring Boot 번역] Logging

출처: https://docs.spring.io/spring-boot/4.0-SNAPSHOT/how-to/logging.html

주의: 이 버전은 아직 개발 중이며 안정적이지 않습니다. 최신 안정 버전은 Spring Boot 3.5.6을 사용하세요!

Logging

Spring Boot는 Commons Logging API를 제외하고는 필수 로깅 의존성이 없습니다. Commons Logging API는 일반적으로 Spring Framework의 spring-jcl 모듈에서 제공됩니다. Logback을 사용하려면 classpath에 Logback과 spring-jcl을 포함해야 합니다. 권장하는 방법은 스타터를 통하는 것입니다. 모든 스타터는 spring-boot-starter-logging에 의존합니다. 웹 애플리케이션의 경우 spring-boot-starter-web만 필요합니다. 이것은 로깅 스타터에 전이적으로 의존하기 때문입니다. Maven을 사용하는 경우 다음 의존성이 로깅을 추가합니다:

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

Spring Boot에는 classpath의 내용을 기반으로 로깅을 구성하려고 시도하는 LoggingSystem 추상화가 있습니다. Logback을 사용할 수 있는 경우 이것이 첫 번째 선택입니다.

로깅에 필요한 유일한 변경 사항이 다양한 로거의 레벨을 설정하는 것이라면 다음 예제와 같이 application.properties에서 "logging.level" 접두사를 사용하여 설정할 수 있습니다:

Properties

logging.level.org.springframework.web=debug
logging.level.org.hibernate=error

YAML

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

logging.file.name을 사용하여 로그가 기록될 파일의 위치를 (콘솔 외에) 설정할 수도 있습니다.

로깅 시스템의 더 세밀한 설정을 구성하려면 해당 LoggingSystem에서 지원하는 네이티브 구성 형식을 사용해야 합니다. 기본적으로 Spring Boot는 시스템의 기본 위치(Logback의 경우 classpath:logback.xml)에서 네이티브 구성을 가져오지만 logging.config 속성을 사용하여 구성 파일의 위치를 설정할 수 있습니다.

Configure Logback for Logging

application.properties로 달성할 수 있는 것 이상으로 logback에 사용자 정의를 적용해야 하는 경우 표준 logback 구성 파일을 추가해야 합니다. classpath의 루트에 logback.xml 파일을 추가하여 logback이 찾을 수 있습니다. Spring Boot Logback Extensions를 사용하려면 logback-spring.xml을 사용할 수도 있습니다.

Logback 문서에는 구성을 어느 정도 자세히 다루는 전용 섹션이 있습니다.

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

다음 파일은 org/springframework/boot/logging/logback/ 아래에 제공됩니다:

defaults.xml - 변환 규칙, 패턴 속성 및 공통 로거 구성을 제공합니다.
console-appender.xml - CONSOLE_LOG_PATTERN을 사용하여 ConsoleAppender를 추가합니다.
structured-console-appender.xml - CONSOLE_LOG_STRUCTURED_FORMAT에서 구조화된 로깅을 사용하여 ConsoleAppender를 추가합니다.
file-appender.xml - FILE_LOG_PATTERN 및 ROLLING_FILE_NAME_PATTERN을 적절한 설정과 함께 사용하여 RollingFileAppender를 추가합니다.
structured-file-appender.xml - FILE_LOG_STRUCTURED_FORMAT에서 구조화된 로깅과 함께 ROLLING_FILE_NAME_PATTERN을 사용하여 RollingFileAppender를 추가합니다.

또한 이전 버전의 Spring Boot와의 호환성을 위해 레거시 base.xml 파일이 제공됩니다.

일반적인 사용자 정의 logback.xml 파일은 다음과 같습니다:

<?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>

logback 구성 파일은 LoggingSystem이 생성하는 시스템 속성을 사용할 수도 있습니다:

${PID}: 현재 프로세스 ID.
${LOG_FILE}: Boot의 외부 구성에서 logging.file.name이 설정되었는지 여부.
${LOG_PATH}: Boot의 외부 구성에서 logging.file.path(로그 파일이 위치할 디렉토리를 나타냄)가 설정되었는지 여부.
${LOG_EXCEPTION_CONVERSION_WORD}: Boot의 외부 구성에서 logging.exception-conversion-word가 설정되었는지 여부.
${ROLLING_FILE_NAME_PATTERN}: Boot의 외부 구성에서 logging.pattern.rolling-file-name이 설정되었는지 여부.

Spring Boot는 사용자 정의 Logback 컨버터를 사용하여 콘솔에서 멋진 ANSI 컬러 터미널 출력을 제공합니다(로그 파일에서는 제공하지 않음). 예제는 defaults.xml 구성에서 CONSOLE_LOG_PATTERN을 참조하세요.

Groovy가 classpath에 있는 경우 logback.groovy로 Logback을 구성할 수 있어야 합니다. 있는 경우 이 설정이 우선합니다.

주의: Spring 확장은 Groovy 구성에서 지원되지 않습니다. 모든 logback-spring.groovy 파일은 감지되지 않습니다.

Configure Logback for File-only Output

콘솔 로깅을 비활성화하고 파일에만 출력을 작성하려면 file-appender.xml을 가져오지만 console-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>

다음 예제와 같이 application.properties 또는 application.yaml에 logging.file.name을 추가해야 합니다:

Properties

logging.file.name=myapplication.log

YAML

logging:
  file:
    name: "myapplication.log"

Configure Log4j for Logging

Spring Boot는 classpath에 있는 경우 로깅 구성을 위해 Log4j 2를 지원합니다. 스타터를 사용하여 의존성을 조합하는 경우 Logback을 제외하고 대신 Log4j 2를 포함해야 합니다. 스타터를 사용하지 않는 경우 Log4j 2 외에 (최소한) spring-jcl을 제공해야 합니다.

권장하는 경로는 스타터를 통하는 것입니다. 약간의 조정이 필요하더라도 말입니다. 다음 예제는 Maven에서 스타터를 설정하는 방법을 보여줍니다:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<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>

Gradle은 스타터를 설정하는 몇 가지 다른 방법을 제공합니다. 한 가지 방법은 모듈 교체를 사용하는 것입니다. 이렇게 하려면 Log4j 2 스타터에 대한 의존성을 선언하고 기본 로깅 스타터의 모든 발생을 Log4j 2 스타터로 교체하도록 Gradle에 지시합니다. 다음 예제를 참조하세요:

dependencies {
    implementation "org.springframework.boot:spring-boot-starter-log4j2"
    modules {
        module("org.springframework.boot:spring-boot-starter-logging") {
            replacedBy("org.springframework.boot:spring-boot-starter-log4j2", "Use Log4j2 instead of Logback")
        }
    }
}

참고: Log4j 스타터는 일반적인 로깅 요구 사항에 대한 의존성을 수집합니다(예: Tomcat이 java.util.logging을 사용하지만 Log4j 2를 사용하여 출력을 구성함).

참고: java.util.logging을 사용하여 수행된 디버그 로깅이 Log4j 2로 라우팅되도록 하려면 java.util.logging.manager 시스템 속성을 org.apache.logging.log4j.jul.LogManager로 설정하여 JDK 로깅 어댑터를 구성하세요.

Use YAML or JSON to Configure Log4j 2

기본 XML 구성 형식 외에도 Log4j 2는 YAML 및 JSON 구성 파일도 지원합니다. 대체 구성 파일 형식을 사용하도록 Log4j 2를 구성하려면 classpath에 적절한 의존성을 추가하고 선택한 파일 형식과 일치하도록 구성 파일의 이름을 지정합니다. 다음 예제를 참조하세요:

Format	Dependencies	File names
YAML	`com.fasterxml.jackson.core:jackson-databind` + `com.fasterxml.jackson.dataformat:jackson-dataformat-yaml`	`log4j2.yaml` + `log4j2.yml`
JSON	`com.fasterxml.jackson.core:jackson-databind`	`log4j2.json` + `log4j2.jsn`

Use Composite Configuration to Configure Log4j 2

Log4j 2는 여러 구성 파일을 단일 복합 구성으로 결합하는 것을 지원합니다. Spring Boot에서 이 지원을 사용하려면 하나 이상의 보조 구성 파일의 위치로 logging.log4j2.config.override를 구성합니다. 보조 구성 파일은 기본 구성의 소스가 Spring Boot의 기본값이든, log4j.xml과 같은 표준 위치이든, logging.config 속성으로 구성된 위치이든 관계없이 기본 구성과 병합됩니다.

Log4j2 재정의 구성 파일 위치 앞에 optional:을 붙일 수 있습니다. 예를 들어 optional:classpath:log4j2-override.xml은 리소스가 존재하는 경우에만 log4j2-override.xml을 로드해야 함을 나타냅니다.