バージョン2.3 以降で新規追加された 仕様です。 このモジュールでは、アプリケーションのための柔軟なエラーログ記録 (logiing) システムを実装するための関数やクラスを定義しています。
ログ記録は Logger クラスのインスタンス (以降 ロガー :logger) におけるメソッドを呼び出すことで行われます。各インスタンスは 名前をもち、ドット (ピリオド) を区切り文字として表記することで、 概念的には名前空間中の階層構造に配置されることになります。 例えば、"scan" と名づけられたロガーは "scan.text"、"scan.html"、 および "scan.pdf" ロガーの親ロガーとなります。ロガー名には何をつけてもよく、 ログに記録されるメッセージの生成元となるアプリケーション中の特定の 領域を示すことになります。
ログ記録されたメッセージにはまた、重要度レベル (level of importance) が関連付けられています。デフォルトのレベルとして提供されているものは DEBUG、INFO、WARNING、 ERROR および CRITICAL です。簡便性のために、 Logger の適切なメソッド群を呼ぶことで、ログに記録されたメッセージの 重要性を指定することができます。それらのメソッドとは、デフォルトの レベルを反映する形で、debug()、 info()、 warning()、 error() および critical() となっています。 これらのレベルを指定するにあたって制限はありません: Logger の より汎用的なメソッドで、明示的なレベル指定のための引数を持つ log() を使って自分自身でレベルを定義したり使用したりできます。
レベルもロガーに関連付けることができ、デベロッパが設定することも、 保存されたログ記録設定を読み込む際に設定することもできます。 ロガーに対してログ記録メソッドが呼び出されると、ロガーは自らの レベルとメソッド呼び出しに関連付けられたレベルを比較します。 ロガーのレベルがメソッド呼び出しのレベルよりも高い場合、実際の ログメッセージは生成されません。これはログ出力の冗長性を制御 するための基本的なメカニズムです。
ログ記録されるメッセージは LogRecord クラスのインスタンスとして コード化されます。ロガーがあるイベントを実際にログ出力すると決定した 場合、ログメッセージから LogRecord インスタンスが生成されます。
ログ記録されるメッセージは、ハンドラ (handers) を通して、 処理機構 (dispatch mechanism) にかけられます。ハンドラは Handler クラスのサブクラスのインスタンスで、ログ記録された (LogRecord 形式の) メッセージが、そのメッセージの伝達対象となる相手 (エンドユーザ、サポートデスクのスタッフ、システム管理者、開発者) に行き着くようにする役割を持ちます。ハンドラには特定の行き先に方向付け られた LogRecord インスタンスが渡されます。各ロガーは ゼロ個、単一またはそれ以上のハンドラを (Logger の addHandler メソッド) で関連付けることができます。 ロガーに直接関連付けられたハンドラに加えて、 ロガーの上位にあるロガー全てに関連付けられたハンドラ がメッセージを処理する際に呼び出されます。
ロガーと同様に、ハンドラは関連付けられたレベルを持つことができます。 ハンドラのレベルはロガーのレベルと同じ方法で、フィルタとして働きます。 ハンドラがあるイベントを実際に処理すると決定した場合、 emit() メソッドが使われ、メッセージを発送先に送信します。ほとんどの ユーザ定義の Hnadler のサブクラスで、この emit() をオーバライドする必要があるでしょう。
基底クラスとなる Handler クラスに加えて、多くの有用なサブクラスが 提供されています:
StreamHandler および FileHandler クラスは、中核となる ログ化機構パッケージ内で定義されています。他のハンドラはサブモジュール、 logging.handlers で定義されています。 (サブモジュールには もうひとつ logging.config があり、これは環境設定機能の ためのものです。)
ログ記録されたメッセージは Formatter クラスのインスタンスを 介し、表示用に書式かされます。これらのインスタンスは % 演算子と辞書を 使うのに適した書式化文字列で初期化されます。
複数のメッセージの初期化をバッチ処理するために、 BufferingFormatter のインスタンスを使うことができます。 書式化文字列 (バッチ処理で各メッセージに適用されます) に加えて、 ヘッダ (header) およびトレイラ (trailer) 書式化文字列が用意されて います。
ロガーレベル、ハンドラレベルの両方または片方に基づいたフィルタリング が十分でない場合、Logger および Handler インスタンスに Filter のインスタンスを (addFilter() メソッドを介して) 追加することができます。メッセージの処理を進める前に、ロガーとハンドラは ともに、全てのフィルタでメッセージの処理が許可されているか調べます。 いずれかのフィルタが偽となる値を返した場合、メッセージの処理は 行われません。
基本的な Filter 機能では、指定されたロガー名でフィルタを 行えるようになっています。この機能が利用された場合、名前付けされた ロガーとその下位にあるロガーに送られたメッセージがフィルタを通過 できるようになり、その他のメッセージは捨てられます。
上で述べたクラスに加えて、いくつかのモジュールレベルの関数が存在します。
[name]) |
与えられた名前に対して、この関数はどの呼び出しでも同じロガーインスタンス を返します。従って、ロガーインスタンスをアプリケーションの各部 でやりとりする必要はなくなります。
msg[, *args[, **kwargs]]) |
msg[, *args[, **kwargs]]) |
msg[, *args[, **kwargs]]) |
msg[, *args[, **kwargs]]) |
msg[, *args[, **kwargs]]) |
msg[, *args]) |
lvl) |
lvl, levelName) |
lvl) |
attrdict) |
attrdict) |
) |
) |
klass) |
参考資料: