logging 모듈을 사용한 Python 로깅, Python 로그 레벨 5가지, Python 오류 처리, 자주 보는 Python 오류 유형을 다룹니다. 마지막 섹션에서는 logbrew-sdk 0.1.29로 같은 로그와 크래시를 LogBrew로 보냅니다. 모든 예제는 Python 3.13에서 실행했으며, 각 출력 블록은 실제 출력입니다.
Flask 앱이라면 이 가이드 대신 Flask 로깅을 사용하세요. 같은 로깅 설정에 요청 트레이스가 더해집니다.
첫 Python 로그 작성하기
이 파일을app.py로 저장하세요. logging.basicConfig()는 프로그램 진입점에서 한 번만 호출하세요. 각 모듈에서는 이름이 있는 로거를 가져오세요.
python3 app.py를 실행하세요. 출력은 표준 오류로 나갑니다.
INFO이므로 debug 레코드는 나타나지 않습니다. logger.exception()은 ERROR 레벨로 기록하고 트레이스백을 추가합니다. 이 메서드는 except 블록 안에서만 호출하세요.
"payment retry %d of %d", 2, 3처럼 값을 인수로 전달하세요. Python은 핸들러가 레코드를 받아들일 때만 메시지를 만듭니다. 메시지 템플릿은 재시도마다 같으므로 이 템플릿으로 검색할 수 있습니다.
Python 로그 레벨
로거는 레코드 레벨이 로거 레벨과 같거나 높을 때만 레코드를 보냅니다. 핸들러에는 더 높은 두 번째 레벨을 설정할 수 있습니다.
루트 로거는
WARNING 레벨에서 시작합니다. 새 로거의 레벨은 NOTSET(0)이며 부모의 레벨을 사용합니다. 프로덕션에서는 INFO를 설정하세요. DEBUG는 개발 중이거나 짧게 진단할 때만 사용하세요.
로거, 핸들러, 포매터
- 로거는 호출을 받습니다. 로거 이름이 모듈 경로를 따르도록
logging.getLogger(__name__)을 사용하세요. - 핸들러는 콘솔, 파일, LogBrew 같은 대상으로 레코드를 보냅니다.
- 포매터는 레코드를 텍스트로 바꿉니다.
logging.NullHandler()만 추가합니다. 핸들러와 레벨은 애플리케이션이 한 번만 설정합니다. 설정이 크면 logging.config.dictConfig()를 사용하세요.
Python 오류 처리
처리할 수 있는 가장 구체적인 예외를 잡으세요. 성공했을 때만 실행할 코드에는else를, 항상 실행할 코드에는 finally를 사용하세요. 원래 원인을 유지하려면 raise ... from error를 사용하세요.
이 파일을 orders.py로 저장하세요.
- 예외는 처리하는 곳에서 한 번만 기록하세요. 계층마다 기록하고 다시 발생시키지 마세요. 계층마다 중복 레코드가 생깁니다.
except Exception: pass를 쓰지 마세요. 오류를 무시한다면 이유와 함께WARNING이상으로 기록하세요.BaseException이 아니라Exception을 잡으세요.BaseException은 의도적으로 프로그램을 멈추는KeyboardInterrupt와SystemExit도 잡습니다.- 호출하는 쪽에서 처리해야 하는 오류에는
OrderError처럼 자체 예외 클래스를 정의하세요.
여러 오류 한 번에 보고하기
Python 3.11 이상에서는ExceptionGroup을 발생시킬 수 있습니다. 한 번의 검사에서 문제를 여러 개 찾았을 때 사용하세요. 각 유형은 except*로 처리하세요.
자주 보는 Python 오류 유형
프로그램이 처리할 수 있는 내장 오류는 모두Exception을 상속합니다. 아래 표는 가장 자주 보는 Python 오류와 각 오류에서 먼저 확인할 점입니다.
KeyboardInterrupt와 SystemExit은 Exception이 아니라 BaseException을 상속합니다. 코드의 오류가 아닙니다.
Python 로그를 LogBrew로 보내기
LogBrewLoggingHandler는 표준 로깅 핸들러입니다. 받아들인 레코드를 하나씩 LogBrew로 보냅니다. 콘솔 핸들러는 그대로 유지됩니다.
1
프로젝트 키 만들기
CLI로 로그인하세요. 프로젝트를 만들고 수집 키를 소유자만 접근할 수 있는 파일에 저장하세요.CLI는 키를 출력하지 않습니다. 프로덕션에서는 사용하는 플랫폼의 시크릿 관리 도구를 사용하세요.
2
SDK 설치하기
애플리케이션의 가상 환경을 활성화하세요. 그런 다음 패키지를 설치하세요. 이 패키지에는 Python 3.10 이상이 필요합니다.
3
키와 배포 정보 설정하기
4
핸들러 추가하기
이 파일을
worker.py로 저장하세요. 클라이언트를 만들기 전에 logging.basicConfig()를 호출하세요. 클라이언트는 루트 로거에 핸들러를 추가하는데, 루트 로거에 이미 핸들러가 있으면 basicConfig()는 아무 작업도 하지 않습니다.HttpTransport()는 첫 이벤트 후 1초가 지나거나 이벤트가 50개 쌓이면 백그라운드에서 이벤트를 보냅니다. client.shutdown()은 남은 이벤트를 보내고 클라이언트를 닫습니다.5
프로그램 실행하기
extra={...}의 원시 값은 메타데이터가 됩니다. 두 번째 이벤트에는 exceptionName KeyError와 exceptionMessage 'seats'가 있습니다. 트레이스백 전체 텍스트를 보내려면 include_exception_text=True로 핸들러를 만드세요.6
로그 다시 읽기
LogBrew로 보낼 레코드 선택하기
레코드를 덜 보내려면 핸들러에 별도 레벨을 지정하세요. 콘솔은 여전히INFO 이상을 받습니다.
Python 크래시를 이슈로 보고하기
install_process_error_capture(client)는 스크립트, 워커, 시작 코드, 스레드에서 잡히지 않은 예외를 보고합니다. 크래시 하나는 이슈 1개가 되며, 예외 타입, 메시지, 스택 프레임, 예외 체인의 원인을 담습니다. Python은 이전과 같이 트레이스백을 출력하고 종료합니다.
이 파일을 startup.py로 저장하고 실행하세요.
FileNotFoundError, 레벨이 critical, 메커니즘이 python.excepthook인 이슈를 받습니다. 프레임에는 파일 이름, 줄, 함수가 있지만 전체 경로는 없습니다. 스레드에서 난 크래시의 레벨은 error입니다. Python이 종료되기 전에 SDK는 전송을 최대 2초 기다립니다.
문제 해결
웹 앱은 Flask 로깅을 참고하세요. 로그 형식을 고르려면 구조화된 로깅을 참고하세요. 다른 런타임은 SDK 연동을 참고하세요.
