logging.handlers --- ログ記録ハンドラー

ソースコード: Lib/logging/handlers.py

Important

このページには、リファレンス情報だけが含まれています。チュートリアルは、以下のページを参照してください

• 基本チュートリアル

• 上級チュートリアル

• ロギングクックブック

---

このパッケージでは、以下の便利なハンドラが提供されています。なお、これらのハンドラのうち、3 つ (StreamHandler, FileHandler および NullHandler) は、実際には logging モジュール自身で定義されていますが、他のハンドラと一緒にここでドキュメント化します。

StreamHandler

logging コアパッケージに含まれる StreamHandler クラスは、ログ出力を sys.stdout, sys.stderr あるいは何らかのファイル風 (file-like) オブジェクト (あるいは、より正確に言えば write() および flush() メソッドをサポートする何らかのオブジェクト) といったストリームに送信します。

class logging.StreamHandler(stream=None)

StreamHandler クラスの新たなインスタンスを返します。 stream が指定された場合、インスタンスはログ出力先として指定されたストリームを使います; そうでない場合、 sys.stderr が使われます。

emit(record)

フォーマッタが指定されていれば、フォーマッタを使ってレコードを書式化します。 次に、レコードが terminator とともにストリームに書き込まれます。 例外情報が存在する場合、 traceback.print_exception() を使って書式化され、 ストリームの末尾につけられます。

flush()

ストリームの flush() メソッドを呼び出してバッファをフラッシュします。 close() メソッドは Handler から継承しているため何も出力を行わないので、 flush() 呼び出しを明示的に行う必要があるかもしれません。

setStream(stream)

このインスタンスの stream と指定された値が異なる場合、指定された値に設定します。 新しい stream を設定する前に、古い stream はフラッシュされます。

パラメータ:

stream -- ハンドラがこれから使う stream 。

戻り値:

ストリームを変更した場合は元のストリーム、変更しなかった場合は None。

Added in version 3.7.

terminator

フォーマット済みのレコードをストリームに出力するときの終端として使われる文字列です。デフォルト値は '\n' です。

もし改行区切りにしたくない場合はハンドラーインスタンスの terminator 属性に空文字列を設定してください。

以前のバージョンでは、区切り文字は '\n' にハードコードされていました。

Added in version 3.2.

FileHandler

logging コアパッケージに含まれる FileHandler クラスは、ログ出力をディスク上のファイルに送信します。このクラスは出力機能を StreamHandler から継承しています。

class logging.FileHandler(filename, mode='a', encoding=None, delay=False, errors=None)

FileHandler クラスの新しいインスタンスを返します。 指定されたファイルを開き、ログ記録用のストリームとして使います。 mode を指定しない場合は 'a' を使います。 encoding が None でない場合は、指定されたエンコーディングでファイルを開きます。 delay が真の場合、最初に emit() を呼び出すまでファイルを開きません。 デフォルトではファイルのサイズは無制限に増え続けます。 errors を指定すると、エンコーディングエラーの処理方法を決定するために使われます。

バージョン 3.6 で変更: 文字列値に加え、 Path オブジェクトも filename 引数が受け取るようになりました。

バージョン 3.9 で変更: errors 引数が追加されました。

close()

ファイルを閉じます。

emit(record)

record をファイルに出力します。

終了時、ロギングがシャットダウンされたためにファイルがクローズされており、ファイルのモードが 'w' である場合、 record は出力されません (bpo-42378 を参照してください)。

NullHandler

Added in version 3.1.

logging コアパッケージに含まれる NullHandler クラスは、いかなる書式化も出力も行いません。これは本質的には、ライブラリ開発者に使われる 'no-op' ハンドラです。

class logging.NullHandler

NullHandler クラスの新しいインスタンスを返します。

emit(record)

このメソッドは何もしません。

handle(record)

このメソッドは何もしません。

createLock()

アクセスを直列化する必要のある I/O がないため、このメソッドはロックとして None を返します。

NullHandler の使い方の詳しい情報は、 ライブラリのためのロギングの設定 を参照してください。

WatchedFileHandler

logging.handlers モジュールの WatchedFileHandler クラスは、ログの書き込み先のファイルを監視する FileHandler です。 ファイルが変わると、いったん閉じてファイル名を使って開き直します。

ファイルはログファイルをローテーションさせる newsyslog や logrotate のようなプログラムを使うことで変更されることがあります。このハンドラは、 Unix/Linux で使われることを意図していますが、ファイルが最後にログを出力してから変わったかどうかを監視します。 (ファイルはデバイスや inode が変わることで変わったと判断します。) ファイルが変わったら古いファイルのストリームは閉じて、現在のファイルを新しいストリームを取得するために開きます。

このハンドラを Windows で使うことは適切ではありません。 というのも Windows では開いているログファイルを移動したり名前を変更したりできないからです - logging はファイルを排他的ロックを掛けて開きます - そのためこうしたハンドラは必要ないのです。 さらに、 Windows では ST_INO がサポートされていません; stat() はこの値として常に 0 を返します。

class logging.handlers.WatchedFileHandler(filename, mode='a', encoding=None, delay=False, errors=None)

WatchedFileHandler クラスの新しいインスタンスを返します。 指定されたファイルを開き、ログ記録用のストリームとして使います。 mode を指定しない場合は 'a' を使います。 encoding が None でない場合は、指定されたエンコーディングでファイルを開きます。 delay が真の場合、最初に emit() を呼び出すまでファイルを開きません。 デフォルトではファイルのサイズは無制限に増え続けます。 errors を指定すると、エンコーディングエラーの処理方法を決定します。

バージョン 3.6 で変更: 文字列値に加え、 Path オブジェクトも filename 引数が受け取るようになりました。

バージョン 3.9 で変更: errors 引数が追加されました。

reopenIfNeeded()

ファイルが変更されたか確認します。 変更されていれば既存のストリームをフラッシュして閉じ、ファイルを開き直します。 通常は、レコードをファイルに出力する前の準備として行います。

Added in version 3.6.

emit(record)

レコードをファイルに出力しますが、最初に reopenIfNeeded() を呼び出して、変更があった場合はファイルを再度開きます。

BaseRotatingHandler

logging.handlers モジュールの BaseRotatingHandler クラスは、ファイルをローテーションするハンドラ RotatingFileHandler と TimedRotatingFileHandler の基底クラスです。 このクラス自体をインスタンス化する必要はないはずですが、オーバーライドが必要になることのある属性やメソッドを持っています。

class logging.handlers.BaseRotatingHandler(filename, mode, encoding=None, delay=False, errors=None)

パラメータは FileHandler と同じです。属性は次の通りです:

namer

この属性に callable がセットされた場合、 rotation_filename() メソッドはこの callable に委譲されます。 callable に渡されるパラメータは rotation_filename() に渡されたものです。

注釈

namer 関数はロールオーバー中にかなりの回数呼ばれます。そのため、できるだけ単純で、速くあるべきです。さらに、それは与えられた入力に対しては常に同じ出力を返すべきです。そうでなければ、ロールオーバーの振る舞いは期待通りに動かないかもしれません。

namer を使う場合は、ローテーションで利用されるファイル名の特徴を保つ必要がある点にも注意してください。 たとえば RotatingFileHandler は、ローテーションが期待通りに動作するために、名前に連続した番号を含むようなファイル名のリストを持つことを期待します。 また TimedRotatingFileHandler は (ハンドラの初期化時に渡された backupCount にもとづいて) 削除すべき古いファイルを決定しながら、古いログファイルを削除します。 この仕組みが動作するためには、ファイル名は名前に含まれる日付や時刻でソート可能である必要があり、 namer はそれを尊重しなければなりません (namer がこの規則を尊重したくない場合、そのような namer は getFilesToDelete() メソッドが特定の命名規則に適合するようにオーバーライドされた TimedRotatingFileHandler の派生クラス内で使う必要があるでしょう)。

Added in version 3.3.

rotator

この属性に callable がセットされた場合、 rotate() メソッドはこの callable に委譲されます。 callable に渡されるパラメータは rotate() に渡されたものです。

Added in version 3.3.

rotation_filename(default_name)

ローテートを行う際にログファイルのファイル名を変更します。

このメソッドは、ファイル名をカスタマイズするために提供されます。

デフォルト実装は、ハンドラの 'namer' 属性が callable だった場合、その callable を呼んでデフォルト名を渡します。属性が callable でない場合 (デフォルトは None です)、名前は変更せずに返されます。

パラメータ:

default_name -- ログファイルのデフォルトのファイル名。

Added in version 3.3.

rotate(source, dest)

ローテートが行われる時、現在のログをローテートします。

デフォルト実装は、 ハンドラの 'rotator' 属性が callable だった場合、その callable を呼んで source と dest 引数を渡します。属性が callable でない場合 (デフォルトは None です)、単に source が destination に改名されます。

パラメータ:

• source -- ソースファイル名。これは通常ベースファイル名 、例えば 'test.log' となります。

• dest -- 変更先ファイル名。これは通常ソースファイルをローテートしたもの (例えば 'test.log.1') です。

Added in version 3.3.

これらの属性が存在する理由は、サブクラス化を省略できるようにするためです。 RotatingFileHandler と TimedRotatingFileHandler のインスタンスに対して同じ callable が使えます。もし namer や rotator callable が例外を上げれば、 emit() 呼び出しで発生した他の例外と同じ方法で、つまりハンドラの handleError() メソッドによって扱われます。

ローテート処理に大幅な変更を加える必要があれば、メソッドをオーバーライドすることができます。

例えば、 rotator と namer を使ってログローテートをカスタマイズする を参照してください。

RotatingFileHandler

logging.handlers モジュールの RotatingFileHandler クラスは、ディスク上のログファイルのローテーションをサポートします。

class logging.handlers.RotatingFileHandler(filename, mode='a', maxBytes=0, backupCount=0, encoding=None, delay=False, errors=None)

RotatingFileHandler クラスの新たなインスタンスを返します。 指定されたファイルが開かれ、ログ記録のためのストリームとして使われます。 mode が指定されなかった場合、 'a' が使われます。 encoding が None でない場合、その値はファイルを開くときのエンコーディングとして使われます。 delay が真ならば、ファイルを開くのは最初の emit() 呼び出しまで遅らせられます。 デフォルトでは、ファイルは無制限に大きくなりつづけます。 errors が提供されると、エンコーディングエラーの処理方法を決定します。

maxBytes および backupCount 値を指定することで、あらかじめ決められたサイズでファイルをロールオーバ (rollover) させることができます。 指定サイズを超えそうになると、ファイルは閉じられ、暗黙のうちに新たなファイルが開かれます。 ロールオーバは現在のログファイルの長さが maxBytes に近くなると常に起きますが、 maxBytes または backupCount がゼロならロールオーバは起きなくなってしまうので、一般的には backupCount を少なくとも 1 に設定し maxBytes を非ゼロにするのが良いでしょう。 backupCount が非ゼロのとき、システムは古いログファイルをファイル名に ".1", ".2" といった拡張子を追加して保存します。 例えば、 backupCount が 5 で、基本のファイル名が app.log なら、 app.log, app.log.1, app.log.2 ... と続き、 app.log.5 までを得ることになります。 ログの書き込み対象になるファイルは常に app.log です。このファイルが満杯になると、ファイルは閉じられ、 app.log.1 に名前が変更されます。 app.log.1, app.log.2 などが存在する場合、それらのファイルはそれぞれ app.log.2, app.log.3 といった具合に名前が変更されます。

バージョン 3.6 で変更: 文字列値に加え、 Path オブジェクトも filename 引数が受け取るようになりました。

バージョン 3.9 で変更: errors 引数が追加されました。

doRollover()

上述のような方法でロールオーバを行います。

emit(record)

上述のようなロールオーバを行いながら、レコードをファイルに出力します。

shouldRollover(record)

指定されたレコードによって、ファイルが設定されたサイズの上限を超えるかどうかを調べます。

TimedRotatingFileHandler

logging.handlers モジュールの TimedRotatingFileHandler クラスは、一定の時間間隔でディスク上のログファイルをローテーションする機能を提供します。

class logging.handlers.TimedRotatingFileHandler(filename, when='h', interval=1, backupCount=0, encoding=None, delay=False, utc=False, atTime=None, errors=None)

TimedRotatingFileHandler クラスの新たなインスタンスを返します。 filename に指定したファイルを開き、ログ出力先のストリームとして使います。ログファイルのローテーション時には、ファイル名に拡張子 (suffix) をつけます。ログファイルのローテーションは when および interval の積に基づいて行います。

when は interval の単位を指定するために使います。使える値は下表の通りです。大小文字の区別は行いません。

値	interval の単位	atTime の使用有無/使用方法
'S'	秒	無視
'M'	分	無視
'H'	時間	無視
'D'	日	無視
'W0'-'W6'	曜日 (0=月曜)	初期のロールオーバー時刻の算出に使用
'midnight'	atTime が指定されなかった場合は深夜に、そうでない場合は atTime の時刻にロールオーバーされます	初期のロールオーバー時刻の算出に使用

曜日ベースのローテーションを使う場合は、月曜として 'W0' を、火曜として 'W1' を、…、日曜として 'W6' を指定します。このケースの場合は、 interval は使われません。

古いログファイルの保存時、ロギングシステムによりファイル名に拡張子が付けられます。 ロールオーバ間隔によって、strftime の %Y-%m-%d_%H-%M-%S 形式またはその前方の一部を使って、日付と時間に基づいた拡張子が付けられます。

最初に次のロールオーバー時間を計算するとき (ハンドラが生成されるとき)、次のローテーションがいつ起こるかを計算するために、既存のログファイルの最終変更時刻または現在の時間が使用されます。

utc 引数が true の場合時刻は UTC になり、それ以外では現地時間が使われます。

backupCount がゼロでない場合、保存されるファイル数は高々 backupCount 個で、それ以上のファイルがロールオーバされる時に作られるならば、一番古いものが削除されます。削除のロジックは interval で決まるファイルを削除するので、 interval を変えると古いファイルが残ったままになることもあります。

delay が true なら、ファイルを開くのは emit() の最初の呼び出しまで延期されます。

atTime が None でない場合、それは datetime.time インスタンスでなければなりません。ロールオーバーが「夜中」「特定の曜日」に設定されていて、ロールが発生する時刻を指定します。 atTime の値は 初期 のロールオーバーの計算に使われますが、後続のロールオーバーは通常の間隔の計算で算出されます。

errors が指定されると、エンコーディングエラーの取り扱い方法を決定します。

注釈

最初のロールオーバーの計算はハンドラーが初期化されたときに行われます。 次回のロールオーバー時刻を計算するのは、ロールオーバーが起きたときだけです。 また、ロールオーバー自体はログの出力時にしか起きません。 これを念頭に置いておかないと混乱する可能性があります。 例えば、インターバルが 毎分 に設定されていて、1分ごとにログファイルが常に生成されるとは限りません。 アプリケーションが実行されている間、1分に1回以上のログ出力されて いるとすると 毎分、分割されたログファイルが出力されますが、そうでなく、5分ごとに出力される場合は、出力されずにロールオーバーが実行されなかった時間分のギャップが生じます。

バージョン 3.4 で変更: atTime パラメータが追加されました。

バージョン 3.6 で変更: 文字列値に加え、 Path オブジェクトも filename 引数が受け取るようになりました。

バージョン 3.9 で変更: errors 引数が追加されました。

doRollover()

上述のような方法でロールオーバを行います。

emit(record)

上で説明した方法でロールオーバを行いながら、レコードをファイルに出力します。

getFilesToDelete()

ロールオーバーの一環として削除されるファイル名のリストを返します。それらのファイルは、ハンドラによって書き込まれた最も古いバックアップログファイルの絶対パスです。

shouldRollover(record)

See if enough time has passed for a rollover to occur and if it has, compute the next rollover time.

SocketHandler

logging.handlers モジュールの SocketHandler クラスは、ログ出力をネットワークソケットに送信します。 基底クラスでは TCP ソケットを使います。

class logging.handlers.SocketHandler(host, port)

アドレスが host および port で与えられた遠隔のマシンと通信するようにした SocketHandler クラスのインスタンスを生成して返します。

バージョン 3.4 で変更: port に None を指定すると、Unix ドメインソケットが host 値を用いて作られます - そうでない場合は TCP ソケットが作られます。

close()

ソケットを閉じます。

emit()

レコードの属性辞書を pickle して、バイナリ形式でソケットに書き込みます。ソケット操作でエラーが生じた場合、暗黙のうちにパケットは捨てられます。事前に接続が失われていた場合、接続を再度確立します。受信端でレコードを unpickle して LogRecord にするには、 makeLogRecord() 関数を使ってください。

handleError()

emit() の処理中に発生したエラーを処理します。よくある原因は接続の消失です。次のイベント発生時に再試行できるようにソケットを閉じます。

makeSocket()

サブクラスで必要なソケット形式を詳細に定義できるようにするためのファクトリメソッドです。デフォルトの実装では、 TCP ソケット (socket.SOCK_STREAM) を生成します。

makePickle(record)

レコードの属性辞書をバイナリ形式に pickle したものの先頭に長さ情報を付け、ソケットを介して送信できるようにして返します。 この操作の詳細は次のコードと同等です:

data = pickle.dumps(record_attr_dict, 1)
datalen = struct.pack('>L', len(data))
return datalen + data

pickle が完全に安全というわけではないことに注意してください。セキュリティに関して心配なら、より安全なメカニズムを実装するためにこのメソッドをオーバーライドすると良いでしょう。例えば、 HMAC を使って pickle に署名して、受け取る側ではそれを検証することができます。あるいはまた、受け取る側でグローバルなオブジェクトの unpickle を無効にすることができます。

send(packet)

pickle したバイト文字列 packet をソケットに送信します。 送信するバイト文字列のフォーマットは、 makePickle() のドキュメントで解説されています。

この関数はネットワークがビジーの時に発生する部分的送信に対応しています。

createSocket()

ソケットの生成を試みます。失敗時には、指数的な減速アルゴリズムを使います。最初の失敗時には、ハンドラは送ろうとしていたメッセージを落とします。続くメッセージが同じインスタンスで扱われたとき、幾らかの時間が経過するまで接続を試みません。デフォルトのパラメタは、最初の遅延時間が 1 秒で、その遅延時間の後でそれでも接続が確保できないなら、遅延時間は 2 倍づつになり、最大で 30 秒になります。

この働きは、以下のハンドラ属性で制御されます:

• retryStart (最初の遅延時間、デフォルトは 1.0 秒)。

• retryFactor (乗数、デフォルトは 2.0)。

• retryMax (最大遅延時間、デフォルトは 30.0 秒)。

つまり、ハンドラが使われた 後に リモートリスナが起動した場合、メッセージが失われてしまうことがあります (ハンドラは、遅延時間が経過するまで接続を試みようとさえせず、その遅延時間中に通知なくメッセージを捨てるので)。

DatagramHandler

logging.handlers モジュールの DatagramHandler クラスは SocketHandler を継承し、UDP ソケットを通してログメッセージを送信する機能を提供します。

class logging.handlers.DatagramHandler(host, port)

アドレスが host および port で与えられた遠隔のマシンと通信するようにした DatagramHandler クラスのインスタンスを生成して返します。

注釈

UDP はストリーミングプロトコルではないため、このハンドラのインスタンスと host に指定したホストとの間に持続的なコネクションはありません。この理由から、ネットワークソケットを使う場合、イベントがログされるごとに DNS のルックアップを行わなければならないかもしれず、それによりシステムにある程度の待ち時間をもたらす可能性があります。この待ち時間が問題になる場合、自身でルックアップを行い、ホスト名の代わりにルックアップの結果得られた IP アドレスを使ってハンドラを初期化することができます。

バージョン 3.4 で変更: port に None を指定すると、Unix ドメインソケットが host 値を用いて作られます - そうでない場合は UDP ソケットが作られます。

emit()

レコードの属性辞書を pickle して、バイナリ形式でソケットに書き込みます。 ソケット操作でエラーが生じた場合、暗黙のうちにパケットは捨てられます。 受信端でレコードを unpickle して LogRecord にするには、 makeLogRecord() 関数を使ってください。

makeSocket()

ここで SocketHandler のファクトリメソッドをオーバライドして、 UDP ソケット (socket.SOCK_DGRAM) を生成しています。

send(s)

pickle したバイト文字列をソケットに送信します。 送信するバイト文字列のフォーマットは、 SocketHandler.makePickle() のドキュメントで解説されています。

SysLogHandler

logging.handlers モジュールの SysLogHandler クラスは、リモートまたはローカルの Unix syslog にログメッセージを送信する機能を提供します。

class logging.handlers.SysLogHandler(address=('localhost', SYSLOG_UDP_PORT), facility=LOG_USER, socktype=socket.SOCK_DGRAM, timeout=None)

SysLogHandler クラスの新しいインスタンスを返します。 このインスタンスは、address に (host, port) タプルで指定されたアドレスのリモート Unix マシンと通信します。 address を指定しない場合は ('localhost', 514) を使います。 このアドレスを使ってソケットを開きます。 (host, port) タプルの代わりに、'/dev/log' のような文字列でアドレスを指定することもできます。 その場合は Unix ドメインソケットを使って syslog にメッセージを送信します。 facility を指定しない場合は LOG_USER を使います。 開くソケットの種類は socktype 引数によって決まります。 デフォルトは socket.SOCK_DGRAM で、UDP ソケットを開きます。 rsyslog のような新しい syslog デーモンで使うために TCP ソケットを開くには、socket.SOCK_STREAM を指定してください。 timeout を指定すると、ソケット操作のタイムアウト (秒単位) を設定します。 これにより、syslog サーバに接続できないときにプログラムが無期限に停止してしまうことを防げます。 timeout のデフォルトは None で、タイムアウトは適用されません。

使用中のサーバが UDP ポート 514 を待機していない場合、 SysLogHandler が正常に動作していないように見える場合があります。その場合、ドメインソケットに使うべきアドレスを調べてください。そのアドレスはシステムによって異なります。例えば、Linux システムでは通常 '/dev/log' ですが、 OS X では '/var/run/syslog' です。プラットフォームを確認し、適切なアドレスを使う必要があります (アプリケーションを複数のプラットフォーム上で動作させる必要がある場合、実行時に確認する必要があるかもしれません)。Windows では、多くの場合、UDP オプションを使用する必要があります。

注釈

macOS 12.x (Monterey) でApple社はsyslogデーモンの振る舞いを変更し、デーモンはドメインソケットを待ち受けなくなりました。したがってこのシステム上では SysLogHandler が動作することは期待できません。

より詳細な情報は gh-91070 を参照して下さい。

バージョン 3.2 で変更: socktype が追加されました。

バージョン 3.14 で変更: timeout が追加されました

close()

遠隔ホストへのソケットを閉じます。

createSocket()

ソケットの作成を試み、データグラムソケットでなければ相手側への接続も試みます。 このメソッドはハンドラの初期化時に呼ばれますが、この時点で相手側が接続を待ち受けていなくてもエラーとはみなしません。 イベントを出力するときにソケットがなければ、再度呼び出されます。

Added in version 3.11.

emit(record)

レコードは書式化された後、 syslog サーバに送信されます。例外情報が存在しても、サーバには 送信されません 。

バージョン 3.2.1 で変更: (参照: bpo-12168) 初期のバージョンでは、 syslog デーモンに送られるメッセージは常に NUL バイトで終端していました。初期のバージョンの syslog デーモンが NUL 終端されたメッセージを期待していたからです - たとえ、それが適切な仕様 (RFC 5424) にはなかったとしても。 syslog デーモンの新しいバージョンは NUL バイトを期待せず、代わりにもしそれがある場合は削除します。さらに、より最近のデーモン (RFC 5424 により忠実なバージョン) は、メッセージの一部として NUL バイトを通します。

このような異なるデーモンの振る舞いすべてに対して syslog メッセージの取り扱いをより容易にするため、 NUL バイトの追加はクラスレベル属性 append_nul を使用して設定できるようになりました。これはデフォルトで True (既存の振る舞いを保持) ですが、 SysLogHandler インスタンスが NUL 終端文字を追加 しない ように False にセットすることができます。

バージョン 3.3 で変更: (参照: bpo-12419) 以前のバージョンでは、メッセージソースを識別するための "ident" あるいは "tag" プリフィックス機能はありませんでした。これは、今ではクラスレベル属性を使用して指定することができるようになりました。デフォルトでは既存の振る舞いを保持するために "" ですが、特定の SysLogHandler インスタンスが扱うすべてのメッセージに識別子を前置するようにそれをオーバーライドすることができます。識別子はバイトではなくテキストでなければならず、正確にそのままメッセージに前置されることに注意してください。

encodePriority(facility, priority)

ファシリティおよび優先度を整数に符号化します。値は文字列でも整数でも渡すことができます。文字列が渡された場合、内部の対応付け辞書が使われ、整数に変換されます。

シンボリックな LOG_ 値は SysLogHandler で定義されています。これは sys/syslog.h ヘッダーファイルで定義された値を反映しています。

優先度

名前 (文字列)	シンボル値
alert	LOG_ALERT
crit or critical	LOG_CRIT
debug	LOG_DEBUG
emerg or panic	LOG_EMERG
err or error	LOG_ERR
info	LOG_INFO
notice	LOG_NOTICE
warn or warning	LOG_WARNING

ファシリティ

名前 (文字列)	シンボル値
auth	LOG_AUTH
authpriv	LOG_AUTHPRIV
cron	LOG_CRON
daemon	LOG_DAEMON
ftp	LOG_FTP
kern	LOG_KERN
lpr	LOG_LPR
mail	LOG_MAIL
news	LOG_NEWS
syslog	LOG_SYSLOG
user	LOG_USER
uucp	LOG_UUCP
local0	LOG_LOCAL0
local1	LOG_LOCAL1
local2	LOG_LOCAL2
local3	LOG_LOCAL3
local4	LOG_LOCAL4
local5	LOG_LOCAL5
local6	LOG_LOCAL6
local7	LOG_LOCAL7

mapPriority(levelname)

ログレベル名を syslog 優先度名に対応付けます。カスタムレベルを使用している場合や、デフォルトアルゴリズムがニーズに適していない場合には、このメソッドをオーバーライドする必要があるかもしれません。デフォルトアルゴリズムは、 DEBUG, INFO, WARNING, ERROR, CRITICAL を等価な syslog 名に、他のすべてのレベル名を "warning" に対応付けます。

NTEventLogHandler

logging.handlers モジュールの NTEventLogHandler クラスは、ローカルの Windows NT、Windows 2000、または Windows XP のイベントログにログメッセージを送信する機能を提供します。 使う前に Mark Hammond の Python 用 Win32 拡張をインストールする必要があります。

class logging.handlers.NTEventLogHandler(appname, dllname=None, logtype='Application')

NTEventLogHandler クラスの新たなインスタンスを返します。 appname はイベントログに表示する際のアプリケーション名を定義するために使われます。 この名前を使って適切なレジストリエントリが生成されます。 dllname はログに保存するメッセージ定義の入った .dll または .exe ファイルへの完全修飾パス名を与えなければなりません (指定されない場合、 'win32service.pyd' が使われます - このライブラリは Win32 拡張とともにインストールされ、いくつかのプレースホルダとなるメッセージ定義を含んでいます)。 これらのプレースホルダを利用すると、メッセージの発信源全体がログに記録されるため、イベントログは巨大になるので注意してください。 ログを小さくしたい場合は、イベントログで使うメッセージ定義を含む独自の .dll または .exe の名前を渡す必要があります。 logtype は 'Application', 'System', 'Security' のいずれかで、デフォルトは 'Application' です。

close()

現時点では、イベントログエントリの発信源としてのアプリケーション名をレジストリから除去することはできます。しかしこれを行うと、イベントログビューアで意図した通りにログが見えなくなるでしょう - これはイベントログが .dll 名を取得するためにレジストリにアクセスできなければならないからです。現在のバージョンではこの操作を行いません。

emit(record)

メッセージ ID、イベントカテゴリ、イベント型を決定し、メッセージを NT イベントログに記録します。

getEventCategory(record)

レコードに対するイベントカテゴリを返します。自作のカテゴリを指定したい場合、このメソッドをオーバライドしてください。このクラスのバージョンのメソッドは 0 を返します。

getEventType(record)

レコードのイベント型を返します。自作の型を指定したい場合、このメソッドをオーバライドしてください。このクラスのバージョンのメソッドは、ハンドラの typemap 属性を使って対応付けを行います。この属性は __init__() で初期化され、 DEBUG, INFO, WARNING, ERROR, CRITICAL が入っています。自作のレベルを使っているのなら、このメソッドをオーバライドするか、ハンドラの typemap 属性に適切な辞書を配置する必要があるでしょう。

getMessageID(record)

レコードのメッセージ ID を返します。自作のメッセージを使っているのなら、ロガーに渡される msg を書式化文字列ではなく ID にします。その上で、辞書参照を行ってメッセージ ID を得ます。このクラスのバージョンでは 1 を返します。この値は win32service.pyd における基本メッセージ ID です。

SMTPHandler

logging.handlers モジュールの SMTPHandler クラスは、SMTP を使ってメールアドレスにログメッセージを送信する機能を提供します。

class logging.handlers.SMTPHandler(mailhost, fromaddr, toaddrs, subject, credentials=None, secure=None, timeout=1.0)

新たな SMTPHandler クラスのインスタンスを返します。インスタンスは email の from および to アドレス行、および subject 行とともに初期化されます。 toaddrs は文字列からなるリストでなければなりません。非標準の SMTP ポートを指定するには、 mailhost 引数に (host, port) のタプル形式を指定します。文字列を使った場合、標準の SMTP ポートが使われます。もし SMTP サーバが認証を必要とするならば、 (username, password) のタプル形式を credentials 引数に指定することができます。

セキュアプロトコル (TLS) の使用を指定するには secure 引数にタプルを渡してください。これは認証情報が渡された場合のみ使用されます。タプルは、空のタプルか、キーファイルの名前を持つ1要素のタプルか、またはキーファイルと証明書ファイルの名前を持つ2要素のタプルのいずれかでなければなりません。 (このタプルは smtplib.SMTP.starttls() メソッドに渡されます。)

SMTP サーバとのコミュニケーションのために、 timeout 引数を使用してタイムアウトを指定することができます。

バージョン 3.3 で変更: timeout 引数が追加されました。

emit(record)

レコードを書式化し、指定されたアドレスに送信します。

getSubject(record)

レコードに応じたサブジェクト行を指定したいなら、このメソッドをオーバライドしてください。

MemoryHandler

logging.handlers モジュールの MemoryHandler クラスは、ログレコードをメモリにバッファリングし、定期的に target (送信先) ハンドラへフラッシュする機能を提供します。 バッファが一杯になったときや、一定以上の重大度のイベントが発生したときにフラッシュします。

MemoryHandler はより一般的な抽象クラス、 BufferingHandler のサブクラスです。この抽象クラスでは、ログ記録するレコードをメモリ上にバッファリングします。各レコードがバッファに追加される毎に、 shouldFlush() を呼び出してバッファをフラッシュすべきかどうか調べます。フラッシュする必要がある場合、 flush() がフラッシュ処理を行うものと想定されます。

class logging.handlers.BufferingHandler(capacity)

容量つきのバッファーを設定してハンドラーが初期化されます。 capacity はバッファ可能なログレコード数を意味します。

emit(record)

レコードをバッファに追加します。 shouldFlush() が true を返す場合、バッファを処理するために flush() を呼び出します。

flush()

BufferingHandler インスタンスのフラッシュは、バッファを空のリストに設定します。 このメソッドをオーバーライドすると、より有用なフラッシュ処理を実装できます。

shouldFlush(record)

バッファが許容量に達している場合に True を返します。このメソッドは自作のフラッシュ処理方針を実装するためにオーバライドすることができます。

class logging.handlers.MemoryHandler(capacity, flushLevel=ERROR, target=None, flushOnClose=True)

MemoryHandler クラスの新たなインスタンスを返します。 インスタンスはサイズ capacity （バッファされるレコード数）のバッファとともに初期化されます。 flushLevel が指定されていない場合、 ERROR が使われます。 target が指定されていない場合、ハンドラが何らかの意味のある処理を行う前に setTarget() でターゲットを指定する必要があります。 flushOnClose が False に指定されていた場合、ハンドラが閉じられるときにバッファはフラッシュ されません 。 flushOnClose が指定されていないか True に指定されていた場合、ハンドラが閉じられるときのバッファのフラッシュは以前の挙動になります。

バージョン 3.6 で変更: flushOnClose パラメータが追加されました。

close()

flush() を呼び出し、ターゲットを None に設定してバッファを消去します。

flush()

MemoryHandler インスタンスのフラッシュは、送信先があれば、バッファ内のレコードを送信先に送るだけです。 送信先にレコードを送るとバッファも消去されます。 異なる動作にしたい場合はオーバーライドしてください。

setTarget(target)

このハンドラの送信先となるハンドラを設定します。

shouldFlush(record)

バッファが一杯になっているか、 flushLevel またはそれ以上のレコードでないかを調べます。

HTTPHandler

logging.handlers モジュールの HTTPHandler クラスは、GET または POST を使って Web サーバにログメッセージを送信する機能を提供します。

class logging.handlers.HTTPHandler(host, url, method='GET', secure=False, credentials=None, context=None)

HTTPHandler クラスの新たなインスタンスを返します。特別なポートを使う必要がある場合、host は host:port の形式で使うことができます。 method が指定されない場合、 GET が使われます。 secure が真の場合、HTTPS 接続が使われます。 HTTPS 接続で使用する SSL 設定のために context 引数を ssl.SSLContext のインスタンスに設定することができます。 credentials を指定する場合、BASIC 認証の際の HTTP 'Authorization' ヘッダに使われるユーザIDとパスワードからなる 2要素タプルを渡してください。 credentials を指定する場合、ユーザIDとパスワードが通信中に平文として剥き出しにならないよう、secure=True も指定すべきです。

バージョン 3.5 で変更: context パラメータが追加されました。

mapLogRecord(record)

URL エンコードされて Web サーバに送信することになる、 record に基づく辞書を供給します。デフォルトの実装では単に record.__dict__ を返します。例えば LogRecord のサブセットのみを Web サーバに送信する場合や、 サーバーに送信する内容を特別にカスタマイズする必要がある場合には、このメソッドをオーバライドできます。

emit(record)

レコードを URL エンコードされた辞書形式で Web サーバに送信します。レコードを送信のために辞書に変換するために mapLogRecord() が呼び出されます。

注釈

Web server に送信するためのレコードを準備することは一般的な書式化操作とは同じではありませんので、 setFormatter() を使って Formatter を指定することは、 HTTPHandler には効果はありません。 format() を呼び出す代わりに、このハンドラは mapLogRecord() を呼び出し、その後その返却辞書を Web server に送信するのに適した様式にエンコードするために urllib.parse.urlencode() を呼び出します。

QueueHandler

Added in version 3.2.

logging.handlers モジュールの QueueHandler クラスは、queue や multiprocessing モジュールが実装するようなキューにログメッセージを送信する機能を提供します。

QueueListener クラスとともに QueueHandler を使うと、ロギングを行うスレッドから分離されたスレッド上でハンドラを動かすことができます。これは、クライアントに対してサービスするスレッドができるだけ速く応答する必要がある一方、別のスレッド上で (SMTPHandler によって電子メールを送信するような) 潜在的に遅い操作が行われるような、ウェブアプリケーションおよびその他のサービスアプリケーションにおいて重要です。

class logging.handlers.QueueHandler(queue)

QueueHandler クラスの新しいインスタンスを返します。 インスタンスは、メッセージの送信先となるキューを指定して初期化します。 queue には任意のキューのようなオブジェクトを指定できます。 enqueue() メソッドにそのまま渡されるので、そのメソッドでキューにメッセージを送る方法を扱う必要があります。 キューがタスク追跡 API を持つ必要は ない ため、queue に SimpleQueue インスタンスも使えます。

注釈

multiprocessing を使っている場合、 SimpleQueue を使うことは避けてください。代わりに multiprocessing.Queue を使ってください。

警告

multiprocessing モジュールは、get_logger() で作成・取得する内部ロガーを使います。 multiprocessing.Queue は、要素がキューに入ると DEBUG レベルのメッセージをログに記録します。 このログメッセージを、同じ multiprocessing.Queue インスタンスを使う QueueHandler で処理すると、デッドロックや無限再帰が発生します。

emit(record)

LogRecord を準備した結果をキューに入れます。 サイズに上限のあるキューが一杯になるなどして例外が発生した場合は、handleError() メソッドを呼び出してエラーを処理します。 その結果、レコードが通知なく破棄されることも (logging.raiseExceptions が False の場合)、sys.stderr にメッセージが表示されることも (logging.raiseExceptions が True の場合) あります。

prepare(record)

キューに追加するためレコードを準備します。このメソッドが返したオブジェクトがキューに追加されます。

基底の実装はレコードがメッセージや引数と、またもし存在すれば、発生した例外およびスタック情報と統合されるようにフォーマットします。 またこの実装ではpickle 化不可能な要素をレコードから削除します。 特に、この実装はレコードの msg と message 属性を (ハンドラの format() メソッドを呼び出すことによって得られる) 統合されたメッセージで上書きし、同時に args, exc_info, exc_text の3つの属性値をすべて None に設定します。

レコードを dict や JSON 文字列に変換したい場合や、オリジナルのレコードを変更せずに修正済のコピーを送りたい場合は、このメソッドをオーバーライドすると良いでしょう。

注釈

基底の実装は、レコードを pickle 化可能にしつつ、さらなるフォーマット処理を防ぐために、メッセージを引数でフォーマットしてフォーマットされたメッセージを message と msg 属性に設定し、同時に args と exc_text 属性を None に設定します。このことは、 QueueListener 側のハンドラが必要なフォーマット処理を行う、たとえば例外のフォーマット処理を行う、ための必要な情報が得られないかもしれないことを意味します。そのため、 QueueHandler の派生クラスにおいてこのメソッドを、たとえば exc_text 属性が None に設定されないように、オーバーライドしたいと考えるかもしれません。この場合、 message / msg / args といった属性の変更はレコードが pickle 化可能であることを保証することと関係しており、元の args の値が pickle 化可能かどうかによって、これらの属性の変更が避けられないかもしれないということに注意してください (この点については、自分のコードだけでなく依存するライブラリのコードも考慮しなければならないことにも注意してください)

enqueue(record)

キューにレコードを put_nowait() を使ってエンキューします; ブロッキングやタイムアウト、あるいはなにか特別なキューの実装を使いたければ、これをオーバライドしてみてください。

listener

dictConfig() による設定で作成された場合、この属性には、このハンドラとともに使う QueueListener インスタンスが格納されます。 それ以外の場合は None です。

Added in version 3.12.

QueueListener

Added in version 3.2.

logging.handlers モジュールの QueueListener クラスは、queue や multiprocessing モジュールが実装するようなキューからログメッセージを受信する機能を提供します。 内部スレッドでキューからメッセージを受け取り、同じスレッド上で 1 つ以上のハンドラに渡して処理します。 QueueListener 自体はハンドラではありませんが、QueueHandler と連携して動作するため、ここで説明します。

QueueHandler クラスとともに QueueListener を使うと、ロギングを行うスレッドから分離されたスレッド上でハンドラを動かすことができます。これは、クライアントに対してサービスするスレッドができるだけ速く応答する必要がある一方、別のスレッド上で (SMTPHandler によって電子メールを送信するような) 潜在的に遅い操作が行われるような、ウェブアプリケーションおよびその他のサービスアプリケーションにおいて重要です。

class logging.handlers.QueueListener(queue, *handlers, respect_handler_level=False)

QueueListener クラスの新しいインスタンスを返します。 インスタンスは、メッセージの送信先となるキューと、キューに入ったエントリーを処理するハンドラのリストを指定して初期化します。 任意のキューのようなオブジェクトを使えます。 dequeue() メソッドにそのまま渡されるので、そのメソッドでキューからメッセージを取り出す方法を扱う必要があります。 キューがタスク追跡 API を持つ必要は ありません が、利用可能なら使います。 そのため、queue に SimpleQueue インスタンスも使えます。

注釈

multiprocessing を使っている場合、 SimpleQueue を使うことは避けてください。代わりに multiprocessing.Queue を使ってください。

もし respect_handler_level が True なら、メッセージをハンドラーに渡すか決める時に（メッセージのレベルに比べて）ハンドラーのレベルが尊重されます。そうでない場合は依然のPythonバージョンと同様にすべてのメッセージは常にハンドラーに渡されます。

バージョン 3.5 で変更: The respect_handler_level argument was added.

バージョン 3.14 で変更: QueueListener を with によるコンテキストマネージャーとして使えるようになりました。 コンテキストに入るとリスナを起動し、コンテキストから出ると停止します。 __enter__() は QueueListener オブジェクトを返します。

dequeue(block)

キューからレコードを取り出して返します。 必要に応じてブロックするかどうかを指定できます。

ベース実装は get() を使用します。タイムアウトを有効にしたい場合や、カスタムのキュー実装を使いたい場合は、このメソッドをオーバーライドすると良いでしょう。

prepare(record)

レコードを扱うための準備をします。

この実装は渡されたレコードをそのまま返します。その値をハンドラに渡す前に何らかのカスタムな整列化 (marshalling) あるいはレコードに対する操作を行う必要があれば、このメソッドをオーバーライドすると良いでしょう。

handle(record)

レコードを処理します。

これは、ハンドラをループしてそれらに処理すべきレコードを渡します。ハンドラに渡される実際のオブジェクトは、 prepare() から返されたものです。

start()

リスナーを開始します。

これは、 LogRecord を処理するキューを監視するために、バックグラウンドスレッドを開始します。

バージョン 3.14 で変更: 呼び出した時点ですでにリスナが動作中の場合は RuntimeError を送出します。

stop()

リスナーを停止します。

スレッドに終了するように依頼し、終了するまで待ちます。アプリケーションの終了前にこのメソッドを呼ばないと、いくつかのレコードがキューに残り、処理されなくなるかもしれないことに注意してください。

enqueue_sentinel()

リスナーに停止するように指示するためキューに番兵を書き込みます。この実装は put_nowait() を使用します。タイムアウトを有効にしたい場合や、カスタムのキュー実装を使いたい場合は、このメソッドをオーバーライドすると良いでしょう。

Added in version 3.3.

参考

logging モジュール

logging モジュールの API リファレンス。

logging.config モジュール

logging モジュールの環境設定 API です。