✍️➡️📡 “어떻게 찍을까”에서 “어디로 보낼까”로 logback-spring.xml 설계기

지난 글에서 Logback이 뭔지 감 잡았다면, 이번에는 드디어 logback-spring.xml을 직접 설계하고 구조화하는 과정을 정리해본다.

무턱대고 xml을 쓰기보다 누가 볼 로그인지, 어디서 소비할지, 어떤 포맷이 맞는지, 공통 키(MDC)를 무엇으로 고정할지부터 정리했다.

🚦 로그 설계 전에 던진 질문들

누가 로그를 볼까? → 개발자, 운영자, ELK 시스템
어디에 남길까? → 콘솔, 텍스트, JSON, Kafka
어떤 포맷으로? → 콘솔은 가독성, 텍스트는 Key=Value, JSON은 구조화
MDC 표준은? → traceId, spanId, userId, uri, method, clientIp

이 네 가지가 정리되지 않으면 xml 설정은 결국 “찍히는 대로 찍는 로그”로 끝나버린다.
나는 그래서 먼저 “로그의 목적”을 정하고, 거기에 맞춰 Appender를 나누는 걸 출발점으로 삼았다.

이 질문을 풀고 나니, 자연스럽게 네 갈래 출구가 자리를 잡았다.
👉 CONSOLE · TEXT_FILE · JSON_FILE · KAFKA_JSON

결국 핵심은 두 가지였다.
MDC 키를 표준화하는 것, 그리고 Appender를 용도별로 분리하는 것 !!!

---

🤔 먼저, 왜 굳이 logback-spring.xml인가 ?

logback.xml도 동작은 하지만, Spring Boot는 logback-spring.xml을 권장한다.
써보니 그 이유가 명확했다.

• Spring 프로퍼티 사용이 가능하다. ${LOG_PATH}, ${KAFKA_BOOTSTRAP_SERVERS} 같은 값을 application.yml에서 가져와 설정과 환경을 한몸처럼 관리할 수 있다.
• 프로필 분기를 xml 안에서 직접 걸 수 있다. <springProfile name="dev|prod">를 활용하면 환경별 Appender·레벨 구성을 쉽게 분리할 수 있다.
• 부트 초기화 타이밍과 맞아떨어진다. 애플리케이션 시작 시점에 안정적으로 로깅이 초기화된다.

요약하면, logback.xml은 순수 Logback 설정이고, logback-spring.xml은 Spring과 함께 움직이며 환경 분기를 품은 설정이다.
나는 이걸 알았을 때, “아, 로그 설정도 코드처럼 환경 분기를 가져가야 하는구나”라는 걸 제대로 체감했다.

logback.xml: Spring 프로퍼티/프로필 불가, 순수 Logback 구문
logback-spring.xml: ${} 지원, <springProfile> 지원, 부트와 자연스러운 연동

---

📡 MDC 키 표준화 : 로그의 공용어 만들기

Appender를 여러 개 두더라도, 공용 키가 없다면 로그는 제각각의 언어로 말하게 된다.
그래서 서비스 곳곳에서 남기는 맥락을 MDC(Mapped Diagnostic Context)로 통일했다.

• 이름은 짧고 일관되게 가져갔다.
• 값이 없어도 키는 항상 유지한다.
  (비어 있다고 키 자체가 빠지면 분석 단계에서 곤란해진다.)

최종적으로 표준화한 키는 다음과 같다.

• traceId, spanId — 분산 추적의 실마리로 삼았다.
• timestamp — 애플리케이션 기준 시각으로 통일했다.
• userId — 인증 전 구간은 anon으로 고정했다.
• uri, method, clientIp, userAgent — 요청 메타를 공통 키로 잡았다.

이 값들은 필터/인터셉터에서 주입했고, 비동기 흐름에도 전파되도록 별도 유틸을 뒀다.
덕분에 컨트롤러든 배치든, 같은 사건은 언제나 같은 이름표를 달고 흘러갔다.
그리고 Kibana에서는 userId=anon 조건으로도 검색할 수 있고, Excel에서도 컬럼이 깨지지 않는다.

👉 자세한 내용은 다음 글(Trace 관련)에서 다룰 예정이다.

---

🗂️ logback-spring.xml, 이렇게 구조화했다

한 가지 포맷으로 전부를 해결하려다 보면 어디선가는 타협이 생겼다. 그래서 아예 출구를 네 갈래로 뽑았다.

콘솔은 개발용 가독성, 텍스트는 사람이 보는 기록, JSON은 기계가 먹는 구조화, Kafka는 중앙 수집 파이프라인 전용.

1. CONSOLE → 개발자 눈으로 확인 (개발·디버깅용)
2. TEXT_FILE → RestAPI, Excel 파싱 등 사람용 기록
3. JSON_FILE → Kafka 장애 대비, Filebeat Fallback용 머신용 구조화 로그
4. KAFKA_JSON → 중앙 수집 파이프라인 전송 (ELK 스택용)

같은 사건이 네 갈래로 나뉘어도, MDC 스키마가 같으니 서로 연결할 수 있었다.
콘솔에서 본 traceId를 Kibana에서 이어서 추적하고, 텍스트 파일에서 찾은 userId로 Kafka 토픽 로그를 좁혀보는 식이다.

이제는 “로그를 많이 찍자”가 아니라, “로그를 어디로, 어떤 표정으로 보낼지”가 중요한 고민이 되었다.

1. CONSOLE — 개발자 눈

개발 단계에서 가장 먼저 확인하는 건 언제나 콘솔이다.
빠르게 원인을 찾으려면 한눈에 들어오는 가독성이 필요하다.
그래서 패턴에는 traceId, spanId, userId 같은 추적용 키들을 전부 넣었다.

<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
  <encoder>
    <pattern>
      %d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36}
      [traceId:%X{traceId}] [spanId:%X{spanId}] [userId:%X{userId}]
      [uri:%X{uri}] [method:%X{method}] [ip:%X{clientIp}] - %msg%n
    </pattern>
  </encoder>
</appender>

2. TEXT_FILE — 운영자가 직접 보는 기록

운영 중에는 “사람이 직접 로그를 열어보는 순간”이 꽤 많다.
특정 요청을 grep으로 추적하거나, Excel로 내려받아 분석할 때가 대표적이다.

그래서 TEXT_FILE은 사람이 읽기 좋은 Key=Value 형태로 표준화했다.
logs/text/ 폴더에 날짜별로 롤링되도록 설계해, “운영자가 빠르게 검색하고 파싱할 수 있는 형태”를 보장했다.

<appender name="TEXT_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
  <file>${LOG_PATH}/text/client-requests.log</file>
  <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
    <fileNamePattern>${LOG_PATH}/text/client-requests.%d{yyyy-MM-dd}.log</fileNamePattern>
    <maxHistory>30</maxHistory>
  </rollingPolicy>
  <encoder>
    <pattern>
      timestamp=%X{timestamp}, traceId=%X{traceId}, spanId=%X{spanId}, userId=%X{userId},
      uri=%X{uri}, method=%X{method}, clientIp=%X{clientIp}, userAgent=%X{userAgent},
      level=%level, logger=%logger{36}, message=%msg%n
    </pattern>
  </encoder>
</appender>

3. JSON_FILE — Filebeat Fallback 저장소

Kafka가 장애를 만나면 로그가 끊길 수 있다.
그럴 때 최소한의 안전망으로 JSON 파일을 두었다.

이 Appender는 Filebeat가 바로 읽을 수 있는 구조화 로그를 logs/json/에 쌓는다.
Kafka가 잠시 멈추더라도, 서비스 기록은 여전히 남아있어 “머신이 먹을 수 있는 원본 데이터”가 보존된다.

<appender name="JSON_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
  <file>${LOG_PATH}/json/app-log.json</file>
  <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
    <fileNamePattern>${LOG_PATH}/json/app-log.%d{yyyy-MM-dd}.json</fileNamePattern>
    <maxHistory>30</maxHistory>
  </rollingPolicy>
  <encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder">
    <providers>
      <timestamp /><logLevel /><loggerName /><threadName /><message /><mdc />
    </providers>
  </encoder>
</appender>

4. KAFKA_JSON — 중앙 파이프라인 전송 (App-logs 토픽)

운영 로그의 최종 목적지는 ELK 스택 같은 중앙 수집 시스템이다.
그래서 KafkaAppender를 통해 로그를 바로 app-logs 토픽으로 보냈다.

여기서는 “실시간 스트림”이 핵심이라 파일을 거치지 않고 바로 토픽으로 흘려보낸다.
성능 문제를 막기 위해 AsyncAppender로 감싸 안정성을 높였고, MDC와 예외 정보까지 JSON에 담아 보냈다.

<appender name="KAFKA_JSON" class="com.github.danielwegener.logback.kafka.KafkaAppender">
  <topic>app-logs</topic>
  <encoder class="com.github.danielwegener.logback.kafka.encoding.LayoutKafkaMessageEncoder">
    <layout class="net.logstash.logback.layout.LogstashLayout">
      <includeMdc>true</includeMdc>
      <includeException>true</includeException>
    </layout>
  </encoder>
  <producerConfig>bootstrap.servers=${KAFKA_BOOTSTRAP_SERVERS}</producerConfig>
  <producerConfig>acks=1</producerConfig>
</appender>

<appender name="ASYNC_KAFKA" class="ch.qos.logback.classic.AsyncAppender">
  <appender-ref ref="KAFKA_JSON"/>
  <queueSize>10000</queueSize>
  <neverBlock>true</neverBlock>
</appender>

<logger name="kafkaLogger" level="INFO" additivity="false">
  <appender-ref ref="ASYNC_KAFKA"/>
</logger>

---

📂 폴더 구조는 단순하게

기본 spring.log는 쓰지 않았다. 내가 설계한 text / json 두 갈래만 유지했다.

logs/
├─ text/
│  └─ client-requests.2025-09-09.log
└─ json/
   └─ app-log.2025-09-09.json

여기서 중요한 건 <file>(현재 쓰는 파일)과 <fileNamePattern>(롤링 결과)이 같은 디렉터리여야 한다는 점이다.

나는 이걸 실수로 틀린 적이 있었고, 어제 로그가 딴 폴더에 가버려서 수집기가 꼬인 적이 있다.
그 뒤로는 더 단호하게 폴더를 쪼갰다......

---

🌐 환경별 분기는 xml 안에서 끝냈다

개발 환경에서는 콘솔 위주, 운영 환경에서는 파일과 카프카가 주력으로 삼았다.
이 차이를 xml 안에서 분리한 것이 바로 logback-spring.xml을 쓸 수밖에 없는 이유였다.

<springProfile name="dev">
  <root level="INFO">
    <appender-ref ref="CONSOLE"/>
    <appender-ref ref="TEXT_FILE"/>
  </root>
</springProfile>

<springProfile name="prod">
  <root level="INFO">
    <appender-ref ref="TEXT_FILE"/>
    <appender-ref ref="JSON_FILE"/>
  </root>
  <logger name="kafkaLogger" level="INFO" additivity="false">
    <appender-ref ref="ASYNC_KAFKA"/>
  </logger>
</springProfile>

---

🔥 마무리하며

정리하자면, 나는 logback-spring.xml을 선택한 이유부터 MDC 표준화 → 목적별 Appender 분리 → 경로·롤링 명확화 → 환경 분기까지, 운영을 전제로 한 설계 과정을 풀어냈다.

로그백 설정은 단순히 “찍는 법”이 아니었다.
👉 누가, 어디서, 무엇을 위해 로그를 볼 것인지까지 고민하는 과정이었다.