메인 콘텐츠로 건너뛰기
LogBrew는 개발자와 코딩 에이전트를 위한 옵저버빌리티 플랫폼입니다. 넉넉한 무료 요금제를 제공하며 카드 등록이 필요 없습니다. 이 가이드는 표준 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

프로그램 실행하기

콘솔 출력은 바뀌지 않습니다. LogBrew는 레코드마다 로그 이벤트 1개를 받습니다. 다음은 첫 번째 이벤트이며, 공통 런타임 컨텍스트는 뺐습니다.
extra={...}의 원시 값은 메타데이터가 됩니다. 두 번째 이벤트에는 exceptionName KeyError와 exceptionMessage 'seats'가 있습니다. 트레이스백 전체 텍스트를 보내려면 include_exception_text=True로 핸들러를 만드세요.
6

로그 다시 읽기

일치하는 결과가 나오면 LogBrew가 로그를 저장한 것입니다. CI나 코딩 에이전트에서 읽으려면 프로젝트 읽기 키를 사용하세요. 설정 확인을 참고하세요.

LogBrew로 보낼 레코드 선택하기

레코드를 덜 보내려면 핸들러에 별도 레벨을 지정하세요. 콘솔은 여전히 INFO 이상을 받습니다.
Python 레벨은 LogBrew 레벨로 바뀝니다. 원래 레벨 이름과 숫자는 메타데이터에 남습니다.

Python 크래시를 이슈로 보고하기

install_process_error_capture(client)는 스크립트, 워커, 시작 코드, 스레드에서 잡히지 않은 예외를 보고합니다. 크래시 하나는 이슈 1개가 되며, 예외 타입, 메시지, 스택 프레임, 예외 체인의 원인을 담습니다. Python은 이전과 같이 트레이스백을 출력하고 종료합니다. 이 파일을 startup.py로 저장하고 실행하세요.
LogBrew는 제목이 FileNotFoundError, 레벨이 critical, 메커니즘이 python.excepthook인 이슈를 받습니다. 프레임에는 파일 이름, 줄, 함수가 있지만 전체 경로는 없습니다. 스레드에서 난 크래시의 레벨은 error입니다. Python이 종료되기 전에 SDK는 전송을 최대 2초 기다립니다.
이슈에는 예외 메시지가 포함됩니다. 예외 메시지나 로그 메시지에 자격 증명이나 개인정보를 넣지 마세요. 로그 마스킹을 참고하세요.

문제 해결

웹 앱은 Flask 로깅을 참고하세요. 로그 형식을 고르려면 구조화된 로깅을 참고하세요. 다른 런타임은 SDK 연동을 참고하세요.