16.8. logging.handlers — ロギングハンドラ

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

Important

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

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

16.8.1. StreamHandler

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

class logging.StreamHandler(stream=None)

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

emit(record)

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

flush()

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

バージョン 3.2 で変更: StreamHandler クラスに terminator 属性が追加されました (デフォルト値は '\n')。これは、書式化されたレコードをストリームに書き込むときの終端記号として使用されます。このような改行による終端を望まなければ、ハンドラ・インスタンスの terminator 属性を空の文字列に設定することができます。初期のバージョンでは、終端記号は '\n' としてハードコードされていました。

16.8.2. FileHandler

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

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

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

バージョン 3.6 で変更: As well as string values, Path objects are also accepted for the filename argument.

close()

ファイルを閉じます。

emit(record)

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

16.8.3. NullHandler

バージョン 3.1 で追加.

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

class logging.NullHandler

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

emit(record)

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

handle(record)

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

createLock()

アクセスが特殊化される必要がある I/O が下にないので、このメソッドはロックに対して None を返します。

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

16.8.4. 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)

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

バージョン 3.6 で変更: As well as string values, Path objects are also accepted for the filename argument.

reopenIfNeeded()

Checks to see if the file has changed. If it has, the existing stream is flushed and closed and the file opened again, typically as a precursor to outputting the record to the file.

バージョン 3.6 で追加.

emit(record)

Outputs the record to the file, but first calls reopenIfNeeded() to reopen the file if it has changed.

16.8.5. BaseRotatingHandler

logging.handlers モジュールに存在する BaseRotatingHandler クラスは、ローテートを行うファイルハンドラ RotatingFileHandler と TimedRotatingFileHandler のベースクラスです。このクラスをインスタンス化する必要はありませんが、オーバーライドすることになるかもしれない属性とメソッドを持っています。

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

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

namer

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

注釈

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

バージョン 3.3 で追加.

rotator

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

バージョン 3.3 で追加.

rotation_filename(default_name)

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

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

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

パラメータ:default_name – ログファイルのデフォルトのファイル名。

バージョン 3.3 で追加.

rotate(source, dest)

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

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

パラメータ:
  • source – ソースファイル名。これは通常ベースファイル名 、例えば 'test.log' となります。
  • dest – 変更先ファイル名。これは通常ソースファイルをローテートしたもの (例えば 'test.log.1') です。

バージョン 3.3 で追加.

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

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

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

16.8.6. RotatingFileHandler

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

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

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

You can use the maxBytes and backupCount values to allow the file to rollover at a predetermined size. When the size is about to be exceeded, the file is closed and a new file is silently opened for output. Rollover occurs whenever the current log file is nearly maxBytes in length; but if either of maxBytes or backupCount is zero, rollover never occurs, so you generally want to set backupCount to at least 1, and have a non-zero maxBytes. When backupCount is non-zero, the system will save old log files by appending the extensions '.1', '.2' etc., to the filename. For example, with a backupCount of 5 and a base file name of app.log, you would get app.log, app.log.1, app.log.2, up to app.log.5. The file being written to is always app.log. When this file is filled, it is closed and renamed to app.log.1, and if files app.log.1, app.log.2, etc. exist, then they are renamed to app.log.2, app.log.3 etc. respectively.

バージョン 3.6 で変更: As well as string values, Path objects are also accepted for the filename argument.

doRollover()

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

emit(record)

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

16.8.7. TimedRotatingFileHandler

logging.handlers モジュールに含まれる TimedRotatingFileHandler クラスは、特定の時間間隔でのログローテーションをサポートしています。

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

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

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

値 interval の単位 If/how atTime is used
'S' 秒 無視
'M' 分 無視
'H' 時間 無視
'D' 日 無視
'W0'-'W6' 曜日 (0=月曜) Used to compute initial rollover time
'midnight' Roll over at midnight, if atTime not specified, else at time atTime Used to compute initial rollover time

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

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

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

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

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

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

If atTime is not None, it must be a datetime.time instance which specifies the time of day when rollover occurs, for the cases where rollover is set to happen "at midnight" or "on a particular weekday". Note that in these cases, the atTime value is effectively used to compute the initial rollover, and subsequent rollovers would be calculated via the normal interval calculation.

注釈

Calculation of the initial rollover time is done when the handler is initialised. Calculation of subsequent rollover times is done only when rollover occurs, and rollover occurs only when emitting output. If this is not kept in mind, it might lead to some confusion. For example, if an interval of "every minute" is set, that does not mean you will always see log files with times (in the filename) separated by a minute; if, during application execution, logging output is generated more frequently than once a minute, then you can expect to see log files with times separated by a minute. If, on the other hand, logging messages are only output once every five minutes (say), then there will be gaps in the file times corresponding to the minutes where no output (and hence no rollover) occurred.

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

バージョン 3.6 で変更: As well as string values, Path objects are also accepted for the filename argument.

doRollover()

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

emit(record)

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

16.8.8. 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 してから先頭に長さ情報を付けてバイナリ形式にして、ソケットを介して送信できるようにして返します。

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

send(packet)

pickle された文字列 packet をソケットに送信します。この関数はネットワークがビジーの時に発生する部分的送信に対応しています。

createSocket()

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

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

  • retryStart (最初の遅延時間、デフォルトは 1.0 秒)。
  • retryFactor (乗数、デフォルトは 2.0)。
  • retryMax (最大遅延時間、デフォルトは 30.0 秒)。

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

16.8.9. DatagramHandler

logging.handlers モジュールに含まれる DatagramHandler クラスは、 SocketHandler を継承しており、 UDP ソケットを介したログ記録メッセージの送信をサポートしています。

class logging.handlers.DatagramHandler(host, port)

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

バージョン 3.4 で変更: If port is specified as None, a Unix domain socket is created using the value in host - otherwise, a UDP socket is created.

emit()

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

makeSocket()

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

send(s)

pickle された文字列をソケットに送信します。

16.8.10. SysLogHandler

logging.handlers モジュールに含まれる SysLogHandler クラスは、ログ記録メッセージを遠隔またはローカルの Unix syslog に送信する機能をサポートしています。

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

遠隔の Unix マシンと通信するための、 SysLogHandler クラスの新たなインスタンスを返します。マシンのアドレスは (host, port) のタプル形式をとる address で与えられます。 address が指定されない場合、 ('localhost', 514) が使われます。アドレスは UDP ソケットを使って開かれます。 (host, port) のタプル形式の代わりに文字列で "/dev/log" のように与えることもできます。この場合、 Unix ドメインソケットが syslog にメッセージを送るのに使われます。 facility が指定されない場合、 LOG_USER が使われます。開かれるソケットの型は、 socktype 引数に依り、デフォルトは socket.SOCK_DGRAM で、UDP ソケットを開きます。 (rsyslog のような新しい syslog デーモンと使うために) TCP ソケットを開くには、 socket.SOCK_STREAM の値を指定してください。

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

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

close()

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

emit(record)

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

バージョン 3.2.1 で変更: (See: bpo-12168.) In earlier versions, the message sent to the syslog daemons was always terminated with a NUL byte, because early versions of these daemons expected a NUL terminated message - even though it’s not in the relevant specification (RFC 5424). More recent versions of these daemons don’t expect the NUL byte but strip it off if it’s there, and even more recent daemons (which adhere more closely to RFC 5424) pass the NUL byte on as part of the message.

このような異なるデーモンの振る舞いすべてに対して 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" に対応付けます。

16.8.11. 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 拡張とともにインストールされ、いくつかのプレースホルダとなるメッセージ定義を含んでいます)。これらのプレースホルダを利用すると、メッセージの発信源全体がログに記録されるため、イベントログは巨大になるので注意してください。 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 です。

16.8.12. 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)

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

16.8.13. MemoryHandler

logging.handlers モジュールに含まれる MemoryHandler は、ログ記録するレコードをメモリ上にバッファリングし、定期的にその内容をターゲット (target) となるハンドラにフラッシュする機能をサポートしています。フラッシュ処理はバッファが一杯になるか、ある深刻度かそれ以上のレベルを持つイベントが観測された際に行われます。

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

class logging.handlers.BufferingHandler(capacity)

指定した許容量のバッファでハンドラを初期化します。

emit(record)

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

flush()

このメソッドをオーバライドして、自作のフラッシュ動作を実装することができます。このクラスのバージョンのメソッドでは、単にバッファの内容を削除して空にします。

shouldFlush(record)

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

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

Returns a new instance of the MemoryHandler class. The instance is initialized with a buffer size of capacity. If flushLevel is not specified, ERROR is used. If no target is specified, the target will need to be set using setTarget() before this handler does anything useful. If flushOnClose is specified as False, then the buffer is not flushed when the handler is closed. If not specified or specified as True, the previous behaviour of flushing the buffer will occur when the handler is closed.

バージョン 3.6 で変更: The flushOnClose parameter was added.

close()

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

flush()

MemoryHandler の場合、フラッシュ処理は単に、バッファされたレコードをターゲットがあれば送信することを意味します。これと異なる動作を行いたい場合、オーバライドしてください。

setTarget(target)

ターゲットハンドラをこのハンドラに設定します。

shouldFlush(record)

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

16.8.14. 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() を呼び出します。

16.8.15. QueueHandler

バージョン 3.2 で追加.

logging.handlers モジュールに含まれる QueueHandler クラスは、 queue モジュールや multiprocessing のモジュールで実装されるようなキューにログメッセージを送信する機能をサポートしています。

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

class logging.handlers.QueueHandler(queue)

QueueHandler クラスの新しいインスタンスを返します。インスタンスは、キューにメッセージを送るように初期化されます。キューは任意のキューのようなオブジェクトが可能です; それはそのまま enqueue() メソッドによって使用されます。そのメソッドはメッセージを送る方法を知っている必要があります。

emit(record)

準備した LogRecord の結果をキューに追加します。

prepare(record)

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

メッセージと引数を合成するためにレコードを書式化して、レコードから pickle 不可能なアイテムを in-place で取り除くベース実装です。

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

enqueue(record)

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

16.8.16. QueueListener

バージョン 3.2 で追加.

logging.handlers モジュールに含まれる QueueListener クラスは、 queue モジュールや multiprocessing のモジュールで実装されるようなキューからログメッセージを受信する機能をサポートしています。メッセージは内部スレッドのキューから受信され、同じスレッド上の複数のハンドラに渡されて処理されます。 QueueListener それ自体はハンドラではありませんが、 QueueHandler と連携して動作するのでここで文書化されています。

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

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

QueueListener クラスの新しいインスタンスを返します。インスタンスは、メッセージの送信先キューと、キュー上に配置されたエントリーを扱うハンドラのリストとともに初期化されます。キューには、任意のキューのようなオブジェクトを使用できます。キューのようなオブジェクトは、そのまま dequeue() メソッドに渡されます。そのメソッドはメッセージをキューから取得する方法を知っている必要があります。 respect_handler_level が True の場合、メッセージをそのハンドラーに渡すかどうかを判断する際、(メッセージに対するレベルと比較して)ハンドラのレベルは尊重されます。False の場合、以前の Python のバージョンと同様に動作し、各メッセージを各ハンドラに常に渡します。

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

dequeue(block)

キューからレコードを取り除き、それを返します。ブロッキングすることがあります。

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

prepare(record)

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

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

handle(record)

レコードを処理します。

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

start()

リスナーを開始します。

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

stop()

リスナーを停止します。

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

enqueue_sentinel()

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

バージョン 3.3 で追加.

参考

logging モジュール
logging モジュールの API リファレンス。
logging.config モジュール
logging モジュールの環境設定 API です。