# 🎓 세션 4: 로깅 시스템 구축 학습 정리

📋 세션 개요

• 주제: Python 로깅 시스템 구축 및 이해
• 기준 코드: insupanda-rag의 src/config/logger.py
• 학습 방식: 직접 타이핑 + 상세 주석으로 개념 학습
• 완성 결과: 콘솔과 파일에 동시 출력되는 로깅 시스템

🔍 핵심 개념 학습

1. 로깅(Logging)이란?

• 정의: 프로그램 실행 중 발생하는 이벤트들을 기록하는 시스템
• 비유: 프로그램의 "일기장" - 언제 무슨 일이 일어났는지 상세 기록
• 필요성: 디버깅, 모니터링, 분석, 증거 보전

2. 로깅 레벨 5단계

DEBUG < INFO < WARNING < ERROR < CRITICAL

• DEBUG: 개발자용 상세 정보 (가장 자세함)
• INFO: 일반적인 정보 ← 우리 프로젝트에서 사용
• WARNING: 경고 메시지
• ERROR: 에러 발생
• CRITICAL: 치명적 오류 (가장 심각함)

3. 핸들러(Handler) 개념

로그를 "어디에" 보낼지 결정하는 배달원 역할

StreamHandler

• 역할: 콘솔(터미널 화면)에 실시간 출력
• 장점: 즉시 확인 가능, 개발 중 디버깅 용이
• 단점: 프로그램 종료 시 사라짐

FileHandler

• 역할: 파일에 영구 저장
• 장점: 영구 보관, 나중에 분석 가능
• 설정: ("app.log", "a", "utf-8")
  • "app.log": 파일명
  • "a": append 모드 (기존 내용에 추가)
  • "utf-8": 한글 지원 인코딩

💻 실습 과정

1. 프로젝트 구조 확인

insurance-rag-learning/
├── src/
│   ├── config/     ← 여기에 logger.py 생성
│   ├── db/
│   ├── models/
│   └── ...
├── tests/
└── README.md

2. logger.py 핵심 코드

import logging

def setup_logging() -> None:
    logging.basicConfig(
        level=logging.INFO,  # INFO 이상만 기록
        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
        handlers=[
            logging.StreamHandler(),  # 콘솔 출력
            logging.FileHandler("app.log", "a", "utf-8"),  # 파일 저장
        ],
    )

3. 테스트 코드 작성 및 실행

• 파일: test_logging.py
• 테스트 내용:
  • 모든 로깅 레벨 테스트
  • 다양한 모듈별 로깅 테스트
  • 콘솔과 파일 동시 출력 확인

✅ 테스트 결과 분석

성공적인 동작 확인

1. DEBUG 필터링 ✅ - INFO 레벨 설정으로 DEBUG 메시지 차단
2. 로거 이름 구분 ✅ - __main__, database, openai_api 등 모듈별 구분
3. 시간 정확성 ✅ - 밀리초 단위 정확한 타임스탬프
4. 동시 출력 ✅ - 콘솔과 파일에 동일한 내용 기록
5. Append 모드 ✅ - 여러 번 실행해도 로그 누적 저장
6. UTF-8 인코딩 ✅ - 한글 깨짐 없이 완벽 저장

실제 테스트 출력 예시

2025-08-02 01:06:51,021 [INFO] __main__: ℹ️ 프로그램이 정상적으로 시작되었습니다
2025-08-02 01:06:51,021 [WARNING] __main__: ⚠️ 이것은 경고 메시지입니다
2025-08-02 01:06:51,021 [ERROR] __main__: ❌ 에러가 발생했습니다
2025-08-02 01:06:51,021 [INFO] database: 💾 데이터베이스 연결 성공

🆚 기존 insupanda-rag와 비교

공통점 (잘 따라한 부분)

• ✅ 동일한 로깅 레벨 (INFO)
• ✅ 동일한 포맷 구조
• ✅ 동일한 핸들러 조합
• ✅ 동일한 파일 설정

우리 버전의 장점

• 상세한 주석: 각 라인의 목적과 동작 원리 명확히 설명
• 구조화된 코드: setup_logging() 함수로 깔끔하게 정리
• 학습 친화적: 초보자도 이해할 수 있는 상세한 설명

🎯 핵심 학습 포인트

1. 로깅 시스템의 3가지 핵심 기능

1. 콘솔 출력: 실시간 모니터링
2. 파일 저장: 영구 보관 및 분석
3. 레벨 필터링: 필요한 정보만 선별 기록

2. Append 모드의 중요성

• "a" 모드: 기존 로그 보존하며 새 로그 추가
• "w" 모드: 기존 로그 삭제 후 새로 작성 (위험!)
• 실제 증명: 두 번 실행했을 때 모든 로그가 누적 저장됨

3. 로거 이름(%(name)s)의 가치

• 문제 추적: 어느 모듈에서 발생한 로그인지 즉시 식별
• 디버깅 효율성: 에러 발생 시 해당 부분만 집중 분석 가능
• 시스템 모니터링: 각 구성 요소별 상태 개별 확인

🚀 다음 단계 예고

다음 세션에서는 환경 변수와 설정 관리를 다룰 예정입니다:

• Pydantic을 활용한 설정 관리
• 환경변수(.env) 활용법
• 개발/운영 환경 분리 방법

📝 학습 성과

• ✅ 로깅의 핵심 개념 완전 이해
• ✅ Python logging 라이브러리 실습 완료
• ✅ 콘솔/파일 동시 출력 시스템 구축
• ✅ 기존 프로젝트 코드와 비교 분석 완료
• ✅ 실무에서 사용할 수 있는 로깅 시스템 습득