TrendPick100

파이썬 logging 모듈 완벽 가이드: print 대신 파일 로그 남기기와 핸들러 활용법

파이썬 logging 모듈을 활용하여 print 대신 체계적인 로그 파일을 생성하고 관리하는 방법, 5가지 로그 레벨 설정, RotatingFileHandler 용량 제한 및 한글 인코딩 깨짐 해결법을 정리합니다.

본문 상단 광고 구역 (승인 후 자동 노출됩니다)

파이썬으로 프로그램을 개발하거나 백그라운드 자동화 스크립트를 운영할 때, 실행 상태나 오류를 확인하기 위해 가장 먼저 사용하는 함수는 print()입니다. 하지만 장시간 동작하는 프로그램이나 배포 환경에서 print() 문에만 의존하면 터미널이 닫히는 순간 모든 기록이 소실되며, 오류가 발생한 정확한 시간과 위치를 추적하기가 사실상 불가능합니다.

파이썬 표준 라이브러리에 내장된 logging 모듈을 사용하면 실행 흐름을 5단계의 심각도(Severity)로 분류하고, 타임스탬프가 포함된 로그를 파일에 영구 보관할 수 있습니다. logging 모듈의 기본 설정부터 실무에서 필수적인 로그 파일 용량 관리(RotatingFileHandler), 한글 깨짐 방지 트러블슈팅까지 체계적으로 정리합니다.

1. print() 함수의 한계와 logging 모듈의 장점

단순 디버깅용 print() 함수와 전문 로깅 시스템의 가장 큰 차이는 ‘기록의 구조화’와 ‘필터링’에 있습니다.

  • 시간 및 위치 추적: 로그가 발생한 정확한 날짜, 시각, 소스 코드 파일명, 함수명, 코드 라인 번호를 자동으로 기록합니다.
  • 로그 레벨별 필터링: 개발 중에는 상세한 디버그 메시지를 보고, 운영 서버에서는 에러 로그만 선별하여 파일에 저장하도록 코드 수정 없이 임계치를 조절할 수 있습니다.
  • 로그 파일 자동 순환(Rotation): 로그 파일의 크기가 무한정 커져 디스크 용량을 채우는 문제를 사전에 차단합니다.

2. 파이썬 로깅의 5가지 레벨(Level)

logging 모듈은 이벤트의 중요도에 따라 5단계의 기본 레벨을 제공합니다. 기본값(Default)은 WARNING 레벨로 설정되어 있어, 별도 설정이 없으면 DEBUG와 INFO 메시지는 무시됩니다.

  • DEBUG (10): 개발 단계에서 상세한 변수 값, 알고리즘 흐름을 진단하기 위한 가장 상세한 로그
  • INFO (20): 서버 구동, 작업 완료, 주기적 배치 실행 등 정상적인 운영 상태를 알리는 일반 정보
  • WARNING (30): 당장 프로그램이 중단되지는 않지만, 향후 문제가 될 수 있는 경고 상황 (기본 임계 레벨)
  • ERROR (40): 특정 기능 실행 실패, API 호출 타임아웃, 예외 발생 등 주요 작업이 실패한 상태
  • CRITICAL (50): 메모리 고갈, 데이터베이스 연결 완전 두절 등 프로그램 전체가 강제 종료될 수준의 치명적 오류

3. basicConfig를 활용한 기본 파일 로깅

가장 빠르고 간편하게 파일에 로그를 기록하는 방법은 logging.basicConfig() 함수를 사용하는 것입니다.

import logging

# 로깅 기본 설정
logging.basicConfig(
    filename='application.log',      # 저장할 파일 이름
    filemode='a',                    # 'a': 이어쓰기(Append), 'w': 덮어쓰기(Write)
    level=logging.DEBUG,             # 기록할 최소 로그 레벨 지정
    format='%(asctime)s [%(levelname)s] (%(filename)s:%(lineno)d) - %(message)s',
    datefmt='%Y-%m-%d %H:%M:%S'
)

# 로그 기록 테스트
logging.debug("디버깅용 상세 변수 값 확인")
logging.info("프로그램이 성공적으로 시작되었습니다.")
logging.warning("네트워크 응답 속도가 느립니다.")
logging.error("데이터베이스 쿼리 실행 실패")
logging.critical("치명적인 메모리 누수 감지됨")

위 스크립트를 실행하면 application.log 파일이 생성되며 다음과 같이 표준 포맷으로 로그가 누적됩니다.

2026-08-28 15:45:00 [DEBUG] (app.py:12) - 디버깅용 상세 변수 값 확인
2026-08-28 15:45:00 [INFO] (app.py:13) - 프로그램이 성공적으로 시작되었습니다.
2026-08-28 15:45:00 [WARNING] (app.py:14) - 네트워크 응답 속도가 느립니다.
2026-08-28 15:45:00 [ERROR] (app.py:15) - 데이터베이스 쿼리 실행 실패
2026-08-28 15:45:00 [CRITICAL] (app.py:16) - 치명적인 메모리 누수 감지됨

4. 실무형 로그 관리: 용량 기반 분할(RotatingFileHandler)

장기간 24시간 실행되는 서버나 자동화 봇의 경우, 단일 파일에 계속 로그를 쓰면 파일 용량이 수 기가바이트(GB)로 커져 열리지 않는 사태가 발생합니다. logging.handlers의 RotatingFileHandler를 사용하여 일정 용량에 도달하면 새 파일을 만들고 백업하도록 구성합니다.

import logging
from logging.handlers import RotatingFileHandler

# 1. 로거 인스턴스 생성
logger = logging.getLogger("MyServiceLogger")
logger.setLevel(logging.INFO)

# 2. 포맷터 정의
formatter = logging.Formatter('%(asctime)s [%(levelname)s] - %(message)s')

# 3. 핸들러 설정: 최대 5MB(5 * 1024 * 1024 bytes), 백업 파일 최대 3개 유지
file_handler = RotatingFileHandler(
    'service.log', 
    maxBytes=5 * 1024 * 1024, 
    backupCount=3, 
    encoding='utf-8'
)
file_handler.setFormatter(formatter)

# 4. 콘솔 출력을 위한 스트림 핸들러 병행 등록
console_handler = logging.StreamHandler()
console_handler.setFormatter(formatter)

# 5. 로거에 핸들러 부착
logger.addHandler(file_handler)
logger.addHandler(console_handler)

# 실행 예시
logger.info("콘솔과 파일에 동시에 기록되는 로그 메시지입니다.")

이 방식을 사용하면 service.log가 5MB를 초과할 때 자동으로 service.log.1, service.log.2로 밀려나며, 지정한 백업 개수를 초과하는 가장 오래된 파일은 자동 삭제됩니다.

5. 자주 발생하는 오류 및 트러블슈팅

1) Windows 환경에서 로그 한글 깨짐 (UnicodeEncodeError)

기본 FileHandler를 사용할 때 윈도우 OS의 기본 인코딩(CP949) 때문에 한글 로그가 깨지거나 인코딩 에러가 발생할 수 있습니다.

  • 원인: 파일 핸들러 생성 시 명시적인 인코딩 파라미터가 누락되었기 때문입니다.
  • 해결법: basicConfig나 FileHandler 선언 시 encoding=’utf-8’을 반드시 명시합니다.
# basicConfig 사용 시 (파이썬 3.9 이상)
logging.basicConfig(filename='app.log', encoding='utf-8', level=logging.INFO)

# FileHandler 직접 사용 시
handler = logging.FileHandler('app.log', encoding='utf-8')

2) basicConfig가 두 번 호출되어 설정이 무시되는 현상

서드파티 모듈이 내부적으로 로깅 설정을 먼저 초기화해 버렸거나, 스크립트 내에서 basicConfig를 두 번 호출하면 두 번째 설정이 완전히 무시됩니다.

  • 원인: basicConfig는 루트 로거에 핸들러가 없을 때만 최초 1회 동작하도록 설계되어 있습니다.
  • 해결법: 파이썬 3.8 이상에서는 force=True 옵션을 추가하여 기존 핸들러를 강제로 초기화하고 덮어씁니다.
# 기존 로깅 핸들러를 강제로 리셋하고 새 설정 적용
logging.basicConfig(
    filename='app.log',
    level=logging.INFO,
    force=True
)

6. 요약 및 실무 적용 팁

파이썬의 logging 모듈은 단순한 출력이 아닌 시스템의 상태와 에러를 감시하는 핵심 인프라입니다.

  • 상용 코드에서는 print() 사용을 전면 배제하고 상황에 맞는 로그 레벨(INFO, ERROR 등)을 사용합니다.
  • 운영 환경에서는 파일 용량 폭증을 방지하기 위해 RotatingFileHandler를 기본으로 사용합니다.
  • 크로스 플랫폼 호환성과 다국어 처리를 위해 항상 encoding=’utf-8′ 옵션을 지정합니다.
본문 하단 광고 구역