logging — 파이썬 로깅 기능

logging — 파이썬 로깅 기능

logging 모듈은 애플리케이션과 라이브러리를 위한 유연한 이벤트 로깅 시스템을 구현하는 함수와 클래스를 정의해요. 로깅 API를 표준 라이브러리 모듈로 제공하는 핵심 이점은 모든 파이썬 모듈이 로깅에 참여할 수 있다는 것이에요. 따라서 애플리케이션 로그에 자체 메시지를 제3자 모듈의 메시지와 통합해 포함할 수 있어요.

이 문서 페이지는 API 참조 정보이며, 튜토리얼과 고급 주제는 기본 튜토리얼, 고급 튜토리얼, 로깅 쿡북을 참고하세요.

전형적인 사용 예시:

# myapp.py
import logging
import mylib
logger = logging.getLogger(__name__)
def main():
    logging.basicConfig(filename='myapp.log', level=logging.INFO)
    logger.info('Started')
    mylib.do_something()
    logger.info('Finished')
if __name__ == '__main__':
    main()

이 idiomatic 사용의 핵심 특징은 대부분의 코드가 getLogger(__name__)로 모듈 수준 로거를 단순히 만들고 그 로거로 필요한 로깅을 하는 것이라는 점이에요. 모듈 수준 로거에 기록된 메시지는 더 높은 수준 모듈의 로거 핸들러로 전달되며, 최고 수준인 루트 로거까지 전달돼요. 이 접근 방식을 계층적 로깅(hierarchical logging)이라 불러요.

로깅이 유용하려면 각 로거의 수준과 대상을 설정하는 방식으로 구성되어야 해요. 대부분의 경우 위 예시처럼 루트 로거만 구성하면 돼요. basicConfig()는 많은 사용 사례를 처리하는 루트 로거를 설정하는 빠른 방법을 제공해요.

출처: Python documentation

본문

Logger 객체

로거는 애플리케이션 코드가 직접 사용하는 인터페이스를 노출해요. 로거는 절대 직접 인스턴스화하면 안 되고 항상 모듈 수준 함수 logging.getLogger(name)을 통해 만들어야 해요. 같은 이름으로 getLogger()를 여러 번 호출하면 항상 같은 Logger 객체에 대한 참조를 반환해요.

class logging.Logger — 주요 속성과 메서드:

  • name — 로거의 이름. 읽기 전용으로 취급.
  • level — setLevel() 메서드로 설정된 이 로거의 임계값.
  • parent — 이 로거의 부모 로거.
  • propagate — 참이면 이 로거에 기록된 이벤트가 상위(조상) 로거의 핸들러에 전달돼요.
  • handlers — 이 로거 인스턴스에 직접 연결된 핸들러 리스트.
  • disabled — 모든 이벤트 처리를 비활성화.

setLevel(level) — 이 로거의 임계값을 level로 설정해요. level보다 심각하지 않은 로깅 메시지는 무시돼요. 로거가 생성될 때 수준은 NOTSET으로 설정되며, 루트 로거는 WARNING 수준으로 생성돼요.

isEnabledFor(level) — 심각도 level의 메시지가 이 로거에 의해 처리될지 여부를 나타내요. getEffectiveLevel() — 이 로거의 유효 수준을 나타내요.

getChild(suffix) — suffix로 결정된 이 로거의 하위 로거를 반환해요. getChildren() — 이 로거의 직접적인 자식 로거 집합을 반환해요.

debug(msg, *args, **kwargs) — 이 로거에 수준 DEBUG의 메시지를 기록해요. info(), warning(), error(), critical()도 같은 패턴으로 특정 수준의 메시지를 기록해요. log(level, msg, ...)는 정수 수준으로 기록하며, exception(msg, ...)은 예외 정보를 추가해 ERROR 수준으로 기록해요. exc_info, stack_info, stacklevel, extra 키워드 인자를 검사해요.

addFilter(filter) / removeFilter(filter) — 필터 추가·제거. addHandler(hdlr) / removeHandler(hdlr) — 핸들러 추가·제거. hasHandlers() — 이 로거에 구성된 핸들러가 있는지 확인.

로깅 수준

수준 숫자 값 의미
logging.NOTSET 0 조상 로거를 참조해 유효 수준 결정
logging.DEBUG 10 상세 정보, 보통 문제 진단 중인 개발자에게만 관심
logging.INFO 20 일이 예상대로 진행되고 있음을 확인
logging.WARNING 30 예상치 못한 일이 발생했거나 가까운 미래에 문제가 발생할 수 있음을 표시
logging.ERROR 40 더 심각한 문제로 소프트웨어가 일부 기능을 수행하지 못함
logging.CRITICAL 50 프로그램 자체가 계속 실행되지 못할 수 있음을 나타내는 심각한 오류

Handler 객체

핸들러는 (로거가 만든) 로그 레코드를 적절한 대상으로 보내요. Handler는 직접 인스턴스화되지 않으며, 더 유용한 하위 클래스의 기반으로 작동해요.

class logging.Handler — 주요 메서드: __init__(level=NOTSET), createLock(), acquire()/release(), setLevel(level), setFormatter(fmt), addFilter(filter)/removeFilter(filter), flush(), close(), handle(record), format(record), emit(record)(하위 클래스 구현용).

Formatter 객체

class logging.Formatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None) — LogRecord를 사람이나 외부 시스템이 해석할 출력 문자열로 변환해요.

  • fmt — 로깅 출력 전체의 형식 문자열. 기본값은 '%(message)s'.
  • datefmt — 로깅 출력의 날짜/시간 부분 형식 문자열.
  • style — '%', '{', '$' 중 하나로 형식 문자열 병합 방식을 결정.

format(record) — 레코드의 속성 딕셔너리를 문자열 형식화 연산의 피연산자로 사용해 결과 문자열을 반환해요. formatTime(record, datefmt=None) — 형식화된 시간을 사용하려는 formatter가 format()에서 호출해야 하는 메서드. formatException(exc_info) — 지정된 예외 정보를 문자열로 형식화. formatStack(stack_info) — 지정된 스택 정보를 문자열로 형식화.

class logging.BufferingFormatter(linefmt=None) — 여러 레코드를 형식화하려 할 때 하위 분류에 적합한 기본 formatter 클래스예요.

Filter 객체

class logging.Filter(name='') — Handlers와 Loggers가 수준이 제공하는 것보다 더 정교한 필터링에 사용할 수 있어요. name이 지정되면 그 로거와 그 자식의 이벤트가 필터를 통과할 수 있게 해요. name이 빈 문자열이면 모든 이벤트를 허용해요.

LogRecord 객체

class logging.LogRecord(name, level, pathname, lineno, msg, args, exc_info, func=None, sinfo=None) — 로깅 중인 이벤트와 관련된 모든 정보를 포함해요. 주요 속성: name, level, pathname, lineno, msg, args, exc_info, func, sinfo. getMessage() — 사용자 제공 인자를 메시지와 병합한 후 이 LogRecord의 메시지를 반환해요.

LoggerAdapter 객체

class logging.LoggerAdapter(logger, extra=None, merge_extra=False) — 로깅 호출에 문맥 정보를 편리하게 전달하는 데 사용돼요. Logger의 debug(), info(), warning(), error(), exception(), critical(), log(), isEnabledFor(), getEffectiveLevel(), setLevel(), hasHandlers() 메서드를 지원해요.

스레드 안전성

logging 모듈은 클라이언트가 특별한 작업을 할 필요 없이 스레드 안전하도록 설계됐어요. 모듈의 공유 데이터 접근을 직렬화하는 잠금 하나와, 각 핸들러가 기반 I/O 접근을 직렬화하는 잠금을 만드는 방식으로 달성돼요.

모듈 수준 함수

  • logging.getLogger(name=None) — 지정된 이름의 로거 또는 이름이 None이면 계층의 루트 로거를 반환해요.
  • logging.basicConfig(**kwargs) — 기본 Formatter를 가진 StreamHandler를 만들어 루트 로거에 추가해 로깅 시스템을 기본 구성해요. filename, filemode, format, datefmt, style, level, stream, handlers, force, encoding, errors 키워드 인자를 지원해요.
  • logging.debug(...), info(...), warning(...), error(...), critical(...) — 루트 로거에서 해당 수준으로 메시지를 기록하는 편의 함수.
  • logging.disable(level=CRITICAL) — 모든 로거에 대해 우선하는 재정의 수준을 제공해요.
  • logging.addLevelName(level, levelName) — 숫자 수준을 텍스트 표현에 연결.
  • logging.shutdown() — 모든 핸들러를 flush하고 닫아 순서대로 종료.
  • logging.setLoggerClass(klass), logging.setLogRecordFactory(factory) — 사용자 지정 로거/레코드 팩토리 설정.
  • logging.captureWarnings(capture) — warnings 모듈의 경고 캡처를 켜고 끄는 함수.

모듈 수준 속성

logging.lastResort — 로깅 구성이 없는 상태에 WARNING 수준으로 sys.stderr에 쓰는, “마지막 수단 핸들러”. logging.raiseExceptions — 처리 중 예외를 전파할지 여부. 기본값 True.

참고

  • 모듈 logging.config — 로깅 모듈의 구성 API.
  • 모듈 logging.handlers — 로깅 모듈에 포함된 유용한 핸들러.
  • PEP 282 — 파이썬 표준 라이브러리 포함을 제안한 문서.

더 알아보기 (Learn more)