logging --- 파이썬 로깅 시설

소스 코드: Lib/logging/__init__.py

Important

이 페이지는 API 레퍼런스 정보를 담고 있습니다. 자습서 정보 및 고급 주제에 대한 설명은 다음을 참조하십시오.

• 기초 자습서

• 고급 자습서

• 로깅 요리책

---

이 모듈은 응용 프로그램과 라이브러리를 위한 유연한 이벤트 로깅 시스템을 구현하는 함수와 클래스를 정의합니다.

표준 라이브러리 모듈로 로깅 API를 제공하는 것의 주요 이점은, 모든 파이썬 모듈이 로깅에 참여할 수 있어서, 응용 프로그램 로그에 여러분 자신의 메시지를 제삼자 모듈의 메시지와 통합할 수 있다는 것입니다.

이 모듈은 많은 기능과 유연성을 제공합니다. 로깅에 익숙하지 않다면, 감을 잡는 가장 좋은 방법은 자습서를 보는 것입니다 (오른쪽 링크를 참조하세요).

모듈에 의해 정의된 기본 클래스와 그 기능은 다음과 같습니다.

• 로거는 응용 프로그램 코드가 직접 사용하는 인터페이스를 노출합니다.

• 처리기는 (로거가 만든) 로그 레코드를 적절한 목적지로 보냅니다.

• 필터는 출력할 로그 레코드를 결정하기 위한 더 세분된 기능을 제공합니다.

• 포매터는 최종 출력에서 로그 레코드의 배치를 지정합니다.

Logger 객체

로거에는 다음과 같은 어트리뷰트와 메서드가 있습니다. 로거는 결코 직접 인스턴스를 만드는 일 없이, 항상 모듈 수준의 함수 logging.getLogger(name) 를 거치는 것에 주의하십시오. 같은 이름(name)으로 getLogger() 를 여러 번 호출해도 항상 같은 로거 객체에 대한 참조를 돌려줍니다.

name 은 잠재적으로 foo.bar.baz 와 같이 마침표로 구분된 계층적 값입니다 (하지만 그냥 간단한 foo 도 가능합니다). 계층적 목록에서 더 아래쪽에 있는 로거는 목록에서 상위에 있는 로거의 자식입니다. 예를 들어, 이름이 foo 인 로거가 주어지면, foo.bar, foo.bar.baz, 그리고 foo.bam 의 이름을 가진 로거는 모두 foo 의 자손입니다. 로거 이름 계층 구조는 파이썬 패키지 계층 구조와 비슷하며, logging.getLogger(__name__) 를 사용하여 모듈 단위로 로거를 구성하는 경우는 패키지 계층 구조와 같아집니다. 왜냐하면, 모듈에서, __name__ 은 파이썬 패키지 이름 공간의 모듈 이름이기 때문입니다.

flowdas

logging.getLogger(__name__) 에 관한 설명은 고급 로깅 자습서 를 참고하세요.

class logging.Logger

propagate

이 어트리뷰트가 참으로 평가되면, 이 로거에 로그 된 이벤트는 이 로거에 첨부된 처리기뿐 아니라 상위 계층 (조상) 로거의 처리기로 전달됩니다. 메시지는 조상 로거의 처리기에 직접 전달됩니다 - 조상 로거의 수준이나 필터는 고려하지 않습니다.

이 값이 거짓으로 평가되면, 로깅 메시지가 조상 로거의 처리기로 전달되지 않습니다.

생성자는 이 어트리뷰트를 True 로 설정합니다.

참고

로거 와 하나 이상의 조상에 처리기를 중복해서 연결하면, 같은 레코드를 여러 번 출력할 수 있습니다. 일반적으로, 하나 이상의 로거에 처리기를 붙일 필요는 없습니다. 로거 계층에서 가장 높은 적절한 로거에 처리기를 연결하면, propagate 설정이 True 로 남아있는 모든 자식 로거들이 로그 하는 모든 이벤트를 보게 됩니다. 일반적인 시나리오는 루트 로거에만 처리기를 연결하고, 전파가 나머지를 처리하도록 하는 것입니다.

setLevel(level)

이 로거의 수준 경계를 level 로 설정합니다. level 보다 덜 심각한 로깅 메시지는 무시됩니다; 심각도 level 이상의 로깅 메시지는, 처리기 수준이 level 보다 높은 심각도 수준으로 설정되지 않는 한, 이 로거에 연결된 처리기가 출력합니다.

로거가 만들어질 때, 수준은 NOTSET (로거가 루트 로거 일 때는 모든 메시지를 처리하게 하고, 로거가 루트 로거가 아니면 모든 메시지를 부모에게 위임하도록 합니다) 으로 설정됩니다. 루트 로거는 수준 WARNING으로 만들어짐에 유의하세요.

'부모에게 위임'이라는 말은, 로거 수준이 NOTSET 인 경우, NOTSET 이외의 수준을 갖는 조상이 발견되거나 루트에 도달할 때까지 조상 로거 체인을 탐색함을 의미합니다.

NOTSET 이외의 수준을 갖는 조상이 발견되면, 그 조상의 수준을 조상 검색이 시작된 로거의 유효 수준으로 간주하여, 로깅 이벤트를 처리할지를 결정하는 데 사용됩니다.

루트에 도달하면, 그리고 루트가 NOTSET 수준을 갖고 있으면, 모든 메시지가 처리됩니다. 그렇지 않으면 루트 수준이 유효 수준으로 사용됩니다.

수준의 목록은 로깅 수준를 보세요.

버전 3.2에서 변경: level 매개 변수는 이제 INFO와 같은 정수 상수 대신 'INFO'와 같은 수준의 문자열 표현을 허용합니다. 그러나 수준은 내부적으로 정수로 저장되며, getEffectiveLevel() 및 isEnabledFor()와 같은 메서드는 정수를 반환하거나 정수가 전달되기를 기대합니다.

isEnabledFor(level)

심각도 level 의 메시지가 이 로거에서 처리될지를 알려줍니다. 이 메서드는 먼저 logging.disable(level) 에 의해 설정된 모듈 수준의 수준을 확인한 다음, getEffectiveLevel()로 확인되는 로거의 유효 수준을 검사합니다.

getEffectiveLevel()

이 로거의 유효 수준을 알려줍니다. setLevel() 을 사용하여 NOTSET 이외의 값이 설정되면, 그 값이 반환됩니다. 그렇지 않으면, NOTSET 이외의 값이 발견될 때까지 루트를 향해 계층 구조를 탐색하고, 그 값이 반환됩니다. 반환되는 값은 정수이며, 일반적으로 logging.DEBUG, logging.INFO 등 중 하나입니다.

getChild(suffix)

접미사에 의해 결정되는, 이 로거의 자손 로거를 반환합니다. 그러므로, logging.getLogger('abc').getChild('def.ghi') 는 logging.getLogger('abc.def.ghi') 와 같은 로거를 반환합니다. 이것은 편의 메서드인데, 부모 로거가 리터럴 문자열이 아닌 이름(가령 __name__)을 사용하여 명명될 때 유용합니다.

버전 3.2에 추가.

debug(msg, *args, **kwargs)

이 로거에 수준 DEBUG 메시지를 로그 합니다. msg 는 메시지 포맷 문자열이고, args 는 문자열 포매팅 연산자를 사용하여 msg 에 병합되는 인자입니다. (이는 포맷 문자열에 키워드를 사용하고, 인자로 하나의 딕셔너리를 전달할 수 있음을 의미합니다.) args가 제공되지 않으면 msg에 % 포매팅 연산이 수행되지 않습니다.

kwargs 에서 검사되는 네 개의 키워드 인자가 있습니다: exc_info, stack_info, stacklevel 및 extra.

exc_info 가 거짓으로 평가되지 않으면, 로깅 메시지에 예외 정보가 추가됩니다. 예외 튜플 (sys.exc_info() 에 의해 반환되는 형식) 또는 예외 인스턴스가 제공되면 사용됩니다; 그렇지 않으면 예외 정보를 얻기 위해 sys.exc_info() 를 호출합니다.

두 번째 선택적 키워드 인자는 stack_info 이며, 기본값은 False 입니다. 참이면, 실제 로깅 호출을 포함하는 스택 정보가 로깅 메시지에 추가됩니다. 이것은 exc_info 를 지정할 때 표시되는 것과 같은 스택 정보가 아닙니다: 전자(stack_info)는 스택의 맨 아래에서 현재 스레드의 로깅 호출까지의 스택 프레임이며, 후자(exc_info)는 예외가 일어난 후에 예외 처리기를 찾으면서 되감은 스택 프레임에 대한 정보입니다.

exc_info 와는 독립적으로 stack_info 를 지정할 수 있습니다. 예를 들어 예외가 발생하지 않은 경우에도 코드의 특정 지점에 어떻게 도달했는지 보여줄 수 있습니다. 스택 프레임은 다음과 같은 헤더 행 다음에 인쇄됩니다:

Stack (most recent call last):

예외 프레임을 표시할 때 사용되는 Traceback (most recent call last): 을 흉내 내고 있습니다.

세 번째 선택적 키워드 인자는 stacklevel이며, 기본값은 1입니다. 1보다 크면, 로깅 이벤트용으로 만들어진 LogRecord에 설정된 줄 번호와 함수 이름을 계산할 때 해당 수의 스택 프레임을 건너뜁니다. 기록된 함수 이름, 파일명 및 줄 번호가 도우미 함수/메서드에 대한 정보가 아니라 호출자의 정보가 되도록, 로깅 도우미에서 사용할 수 있습니다. 이 매개 변수의 이름은 warnings 모듈에 있는 비슷한 것과 같도록 맞췄습니다.

네 번째 키워드 인자는 extra 로, 로깅 이벤트용으로 만들어진 LogRecord의 __dict__ 를 사용자 정의 어트리뷰트로 채우는 데 사용되는 딕셔너리를 전달할 수 있습니다. 이러한 사용자 정의 어트리뷰트는 원하는 대로 사용할 수 있습니다. 예를 들어, 로그 메시지에 포함할 수 있습니다. 예를 들면:

FORMAT = '%(asctime)-15s %(clientip)s %(user)-8s %(message)s'
logging.basicConfig(format=FORMAT)
d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}
logger = logging.getLogger('tcpserver')
logger.warning('Protocol problem: %s', 'connection reset', extra=d)

는 이렇게 인쇄할 것입니다

2006-02-08 22:20:02,165 192.168.0.1 fbloggs  Protocol problem: connection reset

extra 에 전달된 딕셔너리의 키가, 로깅 시스템에서 사용하는 키와 충돌해서는 안 됩니다. (어떤 키가 로깅 시스템에 의해 사용되는지에 대한 더 많은 정보는 Formatter 문서를 보십시오.)

로그 된 메시지에서 이러한 어트리뷰트를 사용하려면 몇 가지 주의를 기울여야 합니다. 위의 예에서, 예를 들어, Formatter 에 설정한 포맷 문자열은 LogRecord의 어트리뷰트 딕셔너리에 'clientip' 과 'user' 가 있을 것으로 기대하고 있습니다. 이것들이 없는 경우 문자열 포매팅 예외가 발생하기 때문에 메시지가 기록되지 않습니다. 따라서 이 경우, 항상 이 키를 포함하는 extra 딕셔너리를 전달해야 합니다.

성가신 일입니다만, 이 기능은 여러 문맥에서 같은 코드가 실행되고 관심 있는 조건들(가령 원격 클라이언트 IP 주소와 인증된 사용자 이름)이 문맥에 따라 발생하는 다중 스레드 서버와 같은 특수한 상황을 위한 것입니다. 이런 상황에서는, 특수한 Formatter 가 특정한 Handler와 함께 사용될 가능성이 큽니다.

flowdas

로그에 문맥 정보를 추가하는 방법은 로그 출력에 문맥 정보 추가 에서 좀 더 자세히 설명합니다.

버전 3.2에서 변경: stack_info 매개 변수가 추가되었습니다.

버전 3.5에서 변경: exc_info 매개 변수는 이제 예외 인스턴스를 받아들입니다.

버전 3.8에서 변경: stacklevel 매개 변수가 추가되었습니다.

info(msg, *args, **kwargs)

이 로거에 수준 INFO 메시지를 로그 합니다. 인자는 debug()처럼 해석됩니다.

warning(msg, *args, **kwargs)

이 로거에 수준 WARNING 메시지를 로그 합니다. 인자는 debug()처럼 해석됩니다.

참고

기능적으로 warning 와 같은, 구식의 warn 메서드가 있습니다. warn 은 폐지되었으므로 사용하지 마십시오 - 대신 warning 을 사용하십시오.

error(msg, *args, **kwargs)

이 로거에 수준 ERROR 메시지를 로그 합니다. 인자는 debug()처럼 해석됩니다.

critical(msg, *args, **kwargs)

이 로거에 수준 CRITICAL 메시지를 로그 합니다. 인자는 debug()처럼 해석됩니다.

log(level, msg, *args, **kwargs)

이 로거에 정수 수준 level 로 메시지를 로그 합니다. 다른 인자는 debug()처럼 해석됩니다.

exception(msg, *args, **kwargs)

이 로거에 수준 ERROR 메시지를 로그 합니다. 인자는 debug()처럼 해석됩니다. 예외 정보가 로깅 메시지에 추가됩니다. 이 메서드는 예외 처리기에서만 호출해야 합니다.

addFilter(filter)

지정된 필터 filter 를 이 로거에 추가합니다.

removeFilter(filter)

이 로거에서 지정된 필터 filter 를 제거합니다.

filter(record)

이 로거의 필터를 레코드(record)에 적용하고 레코드가 처리 대상이면 True를 반환합니다. 필터 중 어느 하나가 거짓 값을 반환할 때까지 필터는 차례로 참조됩니다. 그중 아무것도 거짓 값을 반환하지 않으면 레코드가 처리됩니다 (처리기로 전달됩니다). 어느 하나가 거짓 값을 반환하면, 더 이상의 레코드 처리는 이루어지지 않습니다.

flowdas

이 메서드는 레코드가 처리될 대상인지를 확인만 할뿐 처리기로 전달하지는 않습니다.

addHandler(hdlr)

지정된 처리기 hdlr 를 이 로거에 추가합니다.

removeHandler(hdlr)

이 로거에서 지정된 처리기 hdlr 을 제거합니다.

findCaller(stack_info=False, stacklevel=1)

호출자의 소스 파일 이름과 행 번호를 찾습니다. 파일 이름, 행 번호, 함수 이름 및 스택 정보를 4-요소 튜플로 반환합니다. 스택 정보는 stack_info 가 True 가 아니면 None 으로 반환됩니다.

flowdas

이 메서드가 제공하는 4-튜플은 makeRecord() 메서드의 fn, lno, func, sinfo 매개 변수로 전달됩니다.

stacklevel 매개 변수는 debug()과 기타 API를 호출하는 코드에서 전달됩니다. 1보다 크면, 반환되는 값을 결정하기 전에 초과분만큼 스택 프레임을 건너뜁니다. 일반적으로 도무미/래퍼 코드에서 로깅 API를 호출할 때 유용한데, 이벤트 로그의 정보가 도우미/래퍼 코드가 아니라 호출자 코드를 참조하도록 합니다.

handle(record)

이 로거와 그 조상(거짓 값의 propagate 가 발견될 때까지)과 연관된 모든 처리기에 레코드를 전달하여 레코드를 처리합니다. 이 메서드는 로컬에서 만든 레코드뿐만 아니라 소켓에서 받아서 언피클된 레코드를 처리하는 데 사용됩니다. filter() 를 사용하여 로거 수준 필터링을 적용합니다.

flowdas

소켓을 통해 LogRecord 인스턴스를 피클된 형태로 원격에서 전달받을 수 있습니다. 중앙 집중형 로그 서버를 구성할 때 사용되는 방법입니다. 이 경우 언피클해서 LogRecord 인스턴스를 만들게되는데, 이를 handle() 메서드로 처리하면됩니다. 예제 코드는 네트워크에서 로깅 이벤트 보내고 받기 를 참고하세요.

makeRecord(name, level, fn, lno, msg, args, exc_info, func=None, extra=None, sinfo=None)

이 메서드는 특수한 LogRecord 인스턴스를 만들기 위해 서브 클래스에서 재정의할 수 있는 팩토리 메서드입니다.

flowdas

이 팩토리 메서드보다는 보통 setLogRecordFactory() 를 사용합니다. 자세한 내용은 사용자 정의 LogRecord 를 참고하세요.

hasHandlers()

이 로거에 처리기가 구성되어 있는지 확인합니다. 이 로거의 처리기와 로거 계층의 부모를 찾습니다. 처리기가 발견되면 True 를 반환하고, 그렇지 않으면 False 를 반환합니다. 이 메서드는 'propagate' 어트리뷰트가 거짓으로 설정된 로거가 발견될 때 계층 구조 검색을 중지합니다 - 그 로거가 처리기가 있는지 검사하는 마지막 로거가 됩니다.

버전 3.2에 추가.

버전 3.7에서 변경: 이제 로거는 피클 되고 언피클 될 수 있습니다.

로깅 수준

로깅 수준의 숫자 값은 다음 표에 나와 있습니다. 여러분 자신의 수준을 정의하고, 미리 정의된 수준과 상대적인 특정 값을 갖도록 하려는 경우 필요합니다. 같은 숫자 값을 가진 수준을 정의하면 미리 정의된 값을 덮어씁니다; 미리 정의된 이름이 유실됩니다.

수준	숫자 값
CRITICAL	50
ERROR	40
WARNING	30
INFO	20
DEBUG	10
NOTSET	0

Handler 객체

처리기에는 다음과 같은 어트리뷰트와 메서드가 있습니다. Handler 는 절대로 직접 인스턴스로 만들어지지 않음에 주의하세요; 이 클래스는 더욱 유용한 서브 클래스의 베이스가 됩니다. 그러나, 서브 클래스의 __init__() 메서드는 Handler.__init__() 을 호출해야 합니다.

class logging.Handler

__init__(level=NOTSET)

수준을 설정하고, 필터 목록을 빈 리스트로 설정하고, I/O 메커니즘에 대한 액세스를 직렬화하기 위해 (createLock() 을 사용하여) 록을 생성함으로써 Handler 인스턴스를 초기화합니다.

createLock()

스레드 안전하지 않은 하부 I/O 기능에 대한 액세스를 직렬화하는 데 사용할 수 있는 스레드 록을 초기화합니다.

flowdas

기본적으로 threading.RLock 을 만듭니다. 재진입 가능한 록입니다.

acquire()

createLock() 로 생성된 스레드 록을 확보합니다.

release()

acquire()로 확보한 스레드 록을 반납합니다.

setLevel(level)

이 처리기의 수준 경계를 level 로 설정합니다. level 보다 덜 심각한 로깅 메시지는 무시됩니다. 처리기가 만들어질 때, 수준은 NOTSET (모든 메시지가 처리되게 합니다) 으로 설정됩니다.

수준의 목록은 로깅 수준를 보세요.

버전 3.2에서 변경: level 매개 변수는 이제 INFO와 같은 정수 상수 대신 'INFO'와 같은 수준 문자열 표현을 허용합니다.

setFormatter(fmt)

이 처리기의 Formatter를 fmt 로 설정합니다.

addFilter(filter)

지정된 필터 filter 를 이 처리기에 추가합니다.

removeFilter(filter)

이 처리기에서 지정된 필터 filter 를 제거합니다.

filter(record)

이 처리기의 필터를 레코드에 적용하고 레코드가 처리 대상이면 True를 반환합니다. 필터 중 어느 하나가 거짓 값을 반환할 때까지 필터는 차례로 확인됩니다. 그중 아무것도 거짓 값을 반환하지 않으면 레코드가 출력됩니다. 어느 하나가 거짓 값을 반환하면 처리기는 레코드를 출력하지 않습니다.

flowdas

이 메서드는 레코드가 처리될 대상인지를 확인만 할뿐 실제 처리하지는 않습니다.

flush()

모든 로그 출력이 플러시 되었음을 확실히 합니다. 이 버전은 아무것도 하지 않으며, 서브 클래스에 의해 구현됩니다.

close()

처리기가 사용하는 자원을 정리합니다. 이 버전은 출력하지 않지만, shutdown() 이 호출 될 때 닫히는 처리기의 내부 목록에서 처리기를 제거합니다. 서브 클래스는 이것이 재정의된 close() 메서드에서 이 메서드를 호출해야 합니다.

handle(record)

처리기에 추가된 필터에 따라 조건부로, 지정된 로깅 레코드를 출력합니다. 레코드의 실제 출력을 I/O 스레드 록의 확보/해제로 둘러쌉니다.

handleError(record)

이 메서드는 emit() 호출 중에 예외가 발생할 때 처리기에서 호출됩니다. 모듈 수준 어트리뷰트 raiseExceptions 가 False 인 경우 예외는 조용히 무시됩니다. 이 동작은 대부분 로깅 시스템에서 원하는 방식입니다 - 대부분 사용자는 로깅 시스템 자체의 에러에 관심이 없고, 응용 프로그램 에러에 더 관심이 있습니다. 그러나 원하는 경우, 사용자 정의 처리기로 바꿀 수 있습니다. 지정된 레코드는 예외가 발생할 때 처리되고 있던 레코드입니다. (raiseExceptions 의 기본값은 True 입니다. 개발 중에 더 유용합니다).

flowdas

handleError() 를 호출하는 책임은 emit() 구현에 있습니다. handle() 은 handleError() 를 호출하지 않습니다.

format(record)

레코드를 포맷합니다 - 포매터가 설정된 경우 사용합니다. 그렇지 않으면 모듈의 기본 포매터를 사용합니다.

emit(record)

지정된 로깅 레코드를 실제로 로그 하는 데 필요한 작업을 수행합니다. 이 버전은 서브 클래스에 의해 구현될 것으로 보고 NotImplementedError를 발생시킵니다.

표준으로 포함된 처리기 목록은 logging.handlers 를 참조하십시오.

Formatter 객체

Formatter 객체는 다음과 같은 어트리뷰트와 메서드를 가지고 있습니다. 이들은 LogRecord 를 (보통) 사람이나 외부 시스템이 해석 할 수 있는 문자열로 변환하는 역할을 합니다. 베이스 Formatter 는 포매팅 문자열을 지정할 수 있게 합니다. 아무것도 지정하지 않으면, '%(message)s' 이 기본값으로 사용되는데, 단지 로깅 호출에서 제공된 메시지만 포함됩니다. 포맷된 출력에 추가 정보(가령 타임스탬프)를 넣으려면 계속 읽으십시오.

flowdas

어트리뷰트를 따로 명시하지 않아서 찾기 불편하지만, 본문에는 Formatter.converter, Formatter.default_time_format, Formatter.default_msec_format 이 정의되어 있습니다.

포매터는 LogRecord 어트리뷰트에 포함된 정보를 사용하는 포맷 문자열로 초기화될 수 있습니다 - 위에서 언급 한 기본값은 사용자의 메시지와 인자가 LogRecord 의 message 어트리뷰트로 미리 포맷된다는 사실을 활용합니다. 이 포맷 문자열은 표준 파이썬 %-스타일 매핑 키를 포함합니다. 문자열 포매팅에 대해서 더 많은 정보가 필요하면 printf 스타일 문자열 포매팅를 보세요.

LogRecord 에 있는 유용한 매핑 키는 LogRecord 어트리뷰트 섹션에 있습니다.

class logging.Formatter(fmt=None, datefmt=None, style='%', validate=True)

Formatter 클래스의 새로운 인스턴스를 반환합니다. 인스턴스는 전체 메시지의 포맷 문자열과 메시지의 날짜/시간 부분에 대한 포맷 문자열로 초기화됩니다. fmt 가 지정되지 않으면 '%(message)s' 가 사용됩니다. datefmt 가 지정되지 않으면 formatTime() 설명서에 기술된 포맷이 사용됩니다.

style 매개 변수는 '%', '{' 또는 '$' 중 하나일 수 있으며, 포맷 문자열이 데이터와 병합되는 방식을 결정합니다: %-포매팅, str.format() 또는 string.Template 중 하나를 사용합니다. 이는 Logger.debug에 전달된 실제 로그 메시지가 아닌, 포맷 문자열 fmt (예를 들어 '%(message)s'나 {message})에만 적용됩니다.; 로그 메시지에 {- 와 $-포매팅을 사용하는 방법에 대한 자세한 내용은 응용 프로그램 전체에서 특정 포맷 스타일 사용하기을 참조하십시오.

버전 3.2에서 변경: style 매개 변수가 추가되었습니다.

버전 3.8에서 변경: validate 매개 변수가 추가되었습니다. style과 fmt가 잘못되거나 일치하지 않으면 ValueError를 발생시킵니다. 예를 들어: logging.Formatter('%(asctime)s - %(message)s', style='{').

format(record)

레코드의 어트리뷰트 딕셔너리가 문자열 포매팅 연산의 피연산자로 사용됩니다. 결과 문자열을 반환합니다. 딕셔너리를 포맷하기 전에 몇 가지 준비 단계가 수행됩니다. 레코드의 message 어트리뷰트를 msg % args 를 사용하여 계산합니다. 포매팅 문자열에 '(asctime)' 이 들어 있으면, formatTime() 이 호출되어 이벤트 시간을 포매팅합니다. 예외 정보가 있는 경우, formatException() 을 사용하여 포매팅 되고 메시지에 덧붙입니다. 포맷된 예외 정보는 exc_text 어트리뷰트에 캐시 됩니다. 예외 정보를 피클 해서 네트워크를 통해 전송할 수 있으므로 유용합니다만, 예외 정보의 포매팅을 사용자 정의하는 Formatter 서브 클래스가 두 개 이상 있는 경우 주의해야 합니다. 이 경우, 한 포매터가 포매팅을 완료한 후 캐시 된 값을 지워서 그 이벤트를 처리하는 다음 포매터가 캐시 된 값을 사용하지 않고 새로 계산할 수 있도록 해야 합니다.

flowdas

exc_text 는 LogRecord 의 어트리뷰트입니다.

스택 정보가 있는 경우, 예외 정보 뒤에 덧붙입니다. 필요할 경우 formatStack() 을 사용하여 변환합니다.

formatTime(record, datefmt=None)

이 메서드는 포맷된 시간을 사용하려는 포매터에 의해 format()에서 호출되어야 합니다. 이 메서드는 특정 요구 사항을 제공하기 위해 포매터에서 재정의될 수 있지만, 기본 동작은 다음과 같습니다: datefmt(문자열)이 지정된 경우, time.strftime() 를 사용하여 레코드 생성 시간을 포매팅합니다. 그렇지 않으면 '%Y-%m-%d %H:%M:%S,uuu' 포맷이 사용됩니다. 여기서 uuu 부분은 밀리 초 값이고, 다른 문자들은 time.strftime() 설명서를 따릅니다. 이 포맷의 표현된 시간의 예는 2003-01-23 00:29:50,411 입니다. 결과 문자열이 반환됩니다.

이 함수는 사용자가 구성할 수 있는 함수를 사용하여 생성 시간을 튜플로 변환합니다. 기본적으로 time.localtime() 이 사용됩니다; 특정 포매터 인스턴스에서 이를 변경하려면, converter 어트리뷰트를 time.localtime() 또는 time.gmtime() 과 같은 서명을 가진 함수로 설정하십시오. 모든 포매터를 변경하려면, 예를 들어 모든 로깅 시간을 GMT로 표시하려면, Formatter 클래스의 converter 어트리뷰트를 설정하십시오.

버전 3.3에서 변경: 예전에는, 기본 포맷이 다음과 같이 하드 코딩되었습니다: 2010-09-06 22:38:15,292. 쉼표 앞에 있는 부분은 strptime 포맷 문자열('%Y-%m-%d %H:%M:%S')이며, 쉼표 뒤의 부분은 밀리 초 값입니다. strptime에 밀리 초 포맷 표시자가 없으므로, 밀리 초 값은 다른 포맷 문자열 '%s,%03d' 을 사용하여 추가됩니다 --- 이 두 포맷 문자열 모두 이 메서드에 하드 코드 되었습니다. 이 변경으로, 이 문자열들은 클래스 수준 어트리뷰트로 정의되었고, 원하는 경우 인스턴스 수준에서 재정의할 수 있습니다. 어트리뷰트 이름은 default_time_format(strptime 포맷 문자열)과 default_msec_format(밀리 초 값 추가용)입니다.

버전 3.9에서 변경: default_msec_format은 None일 수 있습니다.

formatException(exc_info)

지정된 예외 정보(sys.exc_info() 에 의해 반환되는 표준 예외 튜플)를 문자열로 포맷합니다. 이 기본 구현은 traceback.print_exception()을 사용합니다. 결과 문자열이 반환됩니다.

formatStack(stack_info)

지정된 스택 정보(traceback.print_stack() 에 의해 반환된 문자열이지만 마지막 줄 바꿈이 제거됩니다)을 문자열로 포맷합니다. 이 기본 구현은 입력 값을 그대로 반환합니다.

flowdas

본문에는 BufferingFormatter 가 빠져있습니다. 여기에 간단한 설명을 붙입니다.

class logging.BufferingFormatter(linefmt=None)

여러 레코드를 포맷하는데 적합한 포매터.

linefmt 는 개별 레코드를 포맷하는데 사용될 포매터를 지정합니다. 지정하지 않으면 기본 포매터(Formatter)가 사용됩니다.

format(records)

지정된 레코드들을 포맷하고 그 결과를 문자열로 반환합니다.

formatFooter(records)

지정된 레코드들의 바닥글 문자열을 반환합니다. 기본 구현은 빈 문자열을 돌려줍니다.

formatHeader(records)

지정된 레코드들의 머릿글 문자열을 반환합니다. 기본 구현은 빈 문자열을 돌려줍니다.

Filter 객체

Filter 는 수준을 통해 제공되는 것보다 더 정교한 필터링을 위해 Handler 와 Logger 에 의해 사용될 수 있습니다. 베이스 필터 클래스는 로거 계층 구조의 특정 지점 아래에 있는 이벤트만 허용합니다. 예를 들어 'A.B'로 초기화된 필터는, 로거 'A.B', 'A.B.C', 'A.B.C.D', 'A.B.D' 등이 로그 한 이벤트를 허용하지만, 'A.BB', 'B.A.B' 등은 허용하지 않습니다. 빈 문자열을 사용하면 모든 이벤트를 통과시킵니다.

class logging.Filter(name='')

Filter 클래스의 인스턴스를 반환합니다. name 을 제공하면, 필터를 통과하도록 허용할 로거(그 자식들도 포함합니다)의 이름을 지정합니다. name 이 빈 문자열이면, 모든 이벤트를 허용합니다.

filter(record)

지정된 레코드가 로그 됩니까? 아니라면 0을 반환하고, 그렇다면 0이 아닌 값을 반환합니다. 적절하다고 판단되면, 이 메서드는 해당 레코드를 수정할 수 있습니다.

flowdas

필터가 레코드를 수정할 수 있도록 허용하기 때문에, 필터는 레코드에 문맥 정보를 주입하는데 사용될 수 있습니다.

처리기에 첨부된 필터는 이벤트를 처리기가 출력하기 전에 호출되는 반면, 로거에 첨부된 필터는 이벤트가 로깅될 때마다 (debug(), info() 등) 처리기로 이벤트를 보내기 전에 호출됩니다. 이는 자손 로거가 만든 이벤트들은, 같은 필터가 자손들에게도 적용되지 않는 한, 로거의 필터 설정으로 필터링 되지 않는다는 것을 뜻합니다.

flowdas

조상 로거로의 이벤트 확산은 로거에의한 필터링이 완료된 후에 이루어집니다. 확산될 때 이벤트는 조상 로거의 처리기들로 전달될 뿐, 조상 로거의 필터를 거치지는 않는다는 뜻입니다.

실제로 Filter 의 서브 클래스를 만들 필요는 없습니다: 같은 의미가 있는 filter 메서드를 가진 인스턴스는 무엇이건 전달할 수 있습니다.

버전 3.2에서 변경: 특수한 Filter 클래스를 만들거나 filter 메서드를 가진 다른 클래스를 사용할 필요가 없습니다: 함수(또는 다른 콜러블)를 필터로 사용할 수 있습니다. 필터링 로직은 필터 객체가 filter 어트리뷰트를 가졌는지 확인합니다: 만약 있다면 Filter 라고 가정하고 filter() 메서드를 호출합니다. 그렇지 않으면 콜러블이라고 가정하고 레코드를 단일 매개 변수로 호출합니다. 반환된 값은 filter() 가 반환하는 값과 같은 의미를 지녀야 합니다.

필터는 수준보다 정교한 기준에 따라 레코드를 필터링하는 데 주로 사용되지만, 필터가 첨부되는 처리기나 로거에서 처리되는 모든 레코드를 볼 수 있습니다: 이 특성은, 특정 로거나 처리기가 얼마나 많은 레코드를 처리하는지 센다거나, 처리 중인 LogRecord에 어트리뷰트를 추가, 변경, 삭제하려고 할 때 유용합니다. 당연히, LogRecord를 변경하는 것은 주의를 필요로 하는 일이지만, 로그에 문맥 정보를 주입하는 것을 허용합니다 (문맥 정보 전달에 필터 사용하기를 보세요).

LogRecord 객체

LogRecord 인스턴스는 뭔가 로깅 될 때마다 Logger 에 의해 자동으로 생성되며, makeLogRecord()를 통해 수동으로 생성될 수 있습니다 (예를 들어, 네트워크에서 수신된 피클 된 이벤트의 경우).

class logging.LogRecord(name, level, pathname, lineno, msg, args, exc_info, func=None, sinfo=None)

로그 되는 이벤트와 관련된 모든 정보를 담고 있습니다.

주요 정보는 msg와 args 로 전달되며, msg % args 를 사용하여 병합되어 레코드의 message 필드를 만듭니다.

매개변수

• name -- 이 LogRecord가 나타내는 이벤트를 로그 하는데 사용된 로거의 이름. 이 이름은 다른 (조상) 로거에 첨부된 처리기가 출력하더라도 항상 이 값을 갖습니다.

• level -- 로깅 이벤트의 숫자 수준 (DEBUG, INFO 등). 이 값은 LogRecord의 두 어트리뷰트로 변환됩니다: 숫자 값을 위한 levelno 와 해당 수준 이름을 위한 levelname.

• pathname -- 로깅 호출이 발생한 소스 파일의 전체 경로명.

• lineno -- 로깅 호출이 발생한 소스 파일의 행 번호.

• msg -- 이벤트 설명 메시지. 변수 데이터를 위한 자리 표시자가 있는 포맷 문자열일 수 있습니다.

• args -- 이벤트 설명을 얻기 위해 msg 인자에 병합할 변수 데이터.

• exc_info -- 현재의 예외 정보를 가지는 예외 튜플. 예외 정보가 없는 경우는 None 입니다.

• func -- 로깅 호출을 호출한 함수 또는 메서드의 이름.

• sinfo -- 현재 스레드에서 스택의 바닥부터 로깅 호출까지의 스택 정보를 나타내는 텍스트 문자열.

getMessage()

사용자가 제공 한 인자를 메시지와 병합한 후, 이 LogRecord 인스턴스에 대한 메시지를 반환합니다. 로깅 호출에 제공된 사용자 제공 메시지 인자가 문자열이 아닌 경우, str() 이 호출되어 문자열로 변환됩니다. 이렇게 해서 사용자 정의 클래스를 메시지로 사용할 수 있도록 하는데, 그 클래스의 __str__ 메서드는 사용할 실제 포맷 문자열을 반환 할 수 있습니다.

버전 3.2에서 변경: 레코드를 생성하는 데 사용되는 팩토리를 제공함으로써, LogRecord의 생성을 더 구성할 수 있게 만들었습니다. 팩토리는 getLogRecordFactory()와 setLogRecordFactory() (팩토리의 서명은 이곳을 참조하십시오) 를 사용하여 설정할 수 있습니다.

이 기능은 LogRecord 생성 시에 여러분 자신의 값을 주입하는데 사용할 수 있습니다. 다음과 같은 패턴을 사용할 수 있습니다:

old_factory = logging.getLogRecordFactory()

def record_factory(*args, **kwargs):
    record = old_factory(*args, **kwargs)
    record.custom_attribute = 0xdecafbad
    return record

logging.setLogRecordFactory(record_factory)

이 패턴을 사용하면 여러 팩토리를 체인으로 묶을 수 있으며, 서로의 어트리뷰트를 덮어쓰거나 위에 나열된 표준 어트리뷰트를 실수로 덮어쓰지 않는 한 놀랄만한 일이 일어나지는 않아야 합니다.

flowdas

이 패턴을 사용할 경우, 체인에 참여하는 팩토리의 순서는 임포트 순서에 영향을 받습니다. 임포트 순서를 정확히 제어할 수 없는 경우가 많기 때문에, 여러 팩토리가 조작하는 어트리뷰트들이 독립적이지 않다면 예상하지 못한 일이 일어날 수 있습니다.

LogRecord 어트리뷰트

LogRecord에는 많은 어트리뷰트가 있으며, 대부분 어트리뷰트는 생성자의 매개 변수에서 옵니다. (LogRecord 생성자 매개 변수와 LogRecord 어트리뷰트의 이름이 항상 정확하게 일치하는 것은 아닙니다.) 이러한 어트리뷰트를 사용하여 레코드의 데이터를 포맷 문자열로 병합 할 수 있습니다. 다음 표는 어트리뷰트 이름, 의미와 해당 자리 표시자를 %-스타일 포맷 문자열로 (알파벳 순서로) 나열합니다.

{}-포매팅(str.format())을 사용한다면, {attrname} 을 포맷 문자열의 자리 표시자로 사용할 수 있습니다. $-포매팅(string.Template)을 사용하고 있다면, ${attrname} 형식을 사용하십시오. 두 경우 모두, 물론, attrname 을 사용하려는 실제 어트리뷰트 이름으로 대체하십시오.

{}-포매팅의 경우, 어트리뷰트 이름 다음에 콜론(:)으로 구분하여 포매팅 플래그를 지정할 수 있습니다. 예를 들어, {msecs:03d} 자리 표시자는 밀리 초 값 4 를 004 로 포맷합니다. 사용할 수 있는 옵션에 대한 자세한 내용은 str.format() 설명서를 참조하십시오.

어트리뷰트 이름	포맷	설명
args	직접 포맷할 필요는 없습니다.	message 를 생성하기 위해 msg 에 병합되는 인자의 튜플. 또는 (인자가 하나뿐이고 딕셔너리일 때) 병합을 위해 값이 사용되는 딕셔너리.
asctime	%(asctime)s	사람이 읽을 수 있는, LogRecord 가 생성된 시간. 기본적으로 '2003-07-08 16:49:45,896' 형식입니다 (쉼표 뒤의 숫자는 밀리 초 부분입니다).
created	%(created)f	LogRecord 가 생성된 시간 (time.time() 이 반환하는 시간).
exc_info	직접 포맷할 필요는 없습니다.	예외 튜플 (sys.exc_info 에서 제공) 또는, 예외가 발생하지 않았다면, None.
filename	%(filename)s	pathname 의 파일명 부분.
funcName	%(funcName)s	로깅 호출을 포함하는 함수의 이름.
levelname	%(levelname)s	메시지의 텍스트 로깅 수준 ('DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL').
levelno	%(levelno)s	메시지의 숫자 로깅 수준 (DEBUG, INFO, WARNING, ERROR, CRITICAL).
lineno	%(lineno)d	로깅 호출이 일어난 소스 행 번호 (사용 가능한 경우).
message	%(message)s	로그 된 메시지. msg % args 로 계산됩니다. Formatter.format() 이 호출 될 때 설정됩니다.
module	%(module)s	모듈 (filename 의 이름 부분).
msecs	%(msecs)d	LogRecord 가 생성된 시간의 밀리 초 부분.
msg	직접 포맷할 필요는 없습니다.	원래 로깅 호출에서 전달된 포맷 문자열. args 와 병합하여 message 를 만듭니다. 또는 임의의 객체 (임의의 객체를 메시지로 사용하기 를 보세요).
name	%(name)s	로깅 호출에 사용된 로거의 이름.
pathname	%(pathname)s	로깅 호출이 일어난 소스 파일의 전체 경로명 (사용 가능한 경우).
process	%(process)d	프로세스 ID (사용 가능한 경우).
processName	%(processName)s	프로세스 이름 (사용 가능한 경우).
relativeCreated	%(relativeCreated)d	logging 모듈이 로드된 시간을 기준으로 LogRecord가 생성된 시간 (밀리 초).
stack_info	직접 포맷할 필요는 없습니다.	현재 스레드의 스택 바닥에서 이 레코드를 생성한 로깅 호출의 스택 프레임까지의 스택 프레임 정보 (사용 가능한 경우).
thread	%(thread)d	스레드 ID (사용 가능한 경우).
threadName	%(threadName)s	스레드 이름 (사용 가능한 경우).

flowdas

module 은 filename 에서 확장자를 제외한 부분을 뜻합니다.

processName 은 multiprocessing.Process.name 의 값입니다. logging.logProcesses = False 하면 그 이후로 process 는 제공되지 않습니다. logging.logMultiprocessing = False 하면 그 이후로 processName 은 제공되지 않습니다.

threadName 은 threading.Thread.name 의 값입니다. logging.logThreads = False 하면 그 이후로 thread 는 제공되지 않습니다.

버전 3.1에서 변경: processName 이 추가되었습니다.

LoggerAdapter 객체

LoggerAdapter 인스턴스는 문맥 정보를 로깅 호출에 편리하게 전달하는 데 사용됩니다. 사용 예는, 로그 출력에 문맥 정보 추가 섹션을 참조하십시오.

class logging.LoggerAdapter(logger, extra)

하부 Logger 인스턴스와 딕셔너리 류 객체로 초기화된 LoggerAdapter 의 인스턴스를 반환합니다.

process(msg, kwargs)

문맥 정보를 삽입하기 위해 로깅 호출에 전달된 메시지 와 키워드 인자를 수정합니다. 이 구현은 생성자에 extra 로 전달된 객체를 가져와서 'extra' 키를 사용하여 kwargs 에 추가합니다. 반환 값은 전달된 인자의 (수정된) 버전을 담은 (msg, kwargs) 튜플입니다.

위의 것에 더해, LoggerAdapter 는 다음과 같은 Logger 의 메서드를 지원합니다: debug(), info(), warning(), error(), exception(), critical(), log(), isEnabledFor(), getEffectiveLevel(), setLevel(), hasHandlers(). 이 메서드들은 Logger 에 있는 것과 똑같은 서명을 가지므로, 두 형의 인스턴스를 바꿔쓸 수 있습니다.

버전 3.2에서 변경: isEnabledFor(), getEffectiveLevel(), setLevel() 그리고 hasHandlers() 메서드가 LoggerAdapter 에 추가되었습니다. 이 메서드는 하부 로거로 위임합니다.

스레드 안전성

로깅 모듈은 클라이언트가 특별한 주의를 기울이지 않아도 스레드 안전하도록 만들어졌습니다. 이렇게 하려고 threading 록을 사용합니다; 모듈의 공유 데이터에 대한 액세스를 직렬화하는 록이 하나 있고, 각 처리기 또한 하부 I/O에 대한 액세스를 직렬화하는 록을 만듭니다.

signal 모듈을 사용하여 비동기 시그널 처리기를 구현한다면, 그 처리기 내에서는 logging을 사용할 수 없을 수도 있습니다. 이는 threading 모듈의 록 구현이 언제나 재진입할 수 있지는 않아서 그러한 시그널 처리기에서 호출할 수 없기 때문입니다.

flowdas

logging 모듈이 사용하고 있는 threading.RLock 이 시그널에 안전하지 않다는 내용입니다만, 이는 파이썬으로 구현된 버전에만 해당하는 내용입니다. 최근의 파이썬 버전에서 사용되는 threading.RLock 의 C 구현은 시그널에 안전합니다.

모듈 수준 함수

위에서 설명한 클래스 외에도 많은 모듈 수준 함수가 있습니다.

logging.getLogger(name=None)

지정된 이름(name)의 로거를 돌려주거나, name이 None 인 경우, 계층의 루트 로거인 로거를 돌려줍니다. 지정된 경우, name은 일반적으로 'a', 'a.b' 또는 'a.b.c.d' 와 같이 점으로 구분된 계층적 이름입니다. 이 이름의 선택은 전적으로 logging을 사용하는 개발자에게 달려 있습니다.

flowdas

이름을 자유롭게 선택할 수 있지만, 계층을 구분하는데 점(.)대신 다른 기호를 사용할 수는 없습니다.

같은 이름으로 이 함수를 여러 번 호출하면 모두 같은 로거 인스턴스를 반환합니다. 이것은 응용 프로그램의 다른 부분 간에 로거 인스턴스를 전달할 필요가 없다는 것을 뜻합니다.

logging.getLoggerClass()

표준 Logger 클래스를 반환하거나, setLoggerClass() 에 전달된 마지막 클래스를 반환합니다. 이 함수는 새 클래스 정의 내에서 호출하여, 사용자 정의 Logger 클래스를 설치할 때 다른 코드가 이미 적용한 사용자 정의를 취소하지 않도록 할 수 있습니다. 예를 들면:

class MyLogger(logging.getLoggerClass()):
    # ... 여기에서 동작을 재정의 합니다

logging.getLogRecordFactory()

LogRecord 를 생성하는 데 사용되는 콜러블을 반환합니다.

버전 3.2에 추가: 이 함수는 setLogRecordFactory()와 함께 제공되어, 개발자가 로깅 이벤트를 나타내는 LogRecord 가 만들어지는 방법을 더욱 잘 제어 할 수 있도록 합니다.

팩토리가 어떻게 호출되는지에 대한 더 자세한 정보는 setLogRecordFactory()를 보세요.

logging.debug(msg, *args, **kwargs)

루트 로거에 수준 DEBUG 메시지를 로그 합니다. msg 는 메시지 포맷 문자열이고, args 는 문자열 포매팅 연산자를 사용하여 msg 에 병합되는 인자입니다. (이는 포맷 문자열에 키워드를 사용하고, 인자로 하나의 딕셔너리를 전달할 수 있음을 의미합니다.)

kwargs 에서 검사되는 세 개의 키워드 인자가 있습니다: exc_info 가 거짓으로 평가되지 않으면, 로깅 메시지에 예외 정보가 추가됩니다. 예외 튜플(sys.exc_info() 에 의해 반환되는 형식)이나 예외 인스턴스가 제공되면 사용됩니다; 그렇지 않으면 예외 정보를 얻기 위해 sys.exc_info() 를 호출합니다.

flowdas

exc_info 로 예외 인스턴스를 전달할 수도 있습니다.

두 번째 선택적 키워드 인자는 stack_info 이며, 기본값은 False 입니다. 참이면, 실제 로깅 호출을 포함하는 스택 정보가 로깅 메시지에 추가됩니다. 이것은 exc_info 를 지정할 때 표시되는 것과 같은 스택 정보가 아닙니다: 전자(stack_info)는 스택의 맨 아래에서 현재 스레드의 로깅 호출까지의 스택 프레임이며, 후자(exc_info)는 예외가 일어난 후에 예외 처리기를 찾으면서 되감은 스택 프레임에 대한 정보입니다.

exc_info 와는 독립적으로 stack_info 를 지정할 수 있습니다. 예를 들어 예외가 발생하지 않은 경우에도 코드의 특정 지점에 어떻게 도달했는지 보여줄 수 있습니다. 스택 프레임은 다음과 같은 헤더 행 다음에 인쇄됩니다:

Stack (most recent call last):

예외 프레임을 표시할 때 사용되는 Traceback (most recent call last): 을 흉내 내고 있습니다.

세 번째 선택적 키워드 인자는 extra 로, 로깅 이벤트용으로 만들어진 LogRecord의 __dict__ 를 사용자 정의 어트리뷰트로 채우는 데 사용되는 딕셔너리를 전달할 수 있습니다. 이러한 사용자 정의 어트리뷰트는 원하는 대로 사용할 수 있습니다. 예를 들어, 로그 메시지에 포함할 수 있습니다. 예를 들면:

FORMAT = '%(asctime)-15s %(clientip)s %(user)-8s %(message)s'
logging.basicConfig(format=FORMAT)
d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}
logging.warning('Protocol problem: %s', 'connection reset', extra=d)

는 이렇게 인쇄할 것입니다:

2006-02-08 22:20:02,165 192.168.0.1 fbloggs  Protocol problem: connection reset

extra 에 전달된 딕셔너리의 키가, 로깅 시스템에서 사용하는 키와 충돌해서는 안 됩니다. (어떤 키가 로깅 시스템에 의해 사용되는지에 대한 더 많은 정보는 Formatter 문서를 보십시오.)

로그 된 메시지에서 이러한 어트리뷰트를 사용하려면 몇 가지 주의를 기울여야 합니다. 위의 예에서, 예를 들어, Formatter 에 설정한 포맷 문자열은 LogRecord의 어트리뷰트 딕셔너리에 'clientip' 과 'user' 가 있을 것으로 기대하고 있습니다. 이것들이 없는 경우 문자열 포매팅 예외가 발생하기 때문에 메시지가 기록되지 않습니다. 따라서 이 경우, 항상 이 키를 포함하는 extra 딕셔너리를 전달해야 합니다.

성가신 일입니다만, 이 기능은 여러 문맥에서 같은 코드가 실행되고 관심 있는 조건들(가령 원격 클라이언트 IP 주소와 인증된 사용자 이름)이 문맥에 따라 발생하는 다중 스레드 서버와 같은 특수한 상황을 위한 것입니다. 이런 상황에서는, 특수한 Formatter 가 특정한 Handler와 함께 사용될 가능성이 큽니다.

flowdas

로그에 문맥 정보를 추가하는 방법은 로그 출력에 문맥 정보 추가 에서 좀 더 자세히 설명합니다.

버전 3.2에서 변경: stack_info 매개 변수가 추가되었습니다.

logging.info(msg, *args, **kwargs)

루트 로거에 수준 INFO 메시지를 로그 합니다. 인자는 debug()처럼 해석됩니다.

logging.warning(msg, *args, **kwargs)

루트 로거에 수준 WARNING 메시지를 로그 합니다. 인자는 debug()처럼 해석됩니다.

참고

기능적으로 warning 와 같은, 구식의 warn 함수가 있습니다. warn 은 폐지되었으므로 사용하지 마십시오 - 대신 warning 을 사용하십시오.

logging.error(msg, *args, **kwargs)

루트 로거에 수준 ERROR 메시지를 로그 합니다. 인자는 debug()처럼 해석됩니다.

logging.critical(msg, *args, **kwargs)

루트 로거에 수준 CRITICAL 메시지를 로그 합니다. 인자는 debug()처럼 해석됩니다.

logging.exception(msg, *args, **kwargs)

루트 로거에 수준 ERROR 메시지를 로그 합니다. 인자는 debug()처럼 해석됩니다. 예외 정보가 로깅 메시지에 추가됩니다. 이 메서드는 예외 처리기에서만 호출해야 합니다.

logging.log(level, msg, *args, **kwargs)

루트 로거에 수준 level 의 메시지를 로그 합니다. 다른 인자는 debug()처럼 해석됩니다.

참고

위의 루트 로거에 위임하는 모듈 수준 편리 함수는 적어도 하나의 처리기를 사용할 수 있도록 basicConfig()를 호출합니다. 이 때문에, 스레드가 시작되기 전에 적어도 하나의 처리기가 루트 로거에 추가되지 않는 한, 2.7.1 및 3.2 이전의 파이썬 버전에서는 스레드에서 이 함수들을 사용하지 않아야 합니다. 이전 버전의 파이썬에서는, basicConfig() 의 스레드 안전성 결함으로 인해 (드물긴 하지만) 처리기가 루트 로거에 여러 번 추가될 수 있으며, 같은 이벤트가 여러 번 기록되는 것으로 이어질 수 있습니다.

logging.disable(level=CRITICAL)

모든 로거의 수준을 level 로 오버라이드합니다. 로거 자체 수준보다 우선합니다. 전체 응용 프로그램에서 로깅 출력을 일시적으로 억제해야 할 필요가 생길 때 이 함수가 유용합니다. 그 효과는 심각도 level 및 그 밑의 모든 로깅 호출을 무효화시킵니다. 따라서 INFO 값으로 호출하면 모든 INFO 및 DEBUG 이벤트는 삭제되지만, WARNING 이상의 심각도는 로거의 유효 수준에 따라 처리됩니다. logging.disable(logging.NOTSET) 이 호출되면, 이 오버라이딩 수준을 실질적으로 제거하므로, 로깅 출력은 다시 개별 로거의 유효 수준에 따르게 됩니다.

CRITICAL 보다 더 높은 사용자 정의 로깅 수준을 정의했다면 (권장하지 않습니다), level 매개 변수의 기본값에 의존할 수 없고 적절한 값을 명시적으로 제공해야 합니다.

버전 3.7에서 변경: level 매개 변수의 기본값은 수준 CRITICAL 입니다. 이 변경 사항에 대한 자세한 내용은 bpo-28524를 참조하십시오.

flowdas

이전 버전에서는 기본값이 없었습니다.

logging.addLevelName(level, levelName)

내부 딕셔너리에 수준 level 을 텍스트 levelName 과 연결합니다. 이 딕셔너리는 숫자 수준을 텍스트 표현으로 매핑하는데 (예를 들어, Formatter 가 메시지를 포매팅할 때) 사용됩니다. 이 기능을 사용해서 여러분 자신의 수준을 정의할 수도 있습니다. 제약 조건은, 사용되는 모든 수준이 이 함수를 사용하여 등록되어야 하고, 수준은 양의 정수이어야 하며, 심각도가 높아질수록 값이 커져야 한다는 것입니다.

참고

자신만의 수준을 정의할 생각이라면 사용자 정의 수준 섹션을 보십시오.

logging.getLevelName(level)

로깅 수준 level 의 텍스트 표현을 반환합니다.

level이 미리 정의된 수준 CRITICAL, ERROR, WARNING, INFO 또는 DEBUG 중 하나면 해당 문자열을 얻게 됩니다. addLevelName()을 사용하여 수준과 이름을 연관 지었다면, level 과 연결된 이름이 반환됩니다. 정의된 수준 중 하나에 해당하는 숫자 값이 전달되면, 해당 문자열 표현이 반환됩니다.

level 매개 변수는 'INFO' 와 같은 수준의 문자열 표현도 받아들입니다. 이럴 때, 이 함수는 해당 수준의 숫자 값을 반환합니다.

일치하는 숫자나 문자열 값이 전달되지 않으면, 문자열 'Level %s' % level 이 반환됩니다.

참고

수준은 (로깅 로직에서 비교해야 하므로) 내부적으로 정수입니다. 이 함수는 정수 수준과 %(levelname)s 포맷 지정자(LogRecord 어트리뷰트를 보세요)로 포맷된 로그 출력에 표시된 이름 간의 변환에 사용됩니다.

버전 3.4에서 변경: 3.4 이전의 파이썬 버전에서, 이 함수로 텍스트 수준을 전달할 수 있고, 해당 수준의 숫자 값을 반환합니다. 이 문서로 만들어지지 않은 동작은 실수로 간주하여, 파이썬 3.4에서 제거되었습니다. 하지만 이전 버전과의 호환성을 유지하기 위해 3.4.2에서 복원되었습니다.

logging.makeLogRecord(attrdict)

어트리뷰트가 attrdict 로 정의된 새로운 LogRecord 인스턴스를 만들어서 반환합니다. 이 함수는 피클 된 LogRecord 어트리뷰트 딕셔너리를 소켓으로 보내고, 수신 단에서 LogRecord 인스턴스로 재구성할 때 유용합니다.

logging.basicConfig(**kwargs)

기본 Formatter로 StreamHandler 를 생성하고 루트 로거에 추가하여 로깅 시스템의 기본 구성을 수행합니다. 함수 debug(), info(), warning(), error() 그리고 critical()은 루트 로거에 처리기가 정의되어 있지 않으면 자동으로 basicConfig()를 호출합니다.

이 함수는 루트 로거에 이미 처리기가 구성되어있는 경우, 키워드 인자 force가 True로 설정되지 않는 한, 아무 작업도 수행하지 않습니다.

참고

이 함수는 다른 스레드가 시작되기 전에 메인 스레드에서 호출되어야 합니다. 2.7.1과 3.2 이전의 파이썬 버전에서, 이 함수를 여러 스레드에서 호출하면, (드문 경우지만) 처리기가 두 번 이상 루트 로거에 추가되어, 로그에 메시지가 중복되는 것과 같은 예기치 않은 결과가 발생할 수 있습니다.

다음 키워드 인자가 지원됩니다.

포맷	설명
filename	StreamHandler 대신 지정된 파일명을 사용해 FileHandler를 만들도록 지정합니다.
filemode	filename 이 지정되었으면, 이 모드 로 파일을 엽니다. 기본값은 'a' 입니다.
format	처리기에 지정된 포맷 문자열을 사용합니다. 기본값은 콜론으로 구분된 어트리뷰트 levelname, name 및 message 입니다.
datefmt	time.strftime() 에서 허용하는 방식대로 지정된 날짜/시간 포맷을 사용합니다.
style	format 을 지정하면, 포맷 문자열에 이 스타일을 사용합니다. '%', '{', '$' 중 하나인데 각각 printf 스타일, str.format(), string.Template 에 대응됩니다. 기본값은 '%' 입니다.
level	루트 로거의 수준을 지정된 수준 으로 설정합니다.
stream	StreamHandler의 초기화에 지정된 스트림을 사용합니다. 이 인자는 filename 과 호환되지 않습니다 - 둘 다 있으면 ValueError 가 발생합니다.
handlers	지정된 경우, 루트 로거에 추가할 이미 만들어진 처리기의 이터러블이어야 합니다. 아직 포매터 세트가 없는 처리기에는 이 함수에서 만들어진 기본 포매터가 지정됩니다. 이 인자는 filename 또는 stream 과 호환되지 않습니다 - 둘 다 있으면 ValueError 가 발생합니다.
force	이 키워드 인자가 참으로 지정되면, 루트 로거에 첨부된 기존 처리기는 다른 인자에 지정된 대로 구성을 수행하기 전에 모두 제거되고 닫힙니다.
encoding	이 키워드 인자가 filename과 함께 지정되면, 그 값이 FileHandler가 만들어질 때 사용되어, 결국 출력 파일을 열 때 사용됩니다.
errors	이 키워드 인자가 filename과 함께 지정되면, 그 값이 FileHandler가 만들어질 때 사용되어, 결국 출력 파일을 열 때 사용됩니다. 지정하지 않으면, 'backslashreplace' 값이 사용됩니다. None이 지정되면, func:open에 그대로 전달되는데, 이는 'errors'를 전달한 것처럼 처리된다는 것에 유의하십시오.

버전 3.2에서 변경: style 인자가 추가되었습니다.

버전 3.3에서 변경: handlers 인자가 추가되었습니다. 호환되지 않는 인자(예를 들어, handlers 를 stream 이나 filename 과 함께 쓰거나, stream 을 filename 과 함께 쓰는 경우)가 있는 상황을 파악하기 위한 검사가 추가되었습니다.

버전 3.8에서 변경: force 인자가 추가되었습니다.

버전 3.9에서 변경: encoding과 errors 인자가 추가되었습니다.

logging.shutdown()

로깅 시스템에 모든 처리기를 플러시하고 닫아서 순차적인 종료를 수행하도록 알립니다. 응용 프로그램 종료 시 호출되어야 하고, 이 호출 후에는 로깅 시스템을 더는 사용하지 않아야 합니다.

logging 모듈이 임포트 될 때, 이 함수를 종료 처리기(atexit를 참조하십시오)로 등록하므로, 일반적으로 수동으로 수행할 필요가 없습니다.

logging.setLoggerClass(klass)

로거의 인스턴스를 만들 때 klass 클래스를 사용하도록 로깅 시스템에 지시합니다. 클래스는 __init__() 을 정의해야 하는데, name만 필수 인자로 요구하고, __init__() 는 Logger.__init__() 을 호출해야 합니다. 이 함수는 일반적으로 사용자 정의된 로거 동작이 필요한 응용 프로그램에서 로거의 인스턴스가 만들어지기 전에 호출됩니다. 이 호출 후, 다른 때와 마찬가지로, 서브 클래스를 사용하여 직접 로거의 인스턴스를 만들지 마십시오: 계속 logging.getLogger() API를 사용하여 로거를 얻으십시오.

flowdas

이 문서에 Logger.__init__() 의 서명이 나오지는 않지만, 이런식으로 하면됩니다:

class MyLogger(Logger):
    def __init__(self, name):
        super().__init__(name)

logging.setLogRecordFactory(factory)

LogRecord 를 만드는데 사용되는 콜러블을 설정합니다.

매개변수

factory -- 로그 레코드의 인스턴스를 만드는데 사용되는 팩토리 콜러블.

버전 3.2에 추가: 이 함수는 getLogRecordFactory()와 함께 제공되어, 개발자가 로깅 이벤트를 나타내는 LogRecord 가 만들어지는 방법을 더욱 잘 제어 할 수 있도록 합니다.

팩토리의 서명은 다음과 같습니다:

factory(name, level, fn, lno, msg, args, exc_info, func=None, sinfo=None, **kwargs)

name

로거 이름.

level

로깅 수준 (숫자).

fn

로깅 호출이 이루어진 파일의 전체 경로명.

lno

로깅 호출이 이루어진 파일의 행 번호.

msg

로깅 메시지

args

로깅 메시지에 대한 인자.

exc_info

예외 튜플 또는 None.

func

로깅 호출을 호출한 함수 또는 메서드의 이름

sinfo

traceback.print_stack() 가 제공하는 것과 같은 스택 트레이스백. 호출 계층 구조를 보여줍니다.

kwargs

추가 키워드 인자.

모듈 수준 어트리뷰트

logging.lastResort

"최후 수단 처리기" 는 이 어트리뷰트를 통해 제공됩니다. 이것은 WARNING 수준으로 sys.stderr 에 쓰는 StreamHandler 이고, 로깅 구성이 없을 때 로깅 이벤트를 처리하는 데 사용됩니다. 최종 결과는 sys.stderr 에 메시지를 출력하기만 하는 것입니다. 이것이 예전의 "no handlers could be found for logger XYZ" 라는 에러 메시지를 대체합니다. 어떤 이유로 이전 동작이 필요하면 lastResort 를 None 으로 설정할 수 있습니다.

버전 3.2에 추가.

warnings 모듈과의 통합

captureWarnings() 함수는 logging을 warnings 모듈과 통합하는데 사용될 수 있습니다.

logging.captureWarnings(capture)

이 함수는 logging 이 경고를 캡처하는 것을 켜고 끄는 데 사용됩니다.

capture 가 True 면, warnings 모듈에 의해 발행된 경고는 로깅 시스템으로 리디렉션됩니다. 특히, 경고는 warnings.formatwarning() 을 사용하여 포맷되고, 결과 문자열을 'py.warnings' 라는 이름의 로거에 심각도 WARNING으로 로그 합니다.

capture 가 False 면, 로깅 시스템으로의 경고 리디렉션은 멈추고, 경고는 원래 목적지(즉, captureWarnings(True) 가 호출되기 전에 적용되던 곳)로 리디렉션됩니다.

더 보기

모듈 logging.config

logging 모듈용 구성 API.

모듈 logging.handlers

logging 모듈에 포함된 유용한 처리기.

PEP 282 - 로깅 시스템

파이썬 표준 라이브러리에 포함하기 위해 이 기능을 설명한 제안.

원본 파이썬 로깅 패키지

logging 패키지의 원래 소스입니다. 이 사이트에서 제공되는 패키지 버전은 표준 라이브러리에 logging 패키지를 포함하지 않는 파이썬 1.5.2, 2.1.x 및 2.2.x에서 사용하기에 적합합니다.