Logging 모듈을 통한 로깅 (StreamHandler, FileHandler, RotatingFileHandler, TimedRotatingFileHandler)

logging은 python 기본 라이브러리 상으로 제공되는 모듈로, application과 library에서 발생하는 이벤트들의 로깅을 위해 사용된다.

 

컴포넌트

로거(logger)

로그를 생성하는 주체, 로거에 로그메시지를 생성해서 로그가 발생하는 구조

 

핸들러(handler)

생성된 로그를 보낼 곳을 결정하는 주체, logging 모듈에서는 아래와 같이 4개의 handler를 정의한다.

• StreamHandler : stdout 출력
• FileHandler : 파일로 출력
• RotatingFileHandler : 파일 용량에 따른 자동 회전되는 로그 파일 포맷으로 출력
• TimedRotatingFileHandler :  일정 시간 간격으로 회전되는 로그 파일 포맷으로 출력

각 로거는 핸들러에 연결해서 발생한 로그를 핸들러에 맞는 목적지로 전송

 

포매터(formatter)

로그 메시지의 형태를 결정하는 주체, 해당 로그의 발생 시각, 함수명 등의 메타데이터들을 자동으로 포함시키도록 포매팅을 구성할 수 있다.

import logging

logger = logging.getLogger("multi_handler_app")
logger.setLevel(logging.DEBUG)

# 파일 handler
file_handler = logging.FileHandler("app.log")
file_handler.setLevel(logging.ERROR)

# formatter 지정
formatter = logging.Formatter('%(asctime)s - %(levelname)s - %(message)s')
file_handler.setFormatter(formatter)

 

로그 레벨

각 logger에는 로깅 요청을 실제로 처리할 지 여부를 판단하는 '로그 레벨' 개념이 존재한다.

DEBUG, INFO, WARNING, ERROR, CRITICAL로 나뉘며, 이 순서대로 심각도를 구분해 로그분석에 가독성을 높여준다.

import logging

app_logger = logging.getLogger('my_app')

# logger에 로그레벨을 정의
app_logger.setLevel(logging.INFO)

 

logger에 지정된 레벨보다 크거나 같은 레벨의 로깅요청만 처리되어 일종의 필터링 역할을 해준다.

ex. 어떤 logger에 INFO 레벨로 지정, DEBUG 레벨의 메시지는 해당 logger에 발생되지 않음

 

 

logging 핸들러

logging 모듈에서 제공하는 핸들러는 10개 이상 존재한다. 이 중 대표적으로 이용되는 4가지 종류를 알아본다.

 

StreamHandler

로그를 stdout/stderr 등의 스트림으로 내보내는 핸들러

가장 기본적인 핸들러로, 별도의 로그파일을 생성하지 않는 형식의 핸들러

import logging

logger = logging.getLogger("console_logger")
logger.setLevel(logging.DEBUG)

console_handler = logging.StreamHandler()
formatter = logging.Formatter('%(levelname)s - %(message)s')
console_handler.setFormatter(formatter)

logger.addHandler(console_handler)

logger.info("[*] Stream logging message")

 

FileHandler

로그를 파일에 기록하는 핸들러

이 핸들러는 단일 파일에 기록하므로, 실제 환경이나 로그가 대량으로 발생할 수 있는 상황에서는 rotating되는 핸들러를 사용하는 것이 추천된다.

import logging

logger = logging.getLogger("file_logger")
logger.setLevel(logging.INFO)

file_handler = logging.FileHandler("app.log", encoding="utf-8")
formatter = logging.Formatter('%(asctime)s - %(levelname)s - %(message)s')
file_handler.setFormatter(formatter)

logger.addHandler(file_handler)

logger.info("[*] File logging message")

 

RotatingFileHandler

FileHandler와 동일하게 로그를 파일에 기록하되, 파일의 용량에 따라 rotating되는 로직이 추가된 핸들러

핸들러에서 지정한 용량을 넘는 경우에 새 로그파일이 생성되고, 그 파일에 로깅이 이어지는 형식이다.

import logging
from logging.handlers import RotatingFileHandler

logger = logging.getLogger("rotate_logger")
logger.setLevel(logging.INFO)

rotate_handler = RotatingFileHandler(
    "rotate_app.log", 
    maxBytes=1024*1024,  # 1MB 넘으면 새 파일
    backupCount=3,       # 3개까지 로그파일 유지
    encoding="utf-8"
)
formatter = logging.Formatter('%(asctime)s - %(levelname)s - %(message)s')
rotate_handler.setFormatter(formatter)

logger.addHandler(rotate_handler)

logger.info(f"[*] Rotating file logging message")

 

rotating이 발생할 때, 로그파일에 `.1`, `.2`와 같은 확장자를 붙여서 지난 로그파일을 저장한다.

이때, `backupCount`파라미터로 유지할 로그파일의 최대 갯수를 지정할 수 있고, 최대 갯수를 넘은 경우에는 오래된 파일(큰 숫자)부터 삭제되며 최대 갯수를 유지한다.

 

TimedRotatingFileHandler

FileHandler와 동일하게 로그를 파일에 기록하되, 지정한 시간에 따라 rotating되는 로직이 추가된 핸들러

import logging
from logging.handlers import TimedRotatingFileHandler

logger = logging.getLogger("time_rotate_logger")
logger.setLevel(logging.INFO)

time_handler = TimedRotatingFileHandler(
    "time_app.log",
    when="midnight",  # 자정마다 회전
    interval=1,       # 1일마다
    backupCount=7,    # 최근 7일 보관
    encoding="utf-8"
)
formatter = logging.Formatter('%(asctime)s - %(levelname)s - %(message)s')
time_handler.setFormatter(formatter)

logger.addHandler(time_handler)

logger.info("[*] Timed rotating file handler")

 

`when` 파라미터로 rotating되는 시각을 지정할 수 있고, `interval`로 rotating 주기를 지정할 수 있다.

 

RotatingFileHandler와 마찬가지로 rotating이 발생하면 파일의 확장자에 접미사를 붙여서 지난 로그파일을 저장한다.

다만, TimedRotatingFileHandler는 `.suffix`를 통해 rotating되는 파일들의 접미사를 지정해줄 수 있다.

# rotating 파일 접미사 설정
time_handler.suffix = "%Y-%m-%d"

### rotate된 파일은 아래처럼 지정된 접미사를 붙여서 저장함
timed_app.log               # 현재 파일 (오늘 날짜)
timed_app.log.2025-10-11
timed_app.log.2025-10-12

 

 

이와 같은 4개의 핸들러를 정리하면 아래와 같다.

핸들러	출력대상	Rotating	주요 파라미터	추천 예시
StreamHandler	스트림 (stdout/stderr)	없음	없음	개발용(실시간 확인)
FileHandler	파일	없음	filename, encoding	개발용
RotatingFileHandler	파일	있음(용량)	maxBytes, backupCount	장기 운영 서비스 등
TimedRotatingFileHandler	파일	있음(시간)	when, interval, backupCount	일/주간 로그 관리가 필요한 경우 등

 

 

Docs

logging.handlers — Logging handlers