파이썬에서 로그를 체계적으로 관리해야 하는 이유
파이썬으로 작은 스크립트를 작성할 때는 상태를 확인하기 위해 무심코 print() 함수를 사용하곤 합니다. 하지만 프로그램의 규모가 커지고 자동화 스크립트가 주기적으로 백그라운드에서 실행되기 시작하면, print() 출력만으로는 언제 어떤 오류가 발생했는지 추적하기 어렵습니다. 에러 메시지가 화면에 출력되어도 로그 파일로 남지 않거나, 발생 시각과 심각도를 구분할 수 없기 때문입니다.
[목차]
이번 글에서는 파이썬 표준 라이브러리인 logging 모듈을 활용하여, 실무에서 가장 많이 쓰이는 기본 설정 패턴을 살펴봅니다. 콘솔 출력과 파일 저장을 동시에 처리하고, 로그 레벨을 적절히 나누어 기록하는 방법을 단계별로 익혀봅니다.
logging 모듈의 핵심 개념과 로그 레벨
파이썬 logging 모듈은 프로그램 실행 중 발생하는 이벤트를 심각도에 따라 분류합니다. 무작정 모든 메시지를 기록하기보다는 상황에 맞는 로그 레벨을 선택하는 것이 중요합니다.
- DEBUG: 상세한 정보로, 주로 문제를 진단할 때 사용합니다.
- INFO: 프로그램이 정상적으로 잘 작동하고 있음을 알리는 일반적인 정보입니다.
- WARNING: 예상치 못한 일이 발생했거나 가까운 미래에 문제가 발생할 수 있음을 경고합니다. (기본 설정 레벨)
- ERROR: 심각한 문제로 인해 프로그램의 일부 기능을 수행하지 못한 경우입니다.
- FATAL / CRITICAL: 프로그램 자체가 중단될 수 있는 매우 심각한 오류입니다.
기본적으로 logging 모듈은 WARNING 레벨 이상만 출력하므로, 개발 및 운영 단계에서는 명시적으로 레벨을 INFO 또는 DEBUG로 설정해 주어야 합니다.
실무에서 자주 쓰는 기본 설정 패턴
실무 환경에서는 로그를 화면(콘솔)에 보여주는 동시에, 나중에 분석할 수 있도록 로그 파일에도 영구적으로 기록해야 합니다. 다음은 핸들러(Handler)와 포매터(Formatter)를 조합하여 콘솔과 파일에 동시에 로그를 남기는 표준적인 코드 패턴입니다.
import logging
# 1. 로거 객체 생성
logger = logging.getLogger('MyAutomationTask')
logger.setLevel(logging.INFO)
# 중복 핸들러 방지 조건문
if not logger.handlers:
# 2. 포매터 생성 (시간, 로그레벨, 메시지 형식 지정)
formatter = logging.Formatter('%(asctime)s - %(levelname)s - %(message)s')
# 3. 콘솔(터미널) 핸들러 설정
stream_handler = logging.StreamHandler()
stream_handler.setFormatter(formatter)
# 4. 파일 핸들러 설정 (UTF-8 인코딩 지정)
file_handler = logging.FileHandler('app_execution.log', encoding='utf-8')
file_handler.setFormatter(formatter)
# 5. 로거에 핸들러 추가
logger.addHandler(stream_handler)
logger.addHandler(file_handler)
# 사용 예시
logger.info('프로그램 실행을 시작합니다.')
logger.warning('디스크 용량이 부족할 수 있습니다.')
logger.error('데이터베이스 연결에 실패했습니다.')
위 코드를 실행하면 스크립트가 실행되는 터미널 창에 로그가 출력되는 동시에, 같은 폴더에 app_execution.log 파일이 생성되어 동일한 내용이 차곡차곡 쌓이게 됩니다.
자주 하는 실수와 주의사항
파이썬 logging을 처음 도입할 때 반복적으로 겪는 몇 가지 실수가 있습니다. 코드를 작성할 때 다음 사항을 주의해야 합니다.
- print 함수와 혼용: 중요한 상태값이나 에러를
print()로 남기면 로그 파일에 누락됩니다. 일관성 있게logger.info()나logger.error()를 사용해야 합니다. - 핸들러 중복 추가: Jupyter Notebook이나 반복 호출되는 함수 내부에서
logger.addHandler()를 조건문 없이 실행하면, 동일한 로그가 한 번에 여러 번 중복 출력됩니다. 핸들러 존재 여부를 체크하는 로직이 필수적입니다. - 인코딩 미지정: 윈도우 환경에서
FileHandler를 생성할 때encoding='utf-8'을 누락하면 한글 로그가 깨지거나UnicodeEncodeError가 발생할 수 있습니다. - 로거 이름 생략:
logging.getLogger()에 이름을 인자로 넘기지 않으면 루트 로거(root logger)를 사용하게 되어 외부 라이브러리 로그와 충돌할 수 있습니다. 스크립트 고유의 이름을 지정하는 것이 좋습니다. - [ ] 루트 로거 대신
logging.getLogger('모듈이름')형태로 전용 로거를 생성했는가? - [ ] 프로젝트 요구사항에 맞춰 로거의 레벨을
INFO또는DEBUG로 적절히 설정했는가? - [ ] 터미널 콘솔 출력과
FileHandler를 통한 파일 저장을 모두 구현했는가? - [ ] 로그 포맷에
%(asctime)s를 포함하여 발생 시점을 명확히 기록하고 있는가? - [ ] 로그 파일 저장 시
encoding='utf-8'을 명시하여 한글 깨짐을 방지했는가? - [ ] 동일한 핸들러가 중복 등록되지 않도록 조건문(
if not logger.handlers:) 처리를 하였는가?
실무 적용 점검 체크리스트
파이썬 자동화 스크립트에 로깅 기능을 도입할 때 점검해야 할 항목들을 정리했습니다.
마무리
파이썬의 logging 모듈은 처음에는 설정 과정이 번거로워 보일 수 있지만, 한 번 기본 패턴을 익혀두면 장기 실행 스크립트나 자동화 프로그램의 유지보수 효율을 극적으로 높여줍니다. print() 대신 체계적인 로그 레벨과 파일 기록 방식을 적용하여 안전하고 견고한 파이썬 코드를 작성해 보시길 바랍니다.