logging — 이벤트 로깅

이 모듈은 표준 Python logging 패키지의 경량 부분집합을 MicroPython에 맞게 적용하여 제공합니다. 계층적으로 명명된 Logger 객체를 통한 레벨 기반 로깅, 소규모 핸들러 집합(StreamHandler, FileHandler), Formatter를 통한 printf 스타일 포매팅, 그리고 루트 로거에 대해 동작하는 함수와 동등한 모듈 수준 편의 함수를 지원합니다.

이 모듈은 익숙한 CPython API를 충분히 유사하게 따르므로 표준 라이브러리용으로 작성된 간단한 애플리케이션은 수정 없이 동작합니다. 필터, 다중 프로세스 잠금, 구성 파일 형식, 그리고 대부분의 핸들러 클래스는 제공되지 않습니다.

레벨 상수

logging.CRITICAL: int

숫자 값 50. 복구 불가능한 오류에 사용됩니다.

logging.ERROR: int

숫자 값 40. 심각한 문제에 사용됩니다.

logging.WARNING: int

숫자 값 30. 새로 구성된 루트 로거의 기본 레벨입니다.

logging.INFO: int

숫자 값 20. 확인 메시지에 사용됩니다.

logging.DEBUG: int

숫자 값 10. 세밀한 진단 출력에 사용됩니다.

logging.NOTSET: int

숫자 값 0. 레벨이 구성되지 않은 로거를 나타냅니다(이 경우 유효 레벨은 루트 로거 또는 WARNING에서 상속됩니다).

함수

logging.getLogger(name: str | None = None) → Logger

name으로 등록된 Logger를 반환하며, 처음 사용할 때 생성합니다. name이 None이면 루트 로거가 반환됩니다. name="root"로(또는 name을 지정하지 않고) 처음 호출하면 sys.stderr에 기록하는 기본 StreamHandler를 연결하기 위해 basicConfig가 암묵적으로 호출됩니다.

logging.log(level: int, msg: str, *args) → None

루트 로거에 level 수준으로 메시지를 기록합니다. args는 printf 스타일 % 포매팅을 사용하여 msg에 삽입됩니다. 단일 dict 인수는 매핑으로 사용됩니다.

logging.debug(msg: str, *args) → None

getLogger().debug(msg, *args)와 동등합니다.

logging.info(msg: str, *args) → None

getLogger().info(msg, *args)와 동등합니다.

logging.warning(msg: str, *args) → None

getLogger().warning(msg, *args)와 동등합니다.

logging.error(msg: str, *args) → None

getLogger().error(msg, *args)와 동등합니다.

logging.critical(msg: str, *args) → None

getLogger().critical(msg, *args)와 동등합니다.

logging.exception(msg: str, *args, exc_info: bool | BaseException = True) → None

getLogger().exception(msg, *args, exc_info=exc_info)와 동등합니다. 메시지를 ERROR 수준으로 기록하며, exc_info가 참이면 현재 활성 예외의 트레이스백을 추가로 포매팅합니다. exc_info가 그 자체로 BaseException이면 해당 예외의 트레이스백이 사용되고, 그렇지 않으면 가능한 경우 sys.exc_info()를 참조합니다.

logging.shutdown() → None

알려진 모든 로거에 연결된 모든 핸들러를 닫고 로거를 잊습니다. sys.atexit 후크가 사용 가능한 경우 자동으로 등록됩니다.

logging.addLevelName(level: int, name: str) → None

텍스트 name을 숫자 level과 연결하여 Formatter가 %(levelname)s를 통해 이를 렌더링할 수 있도록 합니다.

logging.basicConfig(filename: str | None = None, filemode: str = 'a', format: str | None = None, datefmt: str | None = None, level: int = WARNING, stream=None, encoding: str = 'UTF-8', force: bool = False) → None

루트 로거를 단일 핸들러로 구성합니다.

filename이 제공되면 filemode와 encoding을 사용하여 FileHandler가 생성됩니다. 그렇지 않으면 stream(기본값은 sys.stderr)에 기록하는 StreamHandler가 사용됩니다.

format과 datefmt는 새 Formatter에 전달됩니다.

level은 핸들러의 레벨과 루트 로거의 레벨을 모두 설정합니다.

루트 로거에 이미 핸들러가 있으면, force가 True가 아닌 한 이 함수는 아무 작업도 수행하지 않으며, 그러한 경우 기존 핸들러는 닫히고 교체됩니다.

클래스

class logging.Logger(name: str, level: int = NOTSET)

명명된 로거입니다. 동일한 이름에 대해 getLogger가 동일한 인스턴스를 반환할 수 있도록, 직접 생성하지 말고 getLogger를 통해 로거를 생성하십시오.

name: str

로거의 점으로 구분된 이름입니다.

level: int

구성된 숫자 레벨입니다. 0(NOTSET)은 “상속”을 의미합니다.

handlers: list

이 로거에 연결된 Handler 인스턴스 목록입니다. 비어 있으면 메시지는 루트 로거의 핸들러로 디스패치됩니다.

setLevel(level: int) → None

로거의 임계 레벨을 설정합니다.

isEnabledFor(level: int) → bool

level 수준의 메시지가 이 로거에서 처리될 경우 True를 반환합니다.

getEffectiveLevel() → int

다음 중 처음으로 0이 아닌 값을 반환합니다: 이 로거의 레벨, 루트 로거의 레벨, 또는 WARNING.

log(level: int, msg: str, *args) → None

msg를 level 수준으로 기록합니다. args는 % 연산자로 msg에 삽입됩니다. 첫 번째 위치 인수가 dict이면 매핑으로 사용됩니다.

debug(msg: str, *args) → None

msg를 DEBUG 수준으로 기록합니다.

info(msg: str, *args) → None

msg를 INFO 수준으로 기록합니다.

warning(msg: str, *args) → None

msg를 WARNING 수준으로 기록합니다.

error(msg: str, *args) → None

msg를 ERROR 수준으로 기록합니다.

critical(msg: str, *args) → None

msg를 CRITICAL 수준으로 기록합니다.

exception(msg: str, *args, exc_info: bool | BaseException = True) → None

msg를 ERROR 수준으로 기록하며, exc_info가 참이면 포매팅된 트레이스백을 추가합니다. exc_info가 BaseException 인스턴스이면 해당 예외의 트레이스백이 렌더링되고, 그렇지 않으면 sys.exc_info()를 통해 현재 활성 예외를 참조합니다.

addHandler(handler: Handler) → None

handler를 이 로거에 연결합니다.

hasHandlers() → bool

이 로거에 연결된 핸들러가 하나라도 있으면 True를 반환합니다.

class logging.Handler(level: int = NOTSET)

모든 핸들러의 기본 클래스입니다. 하위 클래스는 emit()을 구현합니다.

level: int

핸들러의 임계 레벨입니다.

formatter: 'Formatter | None'

활성 Formatter이거나 None입니다.

setLevel(level: int) → None

핸들러의 임계 레벨을 설정합니다.

setFormatter(formatter: Formatter) → None

formatter를 이 핸들러에 연결합니다.

format(record: LogRecord) → str

구성된 포매터를 사용하여 record를 렌더링합니다.

close() → None

핸들러가 보유한 리소스를 해제합니다. shutdown에 의해 호출되며, FileHandler가 닫힐 때도 호출됩니다.

class logging.StreamHandler(stream=None)

포매팅된 레코드 다음에 self.terminator(기본값 "\n")를 붙여 stream에 기록하는 핸들러입니다. stream의 기본값은 sys.stderr입니다.

stream

대상 스트림 객체입니다.

terminator: str

포매팅된 각 레코드 뒤에 추가되는 문자열입니다. 기본값은 "\n"입니다.

emit(record: LogRecord) → None

record의 레벨이 핸들러 임계값을 충족하면 stream에 기록합니다.

close() → None

기본 스트림에 flush 메서드가 있으면 해당 스트림을 플러시합니다.

class logging.FileHandler(filename: str, mode: str = 'a', encoding: str = 'UTF-8')

주어진 mode와 encoding으로 filename을 열고 포매팅된 레코드를 기록하는 StreamHandler 하위 클래스입니다. 기본 파일은 close() 시 닫힙니다.

class logging.Formatter(fmt: str | None = None, datefmt: str | None = None)

LogRecord 인스턴스를 문자열로 렌더링합니다.

fmt는 printf 스타일 템플릿입니다. 인식되는 키는 %(name)s, %(message)s, %(msecs)d, %(asctime)s, %(levelname)s입니다. 설정하지 않으면 기본값은 "%(levelname)s:%(name)s:%(message)s"입니다.

datefmt는 %(asctime)s를 렌더링하는 데 사용되는 time.strftime 템플릿입니다. 기본값은 "%Y-%m-%d %H:%M:%S"입니다.

usesTime() → bool

포맷 템플릿이 asctime을 참조하면 True를 반환합니다.

formatTime(datefmt: str, record: LogRecord) → str | None

time.strftime과 datefmt를 사용하여 record.ct를 포매팅합니다. time.strftime을 사용할 수 없는 플랫폼에서는 None을 반환합니다.

format(record: LogRecord) → str

record를 렌더링합니다. 템플릿이 asctime을 사용하면 먼저 formatTime()이 호출되어 record.asctime을 채웁니다.

class logging.LogRecord

Logger에서 핸들러로 전달되는 데이터의 컨테이너입니다. 인스턴스는 set()을 통해 채워지며, 로거 구현은 할당을 줄이기 위해 로거당 단일 레코드를 재사용합니다.

name: str

원본 로거의 이름입니다.

levelno: int

이 레코드의 숫자 레벨입니다.

levelname: str

텍스트 레벨 이름입니다.

message: str

완전히 포매팅된 로그 메시지입니다.

ct: float

time.time()이 반환한 생성 시각입니다.

msecs: int

ct의 밀리초 구성 요소입니다.

asctime: str | None

사람이 읽을 수 있는 타임스탬프이며, Formatter에 의해 지연 방식으로 채워집니다.

set(name: str, level: int, message: str) → None

주어진 값으로 레코드를 초기화하고 현재 시각을 캡처합니다.