Spring Boot 로그 레벨 동적 변경과 프로파일별 로깅 설정

개요

애플리케이션을 운영하다 보면 개발·테스트·운영 환경별로 다른 로그 설정이 필요하다. 또한 장애나 성능 문제 발생 시 재배포 없이 로그 레벨을 올려 자세한 로그를 수집해야 한다. 이 글은 Spring Boot에서 프로파일별 Logback 설정과 런타임에 로그 레벨을 동적으로 변경하는 실무적 접근을 정리한다.

왜 프로파일별 로깅과 동적 변경이 필요한가

프로파일별로 로그 포맷, 출력 대상, 레벨을 분리하면 개발 중 디버그용 로그를 활성화하고 운영에서는 정보 또는 경고 수준으로 로그를 줄여 성능과 저장 비용을 관리할 수 있다. 한편 장애 대응 시에는 애플리케이션을 중단하지 않고 특정 패키지의 로그 레벨을 높여 원인 분석에 필요한 상세 정보를 확보할 수 있다.

기본 구성 요소

Logback

Spring Boot 기본 로깅 구현체로 Logback을 사용하면 logback-spring.xml을 통해 프로파일 기반 설정이 가능하다.

Actuator

Spring Boot Actuator의 /actuator/loggers 엔드포인트는 런타임에 로그 레벨을 조회·변경할 수 있는 표준 방법을 제공한다. 보안에 주의해 관리해야 한다.

프로파일별 Logback 설정 예시

다음 예시는 개발(dev)과 운영(prod)에서 서로 다른 콘솔과 파일 패턴을 적용하는 방법이다.

<configuration>

  <springProfile name="dev">
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
      <encoder>
        <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
      </encoder>
    </appender>

    <root level="DEBUG">
      <appender-ref ref="CONSOLE" />
    </root>
  </springProfile>

  <springProfile name="prod">
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
      <file>logs/app.log</file>
      <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
        <fileNamePattern>logs/app.%d{yyyy-MM-dd}.log.gz</fileNamePattern>
        <maxHistory>30</maxHistory>
      </rollingPolicy>
      <encoder>
        <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level %logger{36} - %msg%n</pattern>
      </encoder>
    </appender>

    <root level="INFO">
      <appender-ref ref="FILE" />
    </root>
  </springProfile>

</configuration>

application.yml로 프로파일 관리

application.yml에서 프로파일별로 로깅 레벨을 기본값처럼 정의할 수 있다. 하지만 복잡한 포맷이나 appender는 logback-spring.xml에서 제어하는 것이 더 유연하다.

spring:
  profiles: dev

logging:
  level:
    root: INFO
    com.example: DEBUG

위 설정은 프로파일 별로 기본 레벨을 지정하는 간단한 방법이다. 더 정교한 제어가 필요하면 logback-spring.xml을 사용한다.

런타임 로그 레벨 변경 방법

1) Actuator 사용

Actuator를 의존성에 추가하고 엔드포인트를 활성화하면 /actuator/loggers에서 레벨 변경이 가능하다. 보안이 중요한 환경에서는 인증·인가 설정을 반드시 적용한다.

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

엔드포인트 활성화 예시 (application.yml):

management:
  endpoints:
    web:
      exposure:
        include: "health,info,loggers"
  endpoint:
    loggers:
      enabled: true

로그 레벨 변경 예시 (curl):

curl -X POST -u user:pass -H "Content-Type: application/json" \
  -d '{"configuredLevel":"DEBUG"}' \
  http://localhost:8080/actuator/loggers/com.example.package

2) 코드로 변경

프로그램에서 직접 변경할 때는 Spring Boot의 LoggingSystem을 사용한다. 이 방법은 애플리케이션 내부에서 조건부로 로그 레벨을 바꿀 때 유용하다.

import org.springframework.boot.logging.LoggingSystem;
import org.springframework.stereotype.Service;

@Service
public class LogLevelService {

  private final LoggingSystem loggingSystem;

  public LogLevelService(LoggingSystem loggingSystem) {
    this.loggingSystem = loggingSystem;
  }

  public void setLevel(String loggerName, String level) {
    loggingSystem.setLogLevel(loggerName, org.springframework.boot.logging.LogLevel.valueOf(level));
  }
}

운영 시 고려사항

• Actuator 엔드포인트는 인증·인가 후 노출한다.
• 로그 레벨을 과도하게 DEBUG로 올리면 디스크·CPU에 영향을 줄 수 있다.
• 프로파일별 설정은 일관된 로그 포맷을 유지해 로그 분석과 연동이 쉬운 형태로 설계한다.
• 분산 환경에서는 중앙 로깅(ELK, Grafana Loki 등)과 연계해 로그 레벨 변경 시 수집 정책도 함께 고려한다.

체크리스트

• logback-spring.xml을 프로파일별로 구성했는가
• Actuator의 loggers 엔드포인트가 안전하게 노출되는가
• 운영 환경에서의 로그 보존 정책과 디스크 사용량을 검토했는가
• 동적 변경 후에도 필요한 로그가 정상적으로 수집되는가

마무리

프로파일별 로깅 설정과 런타임 로그 레벨 변경은 안정적인 운영과 빠른 문제 해결에 큰 도움이 된다. 단순한 application.yml 설정으로 충분한 경우도 있지만, 서비스 규모가 커질수록 logback-spring.xml과 Actuator, 중앙 로깅 시스템을 함께 설계하는 것이 바람직하다. 각 환경의 요구에 맞춰 적절히 조합해 사용하면 로그 관리의 효율성을 높일 수 있다.