 |
 |
 |
Python ライブラリリファレンス |  |
 |
 |
|
|
|
Python ライブラリリファレンス | |
|
|
バージョン 2.3 で 新たに追加 された仕様です。 このモジュールでは、アプリケーションのための柔軟なエラーログ記録 (logging) システムを実装するための関数やクラスを定義しています。
ログ記録は 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() を使って自分自身でレベルを定義したり使用したりできます。
ログレベルの数値は以下の表のように与えられています。 これらは基本的に自分でレベルを定義したい人のためのもので、 定義するレベルを既存のレベルの間に位置づけるために具体的な値が必要になります。 もし数値が他のレベルと同じだったら、既存の値は上書きされその名前は失われます。
| レベル | 数値 |
|---|---|
CRITICAL |
50 |
ERROR |
40 |
WARNING |
30 |
INFO |
20 |
DEBUG |
10 |
NOTSET |
0 |
レベルもロガーに関連付けることができ、デベロッパが設定することも、 保存されたログ記録設定を読み込む際に設定することもできます。 ロガーに対してログ記録メソッドが呼び出されると、ロガーは自らの レベルとメソッド呼び出しに関連付けられたレベルを比較します。 ロガーのレベルがメソッド呼び出しのレベルよりも高い場合、実際の ログメッセージは生成されません。これはログ出力の冗長性を制御 するための基本的なメカニズムです。
ログ記録されるメッセージは LogRecord クラスのインスタンスとして コード化されます。ロガーがあるイベントを実際にログ出力すると決定した 場合、ログメッセージから LogRecord インスタンスが生成されます。
ログ記録されるメッセージは、ハンドラ (handlers) を通して、 処理機構 (dispatch mechanism) にかけられます。ハンドラは Handler クラスのサブクラスのインスタンスで、ログ記録された (LogRecord 形式の) メッセージが、そのメッセージの伝達対象となる相手 (エンドユーザ、サポートデスクのスタッフ、システム管理者、開発者) に行き着くようにする役割を持ちます。ハンドラには特定の行き先に方向付け られた LogRecord インスタンスが渡されます。各ロガーは ゼロ個、単一またはそれ以上のハンドラを (Logger の addHandler() メソッド) で関連付けることができます。 ロガーに直接関連付けられたハンドラに加えて、 ロガーの上位にあるロガー全てに関連付けられたハンドラ がメッセージを処理する際に呼び出されます。
ロガーと同様に、ハンドラは関連付けられたレベルを持つことができます。 ハンドラのレベルはロガーのレベルと同じ方法で、フィルタとして働きます。 ハンドラがあるイベントを実際に処理すると決定した場合、 emit() メソッドが使われ、メッセージを発送先に送信します。ほとんどの ユーザ定義の Handler のサブクラスで、この emit() をオーバライドする必要があるでしょう。
基底クラスとなる Handler クラスに加えて、多くの有用なサブクラスが 提供されています:
StreamHandler および FileHandler クラスは、中核となる ログ化機構パッケージ内で定義されています。他のハンドラはサブモジュール、 logging.handlers で定義されています。 (サブモジュールには もうひとつ logging.config があり、これは環境設定機能の ためのものです。)
ログ記録されたメッセージは Formatter クラスのインスタンスを 介し、表示用に書式化されます。これらのインスタンスは % 演算子と辞書を 使うのに適した書式化文字列で初期化されます。
複数のメッセージの初期化をバッチ処理するために、 BufferingFormatter のインスタンスを使うことができます。 書式化文字列 (バッチ処理で各メッセージに適用されます) に加えて、 ヘッダ (header) およびトレイラ (trailer) 書式化文字列が用意されて います。
ロガーレベル、ハンドラレベルの両方または片方に基づいたフィルタリング が十分でない場合、Logger および Handler インスタンスに Filter のインスタンスを (addFilter() メソッドを介して) 追加することができます。メッセージの処理を進める前に、ロガーとハンドラは ともに、全てのフィルタでメッセージの処理が許可されているか調べます。 いずれかのフィルタが偽となる値を返した場合、メッセージの処理は 行われません。
基本的な Filter 機能では、指定されたロガー名でフィルタを 行えるようになっています。この機能が利用された場合、名前付けされた ロガーとその下位にあるロガーに送られたメッセージがフィルタを通過 できるようになり、その他のメッセージは捨てられます。
上で述べたクラスに加えて、いくつかのモジュールレベルの関数が存在します。
| [name]) |
与えられた名前に対して、この関数はどの呼び出しでも同じロガーインスタンス を返します。従って、ロガーインスタンスをアプリケーションの各部 でやりとりする必要はなくなります。
| ) |
class MyLogger(logging.getLoggerClass()):
# ... override behaviour here
| msg[, *args[, **kwargs]]) |
キーワード引数 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' }
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 のドキュメントを参照してください。)
これらの属性をログメッセージに使うことにしたなら、少し注意が必要です。 上の例では、'clientip' と 'user' が LogRecord の属性辞書に含まれている ことを期待した書式化文字列で Formatter はセットアップされてい ます。これらの属性が欠けていると、書式化例外が発生してしまうためメッセー ジはログに残りません。したがってこの場合、常にこれらのキーがあ る extra 辞書を渡す必要があります。
このようなことは煩わしいかもしれませんが、この機能は限定された場面で使 われるように意図しているものなのです。たとえば同じコードがいくつものコ ンテキストで実行されるマルチスレッドのサーバで、興味のある条件が現れる のがそのコンテキストに依存している(上の例で言えば、リモートのクライアン ト IP アドレスや認証されたユーザ名など)、というような場合です。そういっ た場面では、それ用の Formatter が特定の Handler と共に 使われるというのはよくあることです。
バージョン 2.5 で 変更 された仕様: extra が追加されました
| msg[, *args[, **kwargs]]) |
| msg[, *args[, **kwargs]]) |
| msg[, *args[, **kwargs]]) |
| msg[, *args[, **kwargs]]) |
| msg[, *args]) |
| level, msg[, *args[, **kwargs]]) |
| lvl) |
| lvl, levelName) |
| lvl) |
| attrdict) |
| attrdict) |
| [**kwargs]) |
バージョン 2.4 で 変更 された仕様: 以前は basicConfig はキーワード引数を とりませんでした
以下のキーワード引数がサポートされます。
| Format | 説明 |
|---|---|
filename |
StreamHandler ではなく指定された名前で FileHandler が作られます |
filemode |
filename が指定されているとき、ファイルモードを指定します (filemode が指定されない場合デフォルトは 'a' です) |
format |
指定された書式化文字列をハンドラで使います |
datefmt |
指定された日付/時刻の書式を使います |
level |
ルートロガーのレベルを指定されたものにします |
stream |
指定されたストリームを StreamHandler の初期化に使います。 この引数は 'filename' と同時には使えないことに注意してください。 両方が指定されたときには 'stream' は無視されます |
| ) |
| klass) |
参考:
|
|
|
Python ライブラリリファレンス | |
|
|