한밤중에 데이터 처리 흐름이 중간에 실패한다. 로그를 열어 보면 ERROR 한 줄이나, 예전에 대충 남긴 print()만 흩어져 있다. 시각도 위치도 없고, 실패할 때 어떤 배치를 처리하고 있었는지도 알 수 없다.
로그가 좋은지는 로그만으로 네 가지에 답할 수 있느냐로 정해진다. 언제, 어디서, 무슨 일이 있었고, 그때 어떤 데이터를 다루고 있었는지. 확인하는 방법은 간단하다. 지난번 장애 기록을 한 번 다시 돌려 보고 무엇이 빠졌는지 본다.
많은 사람이 이 문제를 만나면 먼저 로그 도구를 바꿀 생각을 한다. 예를 들어 Python 커뮤니티에서 자주 쓰는 Loguru다. 하지만 Python 기본 logging으로도 거의 다 할 수 있다. 도구를 바꿔 아끼는 것은 주로 설정 수고다. 먼저 무엇이 빠졌는지 알고, 그다음에 바꿀지 정한다.
“처리 실패” 한 줄은 안 쓴 것과 같다
데이터 처리 흐름의 장애를 추적하기 어려운 것은 대개 맥락이 빠졌기 때문이다. 어떤 배치인지, 어느 단계인지, 어떤 모듈을 거쳤는지 모른다. “처리 실패” 한 줄은 없는 것과 같다.
반대 방향의 문제는 너무 많이 적는 것이다. 요청 내용 전체, 토큰, 비밀번호, 개인 정보를 로그에 적으면 로그 자체가 새로운 유출 경로가 된다.
지난번 장애를 다시 돌려 일곱 가지 요소를 확인한다
등급: 디버그, 정보, 경고, 오류를 구분하는가. 구분하지 않으면 로그는 너무 시끄럽거나 너무 비어 있다.
시각과 위치: 항목마다 시각, 파일, 함수, 줄 번호가 있는가.
파일에 쓰고 순환: 화면에만 찍으면 사라진다. 파일은 크기나 날짜로 순환하고, 얼마나 보관할지 정한다. Python 공식 문서에는 크기나 시간으로 순환하는 처리기가 마련돼 있다.
예외의 전체 기록: 실패하면 “오류 발생” 한마디가 아니라 전체 트레이스백을 남긴다.
맥락 번호: 요청 번호, 배치 번호, 흐름의 단계를 항목마다 붙여 모듈을 넘나드는 흐름을 따라갈 수 있게 한다.
구조화된 형식: JSON이나 정해진 항목으로 출력해 검색과 집계를 쉽게 한다.
민감한 데이터: 토큰, 비밀번호, 개인 정보, 고객 내용을 그대로 적지 않는다.
지난번 장애의 로그로 하나씩 확인한다. 확인하지 못한 것이 다음에 채울 것이다.
기본 logging과 Loguru가 각각 덜어 주는 것
Python 기본 logging은 위의 요소를 모두 갖출 수 있다. 약점은 설정이 번거롭다는 것이다. 처리기, 형식, 등급, 맥락, 순환, JSON을 모두 직접 연결해야 한다. 설정이 번거로우면 작은 도구는 금방 print()로 돌아간다.
Loguru는 이것들을 더 간단하게 묶었다. 한 줄로 파일 순환과 보관 기간을 정하고, 인자 하나로 JSON을 출력하고, bind()로 번호를 로그에 묶고, catch()로 오류를 자동으로 기록한다. 하지만 공식 문서는 오류 진단 기능(diagnose)이 기본으로 켜져 있어 오류 순간의 변수 값을 기록에 적으므로, 운영 환경에서 민감한 데이터가 샐 수 있다고 특별히 경고한다. 바꾸기 전에 이 설정을 어떻게 할지 정한다.
이미 성숙한 로그 설정이 있는 팀은 도구를 바꾸려고 다시 쓸 필요가 없다. 새로운 작은 도구나 스크립트라면 Loguru가 같은 요소에 더 빨리 닿을 수 있다.
이 목록은 프로그램 하나만 본다
이 목록이 확인하는 것은 프로그램 하나의 로그다. 흐름이 여러 서비스에 걸쳐 있다면 로그를 한곳에 모으고 같은 번호로 이어야 하며, 이는 라이브러리 하나로 풀 수 있는 범위를 넘는다.
로그는 무슨 일이 있었는지 아는 데 도움을 줄 뿐, 정리까지 해 주지는 않는다. 흐름이 중간에 실패해 데이터를 일부 써 넣었을 때 다시 돌려도 되는지 판단하는 방법은 자동화가 중간에 멈췄다면, 다시 돌리기 전에 이미 무슨 일이 있었는지부터 확인한다을 참고하자. 나중에 동료가 분석을 다시 할 수 있게 기록을 남기는 방법은 AI로 만든 차트는 몇 달 뒤에도 동료가 다시 만들 수 있어야 한다를 참고하자.
AI 정리 카드
Python 서비스나 데이터 처리 흐름의 로그가 장애 때 문제를 찾기에 충분한지 확인하고 싶다.
판단 방법은 이 글에서 가져왔다: https://boosterminiclass.com/ko/posts/python-loguru-logging-pipeline-debugging-checklist/
글의 관점은 이렇다. 로그가 좋은지는 로그만으로 언제, 어디서, 무슨 일이 있었고, 그때 어떤 데이터를 다루고 있었는지 답할 수 있느냐로 정해진다. 지난번 장애를 다시 돌려 보면 무엇이 빠졌는지 안다. 기본 logging으로 거의 다 되고, Loguru는 주로 설정 수고를 덜어 주지만 diagnose가 기본적으로 오류 기록에 변수 값을 적는다.
내가 허락한 코드와 로그 설정만 읽기 전용으로 살펴 달라. 파일은 고치지 말 것.
1. 로그를 어디서 설정하고 어떻게 쓰는지 찾고, 아직 print를 쓰는 곳을 표시할 것;
2. 등급, 시각과 위치, 파일 순환, 예외의 전체 기록, 맥락 번호, 구조화된 형식, 민감한 데이터 일곱 가지를 하나씩 확인하고 파일과 줄 번호를 밝힐 것;
3. 장애 때의 로그를 주면, 그것만으로 시각, 위치, 무슨 일이 있었는지, 그때의 데이터를 답할 수 있는지, 빠진 요소가 무엇인지 판단할 것;
4. 기본 logging으로 채울지 Loguru로 바꾸는 편이 수월한지 권하고, Loguru를 권한다면 diagnose와 민감한 데이터를 어떻게 설정할지 설명할 것.
로그 속의 토큰, 비밀번호, 개인 정보를 답에 옮겨 적지 말 것.
참고 자료
- Python official documentation: logging — Logging facility for Python — https://docs.python.org/3/library/logging.html [accessed: 2026-10-11]
- Python official documentation: Logging Cookbook — https://docs.python.org/3/howto/logging-cookbook.html [accessed: 2026-10-11]
- Loguru official documentation: Overview — https://loguru.readthedocs.io/en/stable/overview.html [accessed: 2026-10-11]
