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

ソースコード： ：source： `Lib / logging / handlers.py`

重要

このページには、参照情報のみが含まれています。チュートリアルについては、を参照してください

パッケージには、次の便利なハンドラーが含まれています。 3つのハンドラー（ StreamHandler 、 FileHandler 、 NullHandler ）は、実際には logging モジュール自体で定義されていますが、文書化されていることに注意してください。ここで他のハンドラーと一緒に。

StreamHandler

コア logging パッケージにある StreamHandler クラスは、ログ出力を sys.stdout 、 sys.stderr などのストリームに送信します。ファイルのようなオブジェクト（より正確には、write()およびflush()メソッドをサポートするオブジェクト）。

class logging.StreamHandler(stream=None)

StreamHandler クラスの新しいインスタンスを返します。 stream が指定されている場合、インスタンスはそれをログ出力に使用します。それ以外の場合は、 sys.stderr が使用されます。

emit(record): フォーマッターが指定されている場合、それはレコードのフォーマットに使用されます。次に、レコードはターミネータを使用してストリームに書き込まれます。例外情報が存在する場合は、 traceback.print_exception（）を使用してフォーマットされ、ストリームに追加されます。

flush(): flush（）メソッドを呼び出してストリームをフラッシュします。 close()メソッドは Handler から継承されているため、出力されないため、明示的な flush（）呼び出しが必要になる場合があることに注意してください。

setStream(stream)

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

パラメーター: stream –ハンドラーが使用する必要のあるストリーム。
戻り値: ストリームが変更された場合は古いストリーム、変更されていない場合は None 。

バージョン3.7の新機能。

バージョン3.2で変更： StreamHandlerクラスにterminator属性、デフォルト値'\n'が追加されました。これは、フォーマットされたレコードを書き込むときにターミネータとして使用されます。ストリームに。この改行の終了が必要ない場合は、ハンドラーインスタンスのterminator属性を空の文字列に設定できます。以前のバージョンでは、ターミネータは'\n'としてハードコードされていました。

FileHandler

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

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

FileHandler クラスの新しいインスタンスを返します。指定されたファイルが開かれ、ロギングのストリームとして使用されます。 モードが指定されていない場合、'a'が使用されます。 encoding がNoneでない場合は、そのエンコーディングでファイルを開くために使用されます。 delay がtrueの場合、ファイルを開くのは emit（）が最初に呼び出されるまで延期されます。デフォルトでは、ファイルは無期限に大きくなります。

バージョン3.6で変更：文字列値だけでなく、 Path オブジェクトも filename 引数に使用できます。

close(): ファイルを閉じます。

emit(record): レコードをファイルに出力します。

NullHandler

バージョン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での使用を目的としており、ファイルを監視して、最後の発行以降にファイルが変更されているかどうかを確認します。（デバイスまたはiノードが変更された場合、ファイルは変更されたと見なされます。）ファイルが変更された場合、古いファイルストリームが閉じられ、ファイルが開かれて新しいストリームが取得されます。

このハンドラーは、Windowsでの使用には適していません。これは、Windowsでは、開いているログファイルを移動したり名前を変更したりできないため（ログは排他ロックでファイルを開く）、そのようなハンドラーは必要ないためです。さらに、 ST_INO はWindowsではサポートされていません。 stat（）は、この値に対して常にゼロを返します。

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

WatchedFileHandler クラスの新しいインスタンスを返します。指定されたファイルが開かれ、ロギングのストリームとして使用されます。 モードが指定されていない場合、'a'が使用されます。 encoding がNoneでない場合は、そのエンコーディングでファイルを開くために使用されます。 delay がtrueの場合、ファイルを開くのは emit（）が最初に呼び出されるまで延期されます。デフォルトでは、ファイルは無期限に大きくなります。

バージョン3.6で変更：文字列値だけでなく、 Path オブジェクトも filename 引数に使用できます。

reopenIfNeeded(): ファイルが変更されているかどうかを確認します。存在する場合は、既存のストリームがフラッシュされて閉じられ、ファイルが再び開かれます。これは通常、レコードをファイルに出力する前段階として行われます。

バージョン3.6の新機能。

emit(record): レコードをファイルに出力しますが、ファイルが変更されている場合は、最初に reopenIfNeeded（）を呼び出してファイルを再度開きます。

BaseRotatingHandler

logging.handlers モジュールにある BaseRotatingHandler クラスは、回転ファイルハンドラー RotatingFileHandler および TimedRotatingFileHandler の基本クラスです。このクラスをインスタンス化する必要はありませんが、オーバーライドする必要のある属性とメソッドがあります。

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

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

namer: この属性が呼び出し可能に設定されている場合、ローテーションファイル名（）メソッドはこの呼び出し可能に委任します。呼び出し可能オブジェクトに渡されるパラメーターは、ローテーションファイル名（）に渡されるパラメーターです。

ノート

namer関数は、ロールオーバー中に何度も呼び出されるため、できるだけ単純で高速である必要があります。また、特定の入力に対して毎回同じ出力を返す必要があります。そうしないと、ロールオーバー動作が期待どおりに機能しない可能性があります。

バージョン3.3の新機能。

rotator: この属性が呼び出し可能に設定されている場合、 rotate（）メソッドはこの呼び出し可能に委任します。呼び出し可能オブジェクトに渡されるパラメーターは、 rotate（）に渡されるパラメーターです。

バージョン3.3の新機能。

rotation_filename(default_name)

ローテーション時にログファイルのファイル名を変更します。

これは、カスタムファイル名を提供できるように提供されています。

デフォルトの実装では、ハンドラーの「namer」属性が呼び出可能である場合はそれを呼び出し、デフォルトの名前を渡します。属性を呼び出せない場合（デフォルトはNone）、名前は変更されずに返されます。

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

バージョン3.3の新機能。

rotate(source, dest)

回転するときは、現在のログを回転させます。

デフォルトの実装では、ハンドラーが呼び出し可能である場合、ハンドラーの「rotator」属性を呼び出し、source引数とdest引数を渡します。属性を呼び出せない場合（デフォルトはNone）、ソースの名前は単に宛先に変更されます。

パラメーター

source –ソースファイル名。これは通常、ベースファイル名です。 'test.log'。
dest –宛先ファイル名。これは通常、ソースが回転する対象です。たとえば、 'test.log.1'。

バージョン3.3の新機能。

属性が存在する理由は、サブクラス化の手間を省くためです。 RotatingFileHandler と TimedRotatingFileHandler のインスタンスに同じ呼び出し可能オブジェクトを使用できます。 namerまたはrotatorcallableのいずれかが例外を発生させた場合、これはemit()呼び出し中の他の例外と同じ方法で処理されます。ハンドラーのhandleError()メソッドを介して。

ローテーション処理にさらに重要な変更を加える必要がある場合は、メソッドをオーバーライドできます。

例については、ローテーションとネーマーを使用してログローテーション処理をカスタマイズするを参照してください。

RotatingFileHandler

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

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

RotatingFileHandler クラスの新しいインスタンスを返します。指定されたファイルが開かれ、ロギングのストリームとして使用されます。 モードが指定されていない場合、'a'が使用されます。 encoding がNoneでない場合は、そのエンコーディングでファイルを開くために使用されます。 delay がtrueの場合、ファイルを開くのは emit（）が最初に呼び出されるまで延期されます。デフォルトでは、ファイルは無期限に大きくなります。

maxBytes および backupCount の値を使用して、ファイルを所定のサイズでロールオーバーできるようにすることができます。サイズを超えようとすると、ファイルが閉じられ、新しいファイルがサイレントに開かれて出力されます。ロールオーバーは、現在のログファイルの長さがほぼ 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 引数に使用できます。

doRollover(): 上記のように、ロールオーバーを実行します。

emit(record): 前述のようにロールオーバーに対応して、レコードをファイルに出力します。

TimedRotatingFileHandler

logging.handlers モジュールにある TimedRotatingFileHandler クラスは、特定の時間間隔でのディスクログファイルのローテーションをサポートします。

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

TimedRotatingFileHandler クラスの新しいインスタンスを返します。指定されたファイルが開かれ、ロギングのストリームとして使用されます。回転すると、ファイル名のサフィックスも設定されます。回転は、 when と interval の積に基づいて行われます。

when を使用して、 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 ファイルが保持され、ロールオーバーが発生したときにさらに作成される場合は、最も古いファイルが削除されます。削除ロジックは間隔を使用して削除するファイルを決定するため、間隔を変更すると古いファイルが残っている可能性があります。

delay がtrueの場合、ファイルを開くのは emit（）が最初に呼び出されるまで延期されます。

atTime がNoneでない場合、ロールオーバーが「深夜に」発生するように設定されている場合は、ロールオーバーが発生する時刻を指定するdatetime.timeインスタンスである必要があります。」または「特定の平日」。これらの場合、 atTime 値は、初期ロールオーバーの計算に効果的に使用され、後続のロールオーバーは通常の間隔計算によって計算されることに注意してください。

ノート

初期ロールオーバー時間の計算は、ハンドラーが初期化されるときに行われます。後続のロールオーバー時間の計算は、ロールオーバーが発生したときにのみ実行され、ロールオーバーは出力を発行したときにのみ発生します。これを念頭に置いていない場合、混乱を招く可能性があります。たとえば、「毎分」の間隔が設定されている場合、それは、（ファイル名に）時間が1分で区切られたログファイルが常に表示されることを意味するわけではありません。アプリケーションの実行中に、ログ出力が1分に1回よりも頻繁に生成される場合、次には、1分で区切られた時間のログファイルを表示することが期待できます。一方、ロギングメッセージが5分ごとに1回だけ出力される場合（たとえば）、出力が発生しなかった（したがってロールオーバーが発生しなかった）分に対応するファイル時間にギャップがあります。

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

バージョン3.6で変更：文字列値だけでなく、 Path オブジェクトも filename 引数に使用できます。

doRollover(): 上記のように、ロールオーバーを実行します。

emit(record): 上記のようにロールオーバーに対応して、レコードをファイルに出力します。

SocketHandler

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

class logging.handlers.SocketHandler(host, port)

host および port によってアドレスが指定されているリモートマシンと通信することを目的とした SocketHandler クラスの新しいインスタンスを返します。

バージョン3.4で変更： portがNoneとして指定されている場合、Unixドメインソケットはhostの値を使用して作成されます。創造された。

close(): ソケットを閉じます。

emit(): レコードの属性ディクショナリをピクルスし、バイナリ形式でソケットに書き込みます。ソケットにエラーがある場合は、パケットをサイレントにドロップします。以前に接続が失われた場合は、接続を再確立します。受信側のレコードを LogRecord にアンピックするには、 makeLogRecord（）関数を使用します。

handleError(): emit（）中に発生したエラーを処理します。最も可能性の高い原因は、接続の喪失です。次のイベントで再試行できるように、ソケットを閉じます。

makeSocket(): これは、サブクラスが必要なソケットの正確なタイプを定義できるようにするファクトリメソッドです。デフォルトの実装では、TCPソケット（ socket.SOCK_STREAM ）が作成されます。

makePickle(record)

レコードの属性ディクショナリを長さプレフィックス付きのバイナリ形式でピクルスし、ソケットを介して送信できるように返します。この操作の詳細は、次のものと同等です。

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

漬物は完全に安全ではないことに注意してください。セキュリティが心配な場合は、このメソッドをオーバーライドして、より安全なメカニズムを実装することをお勧めします。たとえば、HMACを使用してピクルスに署名し、受信側でそれらを確認するか、受信側でグローバルオブジェクトのピクルス解除を無効にすることができます。

send(packet)

ピクルス化されたバイト文字列パケットをソケットに送信します。送信されるバイト文字列の形式は、 makePickle（）のドキュメントに記載されているとおりです。

この機能により、部分的な送信が可能になります。これは、ネットワークがビジーのときに発生する可能性があります。

createSocket()

ソケットを作成しようとします。失敗すると、指数バックオフアルゴリズムを使用します。最初の失敗時に、ハンドラーは送信しようとしていたメッセージをドロップします。後続のメッセージが同じインスタンスによって処理される場合、しばらく経過するまで接続を試行しません。デフォルトのパラメーターは、初期遅延が1秒であり、それでも接続を確立できない場合、ハンドラーは最大30秒まで毎回遅延を2倍にします。

この動作は、次のハンドラー属性によって制御されます。

retryStart（初期遅延、デフォルトは1.0秒）。
retryFactor（乗数、デフォルトは2.0）。
retryMax（最大遅延、デフォルトは30.0秒）。

これは、ハンドラーが使用された後にリモートリスナーが起動すると、メッセージが失われる可能性があることを意味します（ハンドラーは遅延が経過するまで接続を試行せず、遅延期間）。

DatagramHandler

logging.handlers モジュールにある DatagramHandler クラスは、 SocketHandler から継承して、UDPソケットを介したロギングメッセージの送信をサポートします。

class logging.handlers.DatagramHandler(host, port)

host および port によってアドレスが指定されているリモートマシンと通信することを目的とした DatagramHandler クラスの新しいインスタンスを返します。

バージョン3.4で変更： portがNoneとして指定されている場合、Unixドメインソケットはhostの値を使用して作成されます-それ以外の場合、UDPソケット創造された。

emit(): レコードの属性ディクショナリをピクルスし、バイナリ形式でソケットに書き込みます。ソケットにエラーがある場合は、パケットをサイレントにドロップします。受信側のレコードを LogRecord にアンピックするには、 makeLogRecord（）関数を使用します。

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

send(s): ピクルス化されたバイト文字列をソケットに送信します。送信されるバイト文字列の形式は、 SocketHandler.makePickle（）のドキュメントに記載されているとおりです。

SysLogHandler

logging.handlers モジュールにある SysLogHandler クラスは、リモートまたはローカルのUnixsyslogへのロギングメッセージの送信をサポートします。

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

アドレスによってアドレスが(host, port)タプルの形式で指定されているリモートUnixマシンと通信することを目的とした SysLogHandler クラスの新しいインスタンスを返します。 アドレスが指定されていない場合は、('localhost', 514)が使用されます。アドレスはソケットを開くために使用されます。 (host, port)タプルを提供する代わりに、アドレスを文字列として提供することもできます（例： '/ dev / log'）。この場合、Unixドメインソケットを使用してメッセージをsyslogに送信します。 ファシリティが指定されていない場合は、LOG_USERが使用されます。開かれるソケットのタイプは、 socktype 引数によって異なります。この引数は、デフォルトで socket.SOCK_DGRAM であるため、UDPソケットを開きます。 TCPソケット（rsyslogなどの新しいsyslogデーモンで使用するため）を開くには、 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で変更：（：issue： `12168` を参照）以前のバージョンでは、syslogデーモンに送信されるメッセージは常にNULバイトで終了していました。これらのデーモンの初期バージョンでは、関連する仕様（ RFC 5424 ）に含まれていなくても、NUL終了メッセージが予期されていました。これらのデーモンのより最近のバージョンは、NULバイトを予期していませんが、存在する場合はそれを取り除きます。さらに最近のデーモン（RFC 5424により厳密に準拠）は、メッセージの一部としてNULバイトを渡します。

これらすべての異なるデーモンの動作に直面してsyslogメッセージをより簡単に処理できるようにするために、クラスレベルの属性append_nulを使用して、NULバイトの追加を構成できるようになりました。これはデフォルトでTrue（既存の動作を保持）に設定されますが、SysLogHandlerインスタンスでFalseに設定して、そのインスタンスをではなくに追加することができます。 NULターミネーター。

バージョン3.3で変更：（：issue： `12419` を参照）以前のバージョンでは、ソースを識別するための「ident」または「tag」プレフィックスの機能がありませんでした。メッセージの。これは、クラスレベルの属性を使用して指定できるようになりました。デフォルトでは""に設定され、既存の動作が保持されますが、SysLogHandlerインスタンスでオーバーライドして、そのインスタンスの前にIDを追加することができます。メッセージが処理されました。指定されたIDはバイトではなくテキストである必要があり、メッセージの前にそのまま追加されることに注意してください。

encodePriority(facility, priority)

ファシリティと優先度を整数にエンコードします。文字列または整数を渡すことができます-文字列が渡される場合、内部マッピング辞書を使用してそれらを整数に変換します。

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

優先事項

名前（文字列）	記号値
`alert`	LOG_ALERT
`crit`または`critical`	LOG_CRIT
`debug`	LOG_DEBUG
`emerg`または`panic`	LOG_EMERG
`err`または`error`	LOG_ERR
`info`	LOG_INFO
`notice`	LOG_NOTICE
`warn`または`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名にマップし、他のすべてのレベル名は'警告'。

NTEventLogHandler

logging.handlers モジュールにある NTEventLogHandler クラスは、ローカルのWindows NT、Windows 2000、またはWindowsXPイベントログへのログメッセージの送信をサポートします。使用する前に、Python用のMarkHammondの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): レコードのイベントタイプを返します。独自のタイプを指定する場合は、これをオーバーライドします。このバージョンは、__init__()で設定されているハンドラーのtypemap属性を使用して、DEBUG、INFO、WARNING、 ERRORおよびCRITICAL。独自のレベルを使用している場合は、このメソッドをオーバーライドするか、ハンドラーの typemap 属性に適切な辞書を配置する必要があります。

getMessageID(record): レコードのメッセージIDを返します。独自のメッセージを使用している場合は、 msg をフォーマット文字列ではなくIDとしてロガーに渡すことで、これを行うことができます。次に、ここで、辞書ルックアップを使用してメッセージIDを取得できます。このバージョンは、win32service.pydのベースメッセージIDである1を返します。

SMTPHandler

logging.handlers モジュールにある SMTPHandler クラスは、SMTPを介した電子メールアドレスへのロギングメッセージの送信をサポートします。

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

SMTPHandler クラスの新しいインスタンスを返します。インスタンスは、電子メールの差出人アドレスと宛先アドレス、および件名で初期化されます。 toaddrs は文字列のリストである必要があります。非標準のSMTPポートを指定するには、 mailhost 引数に（host、port）タプル形式を使用します。文字列を使用する場合は、標準のSMTPポートが使用されます。 SMTPサーバーで認証が必要な場合は、 credentials 引数に（ユーザー名、パスワード）タプルを指定できます。

セキュアプロトコル（TLS）の使用を指定するには、 secure 引数にタプルを渡します。これは、認証資格情報が提供されている場合にのみ使用されます。タプルは、空のタプル、またはキーファイルの名前を持つ単一値のタプル、またはキーファイルと証明書ファイルの名前を持つ2値のタプルのいずれかである必要があります。（このタプルは smtplib.SMTP.starttls（）メソッドに渡されます。）

timeout 引数を使用して、SMTPサーバーとの通信にタイムアウトを指定できます。

バージョン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(): これをオーバーライドして、カスタムフラッシュ動作を実装できます。このバージョンは、バッファを空にするだけです。

shouldFlush(record): バッファが容量に達している場合は、Trueを返します。このメソッドをオーバーライドして、カスタムフラッシュ戦略を実装できます。

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

MemoryHandler クラスの新しいインスタンスを返します。インスタンスは、容量（バッファリングされたレコードの数）のバッファサイズで初期化されます。 flushLevel が指定されていない場合、ERRORが使用されます。 target が指定されていない場合、このハンドラーが何か役立つことを行う前に、 setTarget（）を使用してターゲットを設定する必要があります。 flushOnClose がFalseとして指定されている場合、ハンドラーが閉じられたときにバッファーはフラッシュされません。 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の形式にすることができます。 メソッドが指定されていない場合、GETが使用されます。 secure がtrueの場合、HTTPS接続が使用されます。 context パラメーターを ssl.SSLContext インスタンスに設定して、HTTPS接続に使用されるSSL設定を構成できます。 credentials を指定する場合は、ユーザーIDとパスワードで構成される2タプルである必要があります。これは、基本認証を使用してHTTPの「Authorization」ヘッダーに配置されます。クレデンシャルを指定する場合は、secure = Trueも指定して、ユーザーIDとパスワードがクリアテキストでネットワークを介して渡されないようにする必要があります。

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

mapLogRecord(record): recordに基づいて、URLエンコードされてWebサーバーに送信される辞書を提供します。デフォルトの実装はrecord.__dict__を返すだけです。このメソッドは、たとえば次の場合にオーバーライドできます。 LogRecord のサブセットのみがWebサーバーに送信されるか、サーバーに送信される内容をより具体的にカスタマイズする必要がある場合。

emit(record): レコードをURLエンコードされた辞書としてWebサーバーに送信します。 mapLogRecord（）メソッドは、レコードを送信する辞書に変換するために使用されます。

ノート

レコードをWebサーバーに送信するための準備は、一般的なフォーマット操作と同じではないため、 setFormatter（）を使用して、 HTTPHandler に Formatter を指定します。効果はありません。このハンドラーは、 format（）を呼び出す代わりに、 mapLogRecord（）を呼び出し、次に urllib.parse.urlencode（）を呼び出して、送信に適した形式で辞書をエンコードします。 Webサーバーに。

QueueHandler

バージョン3.2の新機能。

logging.handlers モジュールにある QueueHandler クラスは、 queue またはマルチプロセッシングで実装されているようなキューへのロギングメッセージの送信をサポートします。モジュール。

QueueListener クラスとともに、 QueueHandler を使用して、ハンドラーがロギングを実行するスレッドとは別のスレッドで作業を実行できるようにすることができます。これは、クライアントにサービスを提供するスレッドが可能な限り迅速に応答する必要があるWebアプリケーションやその他のサービスアプリケーションで重要ですが、低速になる可能性のある操作（ SMTPHandler を介した電子メールの送信など）は別のスレッドで実行されます。

class logging.handlers.QueueHandler(queue)

QueueHandler クラスの新しいインスタンスを返します。インスタンスは、メッセージを送信するキューで初期化されます。 queue は、任意のキューのようなオブジェクトにすることができます。 enqueue（）メソッドによってそのまま使用されます。このメソッドは、メッセージの送信方法を知っている必要があります。キューは、タスク追跡APIを持つために必須ではありません。つまり、キューに SimpleQueue インスタンスを使用できます。

emit(record): LogRecordの準備結果をキューに入れます。例外が発生した場合（例：制限されたキューがいっぱいになったため）、エラーを処理するために handleError（）メソッドが呼び出されます。これにより、レコードがサイレントにドロップされたり（logging.raiseExceptionsがFalseの場合）、メッセージがsys.stderrに出力されたり（logging.raiseExceptionsがTrueの場合）発生する可能性があります。 ]）。

prepare(record)

キューイング用のレコードを準備します。このメソッドによって返されるオブジェクトはキューに入れられます。

基本実装は、メッセージ、引数、および例外情報（存在する場合）をマージするようにレコードをフォーマットします。また、その場でレコードからピクルスできないアイテムを削除します。

レコードをdictまたはJSON文字列に変換する場合、または元のレコードをそのままにしてレコードの変更されたコピーを送信する場合は、このメソッドをオーバーライドすることをお勧めします。

enqueue(record): put_nowait()を使用してレコードをキューにエンキューします。ブロッキング動作、タイムアウト、またはカスタマイズされたキューの実装を使用する場合は、これをオーバーライドすることをお勧めします。

QueueListener

バージョン3.2の新機能。

logging.handlers モジュールにある QueueListener クラスは、 queue またはマルチプロセッシングに実装されているようなキューからのロギングメッセージの受信をサポートします。モジュール。メッセージは内部スレッドのキューから受信され、同じスレッドで1つ以上のハンドラーに渡されて処理されます。 QueueListener 自体はハンドラーではありませんが、 QueueHandler と連携して機能するため、ここで説明します。

QueueHandler クラスとともに、 QueueListener を使用して、ハンドラーがロギングを実行するスレッドとは別のスレッドで作業を実行できるようにすることができます。これは、クライアントにサービスを提供するスレッドが可能な限り迅速に応答する必要があるWebアプリケーションやその他のサービスアプリケーションで重要ですが、低速になる可能性のある操作（ SMTPHandler を介した電子メールの送信など）は別のスレッドで実行されます。

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

QueueListener クラスの新しいインスタンスを返します。インスタンスは、メッセージを送信するキューと、キューに配置されたエントリを処理するハンドラーのリストで初期化されます。キューは、任意のキューのようなオブジェクトにすることができます。 dequeue（）メソッドにそのまま渡されます。このメソッドは、そこからメッセージを取得する方法を知っている必要があります。キューは、タスク追跡APIを持つために必須ではありません（使用可能な場合は使用されます）。つまり、キューに SimpleQueue インスタンスを使用できます。

respect_handler_levelがTrueの場合、ハンドラーにメッセージを渡すかどうかを決定するときに、ハンドラーのレベルが（メッセージのレベルと比較して）尊重されます。それ以外の場合、動作は以前のPythonバージョンと同じです。つまり、常に各メッセージを各ハンドラーに渡します。

バージョン3.5で変更： respect_handler_level引数が追加されました。

dequeue(block)

レコードをデキューして返し、オプションでブロックします。

基本実装はget()を使用します。タイムアウトを使用したり、カスタムキューの実装を操作したりする場合は、このメソッドをオーバーライドすることをお勧めします。

prepare(record)

取り扱いのための記録を準備します。

この実装は、渡されたレコードを返すだけです。レコードをハンドラーに渡す前に、レコードのカスタムマーシャリングまたは操作を行う必要がある場合は、このメソッドをオーバーライドすることをお勧めします。

handle(record)

レコードを処理します。

これは、ハンドラーをループして、処理するレコードを提供します。ハンドラーに渡される実際のオブジェクトは、 prepare（）から返されるオブジェクトです。

start()

リスナーを起動します。

これにより、バックグラウンドスレッドが起動し、LogRecordsが処理するキューを監視します。

stop()

リスナーを停止します。

これはスレッドに終了を要求し、終了するのを待ちます。アプリケーションが終了する前にこれを呼び出さないと、キューにまだいくつかのレコードが残っている可能性があり、それらは処理されないことに注意してください。

enqueue_sentinel(): センチネルをキューに書き込み、リスナーに終了するように指示します。この実装はput_nowait()を使用します。タイムアウトを使用したり、カスタムキューの実装を操作したりする場合は、このメソッドをオーバーライドすることをお勧めします。

バージョン3.3の新機能。

も参照してください

モジュールロギング: ロギングモジュールのAPIリファレンス。
モジュール logging.config: ロギングモジュールの構成API。

logging.handlers —ロギングハンドラー—Pythonドキュメント

目次

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

StreamHandler

FileHandler

NullHandler

WatchedFileHandler

BaseRotatingHandler

RotatingFileHandler

TimedRotatingFileHandler

SocketHandler

DatagramHandler

SysLogHandler

NTEventLogHandler

SMTPHandler

MemoryHandler

HTTPHandler

QueueHandler

QueueListener