15.7. ロギング— Pythonのロギング機能—Pythonドキュメント

提供：Dev Guides
< PythonPython/docs/2.7/library/logging
移動先:案内、検索

15.7。 ロギング —Pythonのロギング機能

重要

このページには、APIリファレンス情報が含まれています。 チュートリアル情報とより高度なトピックの説明については、を参照してください。

ソースコード： ：source： `Lib / logging / __ init __。py`


バージョン2.3の新機能。


このモジュールは、アプリケーションとライブラリの柔軟なイベントログシステムを実装する関数とクラスを定義します。

標準ライブラリモジュールによってログAPIが提供される主な利点は、すべてのPythonモジュールがログに参加できるため、アプリケーションログにサードパーティモジュールからのメッセージと統合された独自のメッセージを含めることができることです。

このモジュールは、多くの機能と柔軟性を提供します。 ロギングに慣れていない場合は、ロギングを理解するための最良の方法は、チュートリアルを参照することです（右側のリンクを参照）。

モジュールによって定義される基本的なクラスとその機能を以下に示します。

  • ロガーは、アプリケーションコードが直接使用するインターフェイスを公開します。
  • ハンドラーは、ログレコード（ロガーによって作成された）を適切な宛先に送信します。
  • フィルタは、出力するログレコードを決定するためのよりきめ細かい機能を提供します。
  • フォーマッタは、最終出力のログレコードのレイアウトを指定します。

15.7.1。 ロガーオブジェクト

ロガーには、次の属性とメソッドがあります。 ロガーが直接インスタンス化されることはありませんが、常にモジュールレベルの関数logging.getLogger(name)を介してインスタンス化されることに注意してください。 同じ名前で getLogger（）を複数回呼び出すと、常に同じLoggerオブジェクトへの参照が返されます。

nameは、foo.bar.bazのように、ピリオドで区切られた階層値である可能性があります（ただし、単純なfooなどの場合もあります）。 階層リストのさらに下にあるロガーは、リストの上位にあるロガーの子です。 たとえば、fooという名前のロガーがある場合、foo.bar、foo.bar.baz、およびfoo.bamという名前のロガーはすべて [の子孫です。 X139X]。 ロガー名の階層はPythonパッケージ階層に類似しており、推奨される構造logging.getLogger(__name__)を使用してモジュールごとにロガーを編成する場合は同じです。 これは、モジュールでは、__name__がPythonパッケージ名前空間内のモジュールの名前であるためです。

class logging.Logger
Logger.propagate

これがtrueと評価された場合、このロガーに記録されたイベントは、このロガーに接続されているハンドラーに加えて、より高いレベル（祖先）のロガーのハンドラーに渡されます。 メッセージは祖先ロガーのハンドラーに直接渡されます-問題の祖先ロガーのレベルもフィルターも考慮されません。

これがfalseと評価された場合、ロギングメッセージは祖先ロガーのハンドラーに渡されません。

コンストラクターは、この属性をTrueに設定します。

ノート

ハンドラーをロガーおよびの1つ以上の祖先にアタッチすると、同じレコードを複数回発行する場合があります。 一般に、ハンドラーを複数のロガーにアタッチする必要はありません。ロガー階層の最上位にある適切なロガーにハンドラーをアタッチするだけで、すべての子孫ロガーによってログに記録されたすべてのイベントが表示されます。設定はTrueのままにしておきます。 一般的なシナリオは、ハンドラーをルートロガーにのみアタッチし、残りは伝播に任せることです。

Logger.setLevel(level)

このロガーのしきい値をレベルに設定します。 レベルよりも重大度の低いログメッセージは無視されます。 ロガーが作成されると、レベルはNOTSETに設定されます（これにより、ロガーがルートロガーの場合はすべてのメッセージが処理され、ロガーが非ルートロガーの場合は親に委任されます）。 ルートロガーはレベルWARNINGで作成されることに注意してください。

「親への委任」という用語は、ロガーのレベルがNOTSETの場合、NOTSET以外のレベルの祖先が見つかるか、ルートに到達するまで、その祖先ロガーのチェーンがトラバースされることを意味します。

NOTSET以外のレベルで祖先が見つかった場合、その祖先のレベルは、祖先検索が開始されたロガーの有効レベルとして扱われ、ロギングイベントの処理方法を決定するために使用されます。

ルートに到達し、そのレベルがNOTSETの場合、すべてのメッセージが処理されます。 それ以外の場合は、ルートのレベルが有効レベルとして使用されます。

レベルのリストについては、ロギングレベルを参照してください。

Logger.isEnabledFor(lvl)
重大度 lvl のメッセージがこのロガーによって処理されるかどうかを示します。 このメソッドは、最初にlogging.disable(lvl)によって設定されたモジュールレベルのレベルをチェックし、次に getEffectiveLevel（）によって決定されたロガーの有効レベルをチェックします。
Logger.getEffectiveLevel()
このロガーの有効レベルを示します。 NOTSET以外の値が setLevel（）を使用して設定されている場合は、それが返されます。 それ以外の場合は、NOTSET以外の値が見つかるまで階層がルートに向かって走査され、その値が返されます。 返される値は整数で、通常はlogging.DEBUG、logging.INFOなどのいずれかです。
Logger.getChild(suffix)

接尾辞によって決定されるように、このロガーの子孫であるロガーを返します。 したがって、logging.getLogger('abc').getChild('def.ghi')は、logging.getLogger('abc.def.ghi')によって返されるのと同じロガーを返します。 これは便利な方法であり、親ロガーにegを使用して名前を付ける場合に便利です。 リテラル文字列ではなく__name__。

バージョン2.7の新機能。

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

このロガーにレベルDEBUGのメッセージを記録します。 msg はメッセージ形式の文字列であり、 args は、文字列形式演算子を使用して msg にマージされる引数です。 （これは、単一の辞書引数とともに、フォーマット文字列でキーワードを使用できることを意味することに注意してください。）

kwargs には、検査される2つのキーワード引数があります。 exc_info は、falseと評価されない場合、例外情報をログメッセージに追加します。 例外タプル（ sys.exc_info（）によって返される形式）が提供されている場合は、それが使用されます。 それ以外の場合は、 sys.exc_info（）が呼び出されて例外情報が取得されます。

2番目のキーワード引数は 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アドレスや認証済みなど）。上記の例では、ユーザー名）。 このような状況では、特殊なフォーマッターが特定のHandlerで使用される可能性があります。

Logger.info(msg, *args, **kwargs)
このロガーにレベルINFOのメッセージを記録します。 引数は debug（）と同様に解釈されます。
Logger.warning(msg, *args, **kwargs)
このロガーにレベルWARNINGのメッセージを記録します。 引数は debug（）と同様に解釈されます。
Logger.error(msg, *args, **kwargs)
このロガーにレベルERRORのメッセージを記録します。 引数は debug（）と同様に解釈されます。
Logger.critical(msg, *args, **kwargs)
このロガーにレベルCRITICALのメッセージを記録します。 引数は debug（）と同様に解釈されます。
Logger.log(lvl, msg, *args, **kwargs)
このロガーに整数レベル lvl のメッセージをログに記録します。 他の引数は debug（）と同様に解釈されます。
Logger.exception(msg, *args, **kwargs)
このロガーにレベルERRORのメッセージを記録します。 引数は debug（）と同様に解釈されますが、渡された exc_info は検査されません。 例外情報は常にログメッセージに追加されます。 このメソッドは、例外ハンドラーからのみ呼び出す必要があります。
Logger.addFilter(filter)
指定されたフィルターフィルターをこのロガーに追加します。
Logger.removeFilter(filter)
指定されたフィルターフィルターをこのロガーから削除します。
Logger.filter(record)
このロガーのフィルターをレコードに適用し、レコードを処理する場合は真の値を返します。 フィルタの1つが偽の値を返すまで、フィルタが順番に調べられます。 それらのいずれもfalse値を返さない場合、レコードは処理されます（ハンドラーに渡されます）。 false値を返すと、レコードのそれ以上の処理は発生しません。
Logger.addHandler(hdlr)
指定されたハンドラー hdlr をこのロガーに追加します。
Logger.removeHandler(hdlr)
指定されたハンドラー hdlr をこのロガーから削除します。
Logger.findCaller()

発信者のソースファイル名と行番号を検索します。 ファイル名、行番号、関数名を3要素のタプルとして返します。

バージョン2.4で変更：関数名が追加されました。 以前のバージョンでは、ファイル名と行番号は2要素のタプルとして返されていました。

Logger.handle(record)
このロガーとその祖先に関連付けられているすべてのハンドラーにレコードを渡すことによってレコードを処理します（ propagate の誤った値が見つかるまで）。 このメソッドは、ソケットから受信した選択されていないレコード、およびローカルで作成されたレコードに使用されます。 ロガーレベルのフィルタリングは、 filter（）を使用して適用されます。
Logger.makeRecord(name, lvl, fn, lno, msg, args, exc_info, func=None, extra=None)

これは、サブクラスでオーバーライドして、特殊な LogRecord インスタンスを作成できるファクトリメソッドです。

バージョン2.5で変更： func および extra が追加されました。


15.7.2。 ロギングレベル

ロギングレベルの数値を次の表に示します。 これらは、独自のレベルを定義し、事前定義されたレベルに関連する特定の値を持つ必要がある場合に主に役立ちます。 同じ数値でレベルを定義すると、事前定義された値が上書きされます。 事前定義された名前は失われます。

レベル 数値
CRITICAL 50
ERROR 40
WARNING 30
INFO 20
DEBUG 10
NOTSET 0


15.7.3。 ハンドラーオブジェクト

ハンドラーには、次の属性とメソッドがあります。 Handlerが直接インスタンス化されることはないことに注意してください。 このクラスは、より有用なサブクラスのベースとして機能します。 ただし、サブクラスの__init__()メソッドは、 Handler .__ init __（）を呼び出す必要があります。

Handler.__init__(level=NOTSET)
Handlerインスタンスを初期化するには、そのレベルを設定し、フィルターのリストを空のリストに設定し、I / Oメカニズムへのアクセスをシリアル化するためのロックを作成します（ createLock（）を使用）。
Handler.createLock()
スレッドセーフではない可能性のある基盤となるI / O機能へのアクセスをシリアル化するために使用できるスレッドロックを初期化します。
Handler.acquire()
createLock（）で作成されたスレッドロックを取得します。
Handler.release()
accept（）で取得したスレッドロックを解除します。
Handler.setLevel(level)

このハンドラーのしきい値をレベルに設定します。 レベルよりも重大度の低いログメッセージは無視されます。 ハンドラーが作成されると、レベルはNOTSETに設定されます（これにより、すべてのメッセージが処理されます）。

レベルのリストについては、ロギングレベルを参照してください。

Handler.setFormatter(fmt)
このハンドラーの Formatter を fmt に設定します。
Handler.addFilter(filter)
指定されたフィルターフィルターをこのハンドラーに追加します。
Handler.removeFilter(filter)
指定されたフィルターフィルターをこのハンドラーから削除します。
Handler.filter(record)
このハンドラーのフィルターをレコードに適用し、レコードを処理する場合は真の値を返します。 フィルタの1つが偽の値を返すまで、フィルタが順番に調べられます。 それらのいずれもfalse値を返さない場合、レコードが発行されます。 false値を返した場合、ハンドラーはレコードを発行しません。
Handler.flush()
すべてのログ出力がフラッシュされていることを確認します。 このバージョンは何もせず、サブクラスによって実装されることを目的としています。
Handler.close()
ハンドラーが使用するリソースを整理します。 このバージョンは出力を行いませんが、 shutdown（）が呼び出されたときに閉じられるハンドラーの内部リストからハンドラーを削除します。 サブクラスは、これがオーバーライドされた close（）メソッドから呼び出されるようにする必要があります。
Handler.handle(record)
ハンドラーに追加された可能性のあるフィルターに応じて、指定されたロギングレコードを条件付きで発行します。 I / Oスレッドロックの取得/解放で、レコードの実際の発行をラップします。
Handler.handleError(record)
このメソッドは、 emit（）呼び出し中に例外が発生したときにハンドラーから呼び出す必要があります。 モジュールレベルの属性raiseExceptionsがFalseの場合、例外は黙って無視されます。 これは、ロギングシステムに主に求められていることです。ほとんどのユーザーはロギングシステムのエラーを気にせず、アプリケーションエラーに関心があります。 ただし、必要に応じて、これをカスタムハンドラーに置き換えることができます。 指定されたレコードは、例外が発生したときに処理されていたレコードです。 （raiseExceptionsのデフォルト値はTrueです。これは、開発中により便利です）。
Handler.format(record)
レコードのフォーマットを実行します-フォーマッターが設定されている場合は、それを使用します。 それ以外の場合は、モジュールのデフォルトのフォーマッターを使用してください。
Handler.emit(record)
指定されたログレコードを実際にログに記録するために必要なことは何でもします。 このバージョンはサブクラスによって実装されることを目的としているため、NotImplementedErrorが発生します。

標準で含まれているハンドラーのリストについては、 logging.handlers を参照してください。


15.7.4。 フォーマッタオブジェクト

Formatter オブジェクトには、次の属性とメソッドがあります。 彼らは、 LogRecord を（通常）人間または外部システムのいずれかが解釈できる文字列に変換する責任があります。 ベースの Formatter を使用すると、フォーマット文字列を指定できます。 何も指定されていない場合は、デフォルト値の'%(message)s'が使用されます。これには、ロギング呼び出しのメッセージのみが含まれます。 フォーマットされた出力に追加の情報項目（タイムスタンプなど）を含めるには、読み続けてください。

フォーマッターは、 LogRecord 属性の知識を利用するフォーマット文字列で初期化できます。たとえば、ユーザーのメッセージと引数が[に事前にフォーマットされているという事実を利用した上記のデフォルト値などです。 X248X] LogRecord のメッセージ属性。 このフォーマット文字列には、標準のPython %-sスタイルマッピングキーが含まれています。 文字列フォーマットの詳細については、セクション文字列フォーマット操作を参照してください。

LogRecord の便利なマッピングキーは、 LogRecord属性のセクションに記載されています。

class logging.Formatter(fmt=None, datefmt=None)

Formatter クラスの新しいインスタンスを返します。 インスタンスは、メッセージ全体のフォーマット文字列と、メッセージの日付/時刻部分のフォーマット文字列で初期化されます。 fmt が指定されていない場合は、'%(message)s'が使用されます。 datefmt が指定されていない場合は、ISO8601日付形式が使用されます。

format(record)

レコードの属性ディクショナリは、文字列フォーマット操作のオペランドとして使用されます。 結果の文字列を返します。 辞書をフォーマットする前に、いくつかの準備手順が実行されます。 レコードの message 属性は、 msg ％ args を使用して計算されます。 フォーマット文字列に'(asctime)'が含まれている場合、 formatTime（）が呼び出されてイベント時間がフォーマットされます。 例外情報がある場合は、 formatException（）を使用してフォーマットされ、メッセージに追加されます。 フォーマットされた例外情報は、属性 exc_text にキャッシュされることに注意してください。 これは、例外情報をピクルスにしてネットワーク経由で送信できるため便利ですが、例外情報のフォーマットをカスタマイズする Formatter サブクラスが複数ある場合は注意が必要です。 この場合、フォーマッターがフォーマットを行った後にキャッシュされた値をクリアする必要があります。これにより、イベントを処理する次のフォーマッターはキャッシュされた値を使用せず、新たに再計算します。

formatTime(record, datefmt=None)

このメソッドは、 format（）から、フォーマットされた時間を利用したいフォーマッターによって呼び出される必要があります。 このメソッドは、特定の要件を提供するためにフォーマッターでオーバーライドできますが、基本的な動作は次のとおりです。 datefmt （文字列）が指定されている場合、 time.strftime（）[とともに使用されます。 X203X]レコードの作成時間をフォーマットします。 それ以外の場合は、ISO8601形式が使用されます。 結果の文字列が返されます。

この関数は、ユーザーが構成可能な関数を使用して、作成時間をタプルに変換します。 デフォルトでは、 time.localtime（）が使用されます。 特定のフォーマッタインスタンスに対してこれを変更するには、converter属性を time.localtime（）または time.gmtime（）と同じ署名を持つ関数に設定します。 すべてのフォーマッタで変更するには、たとえば、すべてのロギング時間をGMTで表示する場合は、Formatterクラスでconverter属性を設定します。

formatException(exc_info)

指定された例外情報（ sys.exc_info（）によって返される標準の例外タプル）を文字列としてフォーマットします。 このデフォルトの実装では、 traceback.print_exception（）を使用するだけです。 結果の文字列が返されます。


15.7.5。 オブジェクトをフィルタリングする

Filtersは、HandlersおよびLoggersで使用して、レベルで提供されるよりも高度なフィルタリングを行うことができます。 基本フィルタークラスは、ロガー階層の特定のポイントより下にあるイベントのみを許可します。 たとえば、「A.B」で初期化されたフィルターは、ロガー「A.B」、「ABC」、「ABCD」、「ABD」などによってログに記録されたイベントを許可します。 ただし、「A.BB」、「BAB」などではありません。 空の文字列で初期化すると、すべてのイベントが渡されます。

class logging.Filter(name=)
Filter クラスのインスタンスを返します。 name が指定されている場合、ロガーに名前を付けます。ロガーは、その子とともに、フィルターを介してイベントを許可されます。 name が空の文字列の場合、すべてのイベントを許可します。
filter(record)
指定されたレコードはログに記録されますか？ いいえの場合はゼロを返し、はいの場合はゼロ以外を返します。 適切と思われる場合は、この方法でレコードをインプレースで変更できます。

ハンドラーにアタッチされたフィルターは、ハンドラーによってイベントが発行される前に参照されますが、ロガーにアタッチされたフィルターは、イベントがログに記録されるたびに参照されることに注意してください（ debug（）、 info（）を使用）など）、ハンドラーにイベントを送信する前。 これは、子孫ロガーによって生成されたイベントは、フィルターがそれらの子孫ロガーにも適用されていない限り、ロガーのフィルター設定によってフィルター処理されないことを意味します。

実際にFilterをサブクラス化する必要はありません。同じセマンティクスを持つfilterメソッドを持つ任意のインスタンスを渡すことができます。

フィルタは主に、レベルよりも高度な基準に基づいてレコードをフィルタリングするために使用されますが、接続されているハンドラまたはロガーによって処理されるすべてのレコードを確認できます。これは、数を数えるなどの操作を行う場合に役立ちます。レコードは、特定のロガーまたはハンドラーによって処理されたか、処理中のLogRecordの属性を追加、変更、または削除しました。 明らかに、LogRecordの変更は注意して行う必要がありますが、ログにコンテキスト情報を挿入することはできます（フィルターを使用したコンテキスト情報の伝達を参照）。


15.7.6。 LogRecordオブジェクト

LogRecord インスタンスは、何かがログに記録されるたびに Logger によって自動的に作成され、 makeLogRecord（）を介して手動で作成できます（たとえば、受信したpickle化イベントから）ワイヤー上）。

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

ログに記録されるイベントに関連するすべての情報が含まれます。

一次情報はmsgとargsで渡され、msg % argsを使用して結合されてレコードのmessageフィールドが作成されます。

パラメーター

  • name –このLogRecordによって表されるイベントをログに記録するために使用されるロガーの名前。 この名前は、別の（祖先）ロガーに接続されたハンドラーによって発行される場合でも、常にこの値を持つことに注意してください。

  • level –ロギングイベントの数値レベル（DEBUG、INFOなどのいずれか）これはLogRecordの 2つの属性に変換されることに注意してください：levelno数値および対応するレベル名のlevelname。

  • pathname –ロギング呼び出しが行われたソースファイルのフルパス名。

  • lineno –ロギング呼び出しが行われたソースファイルの行番号。

  • msg –イベントの説明メッセージ。変数データのプレースホルダーを含むフォーマット文字列の場合があります。

  • args –イベントの説明を取得するために msg 引数にマージする変数データ。

  • exc_info –現在の例外情報を含む例外タプル。例外情報が利用できない場合はNone。

  • func –ロギング呼び出しが呼び出された関数またはメソッドの名前。

バージョン2.5で変更： func が追加されました。

getMessage()

ユーザー指定の引数をメッセージとマージした後、この LogRecord インスタンスのメッセージを返します。 ロギング呼び出しに対するユーザー指定のメッセージ引数が文字列でない場合は、 str（）が呼び出されて文字列に変換されます。 これにより、ユーザー定義クラスをメッセージとして使用できます。その__str__メソッドは、使用する実際のフォーマット文字列を返すことができます。


15.7.7。 LogRecord属性

LogRecordにはいくつかの属性があり、そのほとんどはコンストラクターへのパラメーターから派生しています。 （名前は、LogRecordコンストラクターパラメーターとLogRecord属性の間で常に正確に対応しているわけではないことに注意してください。）これらの属性を使用して、レコードのデータをフォーマット文字列にマージできます。 次の表に、属性名、その意味、および対応するプレースホルダーを%-sスタイル形式の文字列で（アルファベット順に）示します。

属性名 フォーマット 説明
引数 これを自分でフォーマットする必要はありません。 引数のタプルがmsgにマージされて、message、または値がマージに使用されるdict（引数が1つだけで、辞書である場合）が生成されます。
asctime %(asctime)s LogRecord が作成されたときの人間が読める時間。 デフォルトでは、これは「2003-07-08 16：49：45,896」の形式です（コンマの後の数字は時間のミリ秒部分です）。
作成した %(created)f LogRecord が作成された時刻（ time.time（）によって返される）。
exc_info これを自分でフォーマットする必要はありません。 例外タプル（àlasys.exc_info）、または例外が発生していない場合はNone。
ファイル名 %(filename)s pathnameのファイル名部分。
funcName %(funcName)s ロギング呼び出しを含む関数の名前。
レベル名 %(levelname)s メッセージのテキストログレベル（'DEBUG'、'INFO'、'WARNING'、'ERROR'、'CRITICAL'）。
levelno %(levelno)s メッセージの数値ログレベル（DEBUG、INFO、WARNING、ERROR、CRITICAL）。
lineno %(lineno)d ロギング呼び出しが発行されたソース行番号（使用可能な場合）。
モジュール %(module)s モジュール（filenameの名前部分）。
ミリ秒 %(msecs)d LogRecord が作成された時間のミリ秒部分。
メッセージ %(message)s ログに記録されたメッセージ。msg % argsとして計算されます。 これは、 Formatter.format（）が呼び出されたときに設定されます。
msg これを自分でフォーマットする必要はありません。 元のロギング呼び出しで渡されたフォーマット文字列。 argsとマージして、messageまたは任意のオブジェクトを生成します（メッセージとしての任意のオブジェクトの使用を参照）。
名前 %(name)s 通話の記録に使用されたロガーの名前。
パス名 %(pathname)s ロギング呼び出しが発行されたソースファイルのフルパス名（使用可能な場合）。
処理する %(process)d プロセスID（利用可能な場合）。
processName %(processName)s プロセス名（利用可能な場合）。
relatedCreated %(relativeCreated)d ロギングモジュールがロードされた時間に対する、LogRecordが作成されたミリ秒単位の時間。
糸 %(thread)d スレッドID（利用可能な場合）。
threadName %(threadName)s スレッド名（利用可能な場合）。

バージョン2.5で変更： funcName が追加されました。


バージョン2.6で変更： processName が追加されました。


15.7.8。 LoggerAdapterオブジェクト

LoggerAdapter インスタンスは、コンテキスト情報をロギング呼び出しに便利に渡すために使用されます。 使用例については、ログ出力へのコンテキスト情報の追加のセクションを参照してください。

バージョン2.6の新機能。


class logging.LoggerAdapter(logger, extra)
基になる Logger インスタンスとdictのようなオブジェクトで初期化された LoggerAdapter のインスタンスを返します。
process(msg, kwargs)
コンテキスト情報を挿入するために、ロギング呼び出しに渡されるメッセージおよび/またはキーワード引数を変更します。 この実装は、 extra として渡されたオブジェクトをコンストラクターに受け取り、キー 'extra'を使用して kwargs に追加します。 戻り値は（ msg 、 kwargs ）タプルであり、引数の（変更された可能性のある）バージョンが渡されます。

上記に加えて、 LoggerAdapter は、 Logger の次のメソッドをサポートします： debug（）、 info（）、警告（）、エラー（）、例外（）、クリティカル（）、ログ（）および isEnabledFor （）。 これらのメソッドは、 Logger の対応するメソッドと同じシグネチャを持っているため、これらの呼び出しで2つのタイプのインスタンスを交換可能に使用できます。

バージョン2.7で変更： isEnabledFor（）メソッドが LoggerAdapter に追加されました。 このメソッドは、基盤となるロガーに委任します。


15.7.9。 スレッドセーフ

ロギングモジュールは、クライアントが特別な作業を行う必要がなく、スレッドセーフであることを目的としています。 スレッドロックを使用してこれを実現します。 モジュールの共有データへのアクセスをシリアル化するためのロックが1つあり、各ハンドラーは、基盤となるI / Oへのアクセスをシリアル化するためのロックも作成します。

signal モジュールを使用して非同期シグナルハンドラーを実装している場合、そのようなハンドラー内からロギングを使用できない場合があります。 これは、 threading モジュールのロック実装が常に再入可能であるとは限らないため、そのようなシグナルハンドラーから呼び出すことができないためです。


15.7.10。 モジュールレベルの機能

上記のクラスに加えて、いくつかのモジュールレベルの関数があります。

logging.getLogger([name])

指定された名前のロガーを返すか、名前が指定されていない場合は、階層のルートロガーであるロガーを返します。 指定した場合、名前は通常、「a」、「ab」、「abcd」のようなドット区切りの階層名です。 これらの名前の選択は、ロギングを使用している開発者次第です。

指定された名前でこの関数を呼び出すと、同じロガーインスタンスが返されます。 これは、ロガーインスタンスをアプリケーションの異なる部分間で渡す必要がないことを意味します。

logging.getLoggerClass()

標準の Logger クラス、または setLoggerClass（）に渡された最後のクラスのいずれかを返します。 この関数は、カスタマイズされた Logger クラスをインストールしても、他のコードによってすでに適用されているカスタマイズが取り消されないようにするために、新しいクラス定義内から呼び出すことができます。 例えば：

class MyLogger(logging.getLoggerClass()):
    # ... override behaviour here
logging.debug(msg[, *args[, **kwargs]])

レベルDEBUGのメッセージをルートロガーに記録します。 msg はメッセージ形式の文字列であり、 args は、文字列形式演算子を使用して msg にマージされる引数です。 （これは、単一の辞書引数とともに、フォーマット文字列でキーワードを使用できることを意味することに注意してください。）

kwargs には、検査される2つのキーワード引数があります。 exc_info は、falseと評価されない場合、例外情報をログメッセージに追加します。 例外タプル（ sys.exc_info（）によって返される形式）が提供されている場合は、それが使用されます。 それ以外の場合は、 sys.exc_info（）が呼び出されて例外情報が取得されます。

他のオプションのキーワード引数は 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アドレスや認証済みなど）。上記の例では、ユーザー名）。 このような状況では、特殊なフォーマッターが特定のHandlerで使用される可能性があります。

バージョン2.5で変更： extra が追加されました。

logging.info(msg[, *args[, **kwargs]])
レベルINFOのメッセージをルートロガーに記録します。 引数は debug（）と同様に解釈されます。
logging.warning(msg[, *args[, **kwargs]])
レベルWARNINGのメッセージをルートロガーに記録します。 引数は debug（）と同様に解釈されます。
logging.error(msg[, *args[, **kwargs]])
レベルERRORのメッセージをルートロガーに記録します。 引数は debug（）と同様に解釈されます。
logging.critical(msg[, *args[, **kwargs]])
レベルCRITICALのメッセージをルートロガーに記録します。 引数は debug（）と同様に解釈されます。
logging.exception(msg[, *args[, **kwargs]])
レベルERRORのメッセージをルートロガーに記録します。 引数は debug（）と同様に解釈されますが、渡された exc_info は検査されません。 例外情報は常にログメッセージに追加されます。 この関数は、例外ハンドラーからのみ呼び出す必要があります。
logging.log(level, msg[, *args[, **kwargs]])

レベルレベルのメッセージをルートロガーに記録します。 他の引数は debug（）と同様に解釈されます。

ノート

ルートロガーに委任する上記のモジュールレベルの便利な関数は、 basicConfig（）を呼び出して、少なくとも1つのハンドラーが使用可能であることを確認します。 このため、少なくとも1つのハンドラーがの前にルートロガーに追加されていない限り、2.7.1および3.2より前のバージョンのPythonでは、スレッドで使用しないでください。スレッドが開始されます。 以前のバージョンのPythonでは、 basicConfig（）のスレッドセーフの欠点により、（まれな状況で）ハンドラーがルートロガーに複数回追加され、複数のメッセージが表示される可能性があります。同じイベントのために。

logging.disable(lvl)
すべてのロガーにオーバーライドレベル lvl を提供します。これは、ロガー自体のレベルよりも優先されます。 アプリケーション全体でロギング出力を一時的に絞る必要が生じた場合、この機能が役立ちます。 その効果は、重大度 lvl 以下のすべてのロギング呼び出しを無効にすることです。そのため、INFOの値で呼び出すと、すべてのINFOイベントとDEBUGイベントが破棄されますが、重大度WARNING以上のイベントは破棄されます。ロガーの有効レベルに従って処理されます。 logging.disable(logging.NOTSET)が呼び出されると、このオーバーライドレベルが効果的に削除されるため、ログ出力は個々のロガーの有効レベルに依存します。
logging.addLevelName(lvl, levelName)

レベル lvl を内部辞書のテキスト levelName に関連付けます。これは、たとえば Formatter がメッセージをフォーマットするときに、数値レベルをテキスト表現にマップするために使用されます。 この関数を使用して、独自のレベルを定義することもできます。 唯一の制約は、使用されるすべてのレベルがこの関数を使用して登録される必要があり、レベルが正の整数であり、重大度の昇順で増加する必要があることです。

ノート

独自のレベルを定義することを考えている場合は、カスタムレベルのセクションを参照してください。

logging.getLevelName(lvl)

ロギングレベル lvl のテキスト表現を返します。 レベルが事前定義されたレベルCRITICAL、ERROR、WARNING、INFO、またはDEBUGのいずれかである場合、対応する文字列を取得します。 addLevelName（）を使用してレベルを名前に関連付けている場合は、 lvl に関連付けた名前が返されます。 定義されたレベルの1つに対応する数値が渡されると、対応する文字列表現が返されます。 それ以外の場合は、文字列「Level％s」％lvlが返されます。

ノート

整数レベルは、たとえば次の場合に使用する必要があります Logger およびハンドラーのインスタンスにレベルを設定します。 この関数は、%(levelname)sフォーマット指定子（ LogRecord属性を参照）を使用して、整数レベルとフォーマットされたログ出力に表示されるレベル名を変換するために使用されます。

logging.makeLogRecord(attrdict)
属性が attrdict によって定義されている新しい LogRecord インスタンスを作成して返します。 この関数は、ピクルス化された LogRecord 属性ディクショナリを取得し、ソケットを介して送信し、受信側で LogRecord インスタンスとして再構成する場合に役立ちます。
logging.basicConfig([**kwargs])

デフォルトの Formatter で StreamHandler を作成し、それをルートロガーに追加することにより、ロギングシステムの基本構成を行います。 関数 debug（）、 info（）、 warning（）、 error（）および critical（）[X104X ]は、ルートロガーにハンドラーが定義されていない場合、 basicConfig（）を自動的に呼び出します。

ルートロガーにハンドラーが既に構成されている場合、この関数は何もしません。

バージョン2.4で変更：以前は、 basicConfig（）はキーワード引数を取りませんでした。

ノート

この関数は、他のスレッドを開始する前にメインスレッドから呼び出す必要があります。 2.7.1および3.2より前のバージョンのPythonでは、この関数が複数のスレッドから呼び出されると、（まれに）ハンドラーがルートロガーに複数回追加され、メッセージなどの予期しない結果が発生する可能性があります。ログに複製されています。

次のキーワード引数がサポートされています。

フォーマット

説明

ファイル名

StreamHandlerではなく、指定されたファイル名を使用してFileHandlerを作成することを指定します。

ファイルモード

filename が指定されている場合は、このモードでファイルを開きます。 デフォルトは'a'です。

フォーマット

ハンドラーには指定されたフォーマット文字列を使用してください。

datefmt

time.strftime（）で受け入れられているように、指定された日付/時刻形式を使用します。

レベル

ルートロガーレベルを指定されたレベルに設定します。

ストリーム

指定されたストリームを使用して、StreamHandlerを初期化します。 この引数はファイル名と互換性がないことに注意してください。両方が存在する場合、ストリームは無視されます。

logging.shutdown()
すべてのハンドラーをフラッシュして閉じることにより、正常なシャットダウンを実行するようにロギングシステムに通知します。 これはアプリケーションの終了時に呼び出す必要があり、この呼び出しの後にログシステムを使用しないでください。
logging.setLoggerClass(klass)
ロガーをインスタンス化するときにクラス klass を使用するようにロギングシステムに指示します。 クラスは、name引数のみが必要になるように__init__()を定義する必要があり、__init__()はLogger.__init__()を呼び出す必要があります。 この関数は通常、カスタムロガー動作を使用する必要があるアプリケーションによってロガーがインスタンス化される前に呼び出されます。


15.7.11。 警告モジュールとの統合

captionWarnings（）関数を使用して、 logging を warnings モジュールと統合できます。

logging.captureWarnings(capture)

この関数は、ログオンとログオフによって警告のキャプチャをオンにするために使用されます。

キャプチャがTrueの場合、警告モジュールによって発行された警告はロギングシステムにリダイレクトされます。 具体的には、警告は warnings.formatwarning（）を使用してフォーマットされ、結果の文字列は'py.warnings'という名前のロガーに重大度WARNINGで記録されます。

キャプチャがFalseの場合、ログシステムへの警告のリダイレクトは停止し、警告は元の宛先にリダイレクトされます（つまり、 captureWarnings(True)が呼び出される前に有効だったもの）。

も参照してください

モジュール logging.config
ロギングモジュールの構成API。
モジュール logging.handlers
ロギングモジュールに含まれている便利なハンドラー。
PEP 282 -ロギングシステム
Python標準ライブラリに含めるためにこの機能を説明した提案。
オリジナルのPythonロギングパッケージ
これは、 logging パッケージの元のソースです。 このサイトから入手できるパッケージのバージョンは、Python 1.5.2、2.1.x、および2.2.xでの使用に適しており、標準ライブラリに logging パッケージは含まれていません。



「https://www.finddevguides.com/index.php?title=Python/docs/2.7/library/logging&oldid=97195」から取得
Powered by MediaWiki