👋 챕터 소개

안녕하세요! 지금까지 우리는 사람이 읽기 좋은 로그를 만드는 데 집중해왔습니다. 하지만 실제 운영 환경에서는 하루에 수백만, 수천만 건의 로그가 쏟아져요. 이 방대한 양의 로그를 사람이 일일이 눈으로 읽고 분석하는 것은 불가능에 가깝습니다. 🕵️➡️💻

이번 챕터에서는 로그의 최종 소비자가 '사람'이 아닌 '기계'가 되는 세상을 만나봅니다. 로그 분석 시스템이 가장 좋아하는 음식인 JSON 형식으로 로그를 남기는 방법을 배울 거예요. logger.add()에 단 하나의 파라미터, serialize=True를 추가하는 것만으로 여러분의 로그가 얼마나 똑똑해질 수 있는지 직접 확인해 보세요!

🎯 챕터 목표

이번 챕터를 마치면 여러분은 다음을 할 수 있게 될 거예요!

일반 텍스트 로그의 한계와 구조화된(Structured) 로깅의 필요성을 설명할 수 있습니다.
serialize=True 파라미터를 사용하여 모든 로그를 JSON 형식으로 손쉽게 변환할 수 있습니다.
출력된 JSON 로그의 구조를 분석하고, 각 필드가 어떤 정보를 담고 있는지 이해합니다.
bind()로 추가한 컨텍스트 데이터가 JSON에 어떻게 포함되는지, 그리고 이것이 로그 검색 및 필터링을 얼마나 강력하게 만드는지 깨닫게 됩니다.

💻 이번 챕터에서 사용되는 전체 코드 및 프로젝트 구조

structured_logging.py 파일을 새로 추가하여 실습합니다. 코드를 실행하면, 모든 로그가 한 줄씩 JSON 형식으로 깔끔하게 저장된 structured_log.json 파일이 생성됩니다.

프로젝트 구조

loguru-course/
├── venv/
├── ... (이전 강의 파일들)
├── structured_logging.py      <- 새로 추가된 파일!
└── structured_log.json        <- 코드 실행 후 생성될 파일!

structured_logging.py 전체 코드

# structured_logging.py
import sys
import uuid
from loguru import logger

# 1. 기본 핸들러 제거
logger.remove()

# 2. JSON 출력을 위한 파일 싱크 추가
#    serialize=True 파라미터 하나로 모든 로그 레코드가 JSON 형식으로 변환됩니다.
logger.add("structured_log.json", serialize=True)

# 3. 비교를 위해, 사람이 읽기 좋은 일반 텍스트 로그를 콘솔에도 출력합니다.
logger.add(sys.stderr, level="INFO")

def handle_payment(user_id, amount):
    # 각 결제 처리마다 고유한 transaction_id를 부여합니다.
    tx_id = f"tx-{uuid.uuid4().hex[:12]}"

    # transaction_id와 user_id를 컨텍스트에 바인딩합니다.
    payment_logger = logger.bind(transaction_id=tx_id, user_id=user_id)

    payment_logger.info(f"결제 시도: {amount}원")

    if amount > 100000:
        payment_logger.warning("고액 결제(10만원 초과)입니다. 추가 인증이 필요할 수 있습니다.")

    # ... 가상의 결제 처리 로직 ...
    payment_logger.success("결제 처리가 성공적으로 완료되었습니다.")

if __name__ == "__main__":
    handle_payment("user-jane", 50000)
    handle_payment("user-john", 150000)

📖 강의 내용

🤔 구조화 로깅, 왜 필요할까요?

사람의 눈에는 일반 텍스트 로그가 읽기 편하지만, 기계에게는 그저 의미 없는 문자열의 나열일 뿐이에요. 예를 들어, "user-john의 결제가 실패했습니다" 라는 로그에서 'user-john'이라는 사용자 아이디만 뽑아내려면 복잡한 문자열 처리(파싱)가 필요합니다.

***구조화 로깅(Structured Logging)***은 모든 로그를 key-value 형태, 즉 JSON처럼 명확한 구조를 가진 데이터로 기록하는 방식입니다. 이렇게 하면 기계(로그 분석 시스템)가 각 로그의 속성을 아주 쉽게 이해하고, 강력한 검색과 분석, 시각화를 수행할 수 있게 됩니다.