14.5.1 Logger オブジェクト

ロガーは以下の属性とメソッドを持ちます。ロガーを直接インスタンス化することはできず、常にモジュール関数 logging.getLogger(name) を介してインスタンス化するので注意してください。

propagate: この値の評価結果が偽になる場合、ログ記録しようとするメッセージはこのロガーに渡されず、また子ロガーから上位の (親の) ロガーに渡されません。コンストラクタはこの属性を 1 に設定します。

setLevel( lvl)

このロガーの閾値を lvl に設定します。ログ記録しようとするメッセージで、lvl よりも深刻でないものは無視されます。ロガーが生成された際、レベルは NOTSET (これにより全てのメッセージについて、ロガーがルートロガーであれば処理される、そうでなくてロガーが非ルートロガーの場合には親ロガーに代行させる) に設定されます。ルートロガーは WARNING レベルで生成されることに注意してください。

「親ロガーに代行させる」という用語の意味は、もしロガーのレベルが NOTEST ならば、祖先ロガーの系列の中を NOTEST 以外のレベルの祖先を見つけるかルートに到達するまで辿っていく、ということです。

もし NOTEST 以外のレベルの祖先が見つかったなら、その祖先のレベルが祖先の探索を開始したロガーの実効レベルとして取り扱われ、ログイベントがどのように処理されるかを決めるのに使われます。

ルートに到達した場合、ルートのレベルが NOTEST ならば全てのメッセージは処理されます。そうでなければルートのレベルが実効レベルとして使われます。

isEnabledFor( lvl): 深刻さが lvl のメッセージが、このロガーで処理されることになっているかどうかを示します。このメソッドはまず、 logging.disable(lvl) で設定されるモジュールレベルの深刻さレベルを調べ、次にロガーの実効レベルを getEffectiveLevel() で調べます。

getEffectiveLevel( ): このロガーの実効レベルを示します。NOTSET 以外の値が setLevel() で設定されていた場合、その値が返されます。そうでない場合、NOTSET 以外の値が見つかるまでロガーの階層をルートロガーの方向に追跡します。見つかった場合、その値が返されます。

debug( msg[, *args[, **kwargs]])

レベル DEBUG のメッセージをこのロガーで記録します。 msg はメッセージの書式化文字列で、args は msg に文字列書式化演算子を使って取り込むための引数です。(これは、書式化文字列でキーワードを使い引数に辞書を渡すことができる、ということを意味します。)

キーワード引数 kwargs からは二つのキーワードが調べられます。一つめは exc_info で、この値の評価値が偽でない場合、例外情報をログメッセージに追加します。(sys.exc_info の返す形式の) 例外情報を表すタプルが与えられていれば、それをメッセージに使います。それ以外の場合には、sys.exc_info を呼び出して例外情報を取得します。

もう一つのキーワード引数は extra で、当該ログイベント用に作られた LogRecoed の __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 のドキュメントを参照してください。)

これらの属性をログメッセージに使うことにしたなら、少し注意が必要です。上の例では、'clientip' と 'user' が LogRecord の属性辞書に含まれていることを期待した書式化文字列で Formatter はセットアップされています。これらの属性が欠けていると、書式化例外が発生してしまうためメッセージはログに残りません。したがってこの場合、常にこれらのキーがある extra 辞書を渡す必要があります。

このようなことは煩わしいかもしれませんが、この機能は限定された場面で使われるように意図しているものなのです。たとえば同じコードがいくつものコンテキストで実行されるマルチスレッドのサーバで、興味のある条件が現れるのがそのコンテキストに依存している(上の例で言えば、リモートのクライアント IP アドレスや認証されたユーザ名など)、というような場合です。そういった場面では、それ用の Formatter が特定の Handler と共に使われるというのはよくあることです。

バージョン 2.5 で変更された仕様: extra が追加されました

info( msg[, *args[, **kwargs]]): レベル INFO のメッセージをこのロガーで記録します。引数は debug() と同じように解釈されます。

warning( msg[, *args[, **kwargs]]): レベル WARNING のメッセージをこのロガーで記録します。引数は debug() と同じように解釈されます。

error( msg[, *args[, **kwargs]]): レベル ERROR のメッセージをこのロガーで記録します。引数は debug() と同じように解釈されます。

critical( msg[, *args[, **kwargs]]): レベル CRITICAL のメッセージをこのロガーで記録します。引数は debug() と同じように解釈されます。

log( lvl, msg[, *args[, **kwargs]]): 整数で表したレベル lvl のメッセージをこのロガーで記録します。その他の引数は debug() と同じように解釈されます。

exception( msg[, *args]): レベル ERROR のメッセージをこのロガーで記録します。引数は debug() と同じように解釈されます。例外情報はログメッセージに追加されます。このメソッドは例外ハンドラからのみ呼び出されます。

addFilter( filt): 指定されたフィルタ filt をこのロガーに追加します。

removeFilter( filt): 指定されたフィルタ filt をこのロガーから除去します。

filter( record): このロガーのフィルタをレコード (record) に適用し、レコードがフィルタを透過して処理されることになる場合には真を返します。

addHandler( hdlr): 指定されたハンドラ hdlr をこのロガーに追加します。

removeHandler( hdlr): 指定されたハンドラ hdlr をこのロガーから除去します。

findCaller( ): 呼び出し元のソースファイル名と行番号を調べます。ファイル名と行番号を 2 要素のタプルで返します。

handle( record): レコードをこのロガーおよびその上位ロガーに (propagate の値が偽になるまで) さかのぼった関連付けられている全てのハンドラに渡して処理します。このメソッドはソケットから受信した逆 pickle 化されたレコードに対してもレコードがローカルで生成された場合と同様に用いられます。 filter() によって、ロガーレベルでのフィルタが適用されます。

makeRecord( name, lvl, fn, lno, msg, args, exc_info, func, extra): このメソッドは、特殊な LogRecord インスタンスを生成するためにサブクラスでオーバライドできるファクトリメソッドです。バージョン 2.5 で変更された仕様: func と extra が追加されました

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。