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

重要

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

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

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

15.9.1。 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（）呼び出しが必要になる場合があることに注意してください。

15.9.2。 FileHandler

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

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

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

バージョン2.6で変更： delay が追加されました。

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

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

15.9.3。 NullHandler

バージョン2.7の新機能。

コア logging パッケージにある NullHandler クラスは、フォーマットや出力を行いません。これは本質的に、ライブラリ開発者が使用するための「no-op」ハンドラーです。

class logging.NullHandler

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

emit(record): この方法は何もしません。

handle(record): この方法は何もしません。

createLock(): アクセスをシリアル化する必要のある基になるI / Oがないため、このメソッドはロックに対してNoneを返します。

NullHandler の使用方法の詳細については、ライブラリのログの構成を参照してください。

15.9.4。 WatchedFileHandler

バージョン2.6の新機能。

logging.handlers モジュールにある WatchedFileHandler クラスは、ログに記録されているファイルを監視するFileHandlerです。ファイルが変更された場合は、ファイル名を使用して閉じられ、再度開かれます。

newsyslog や logrotate など、ログファイルのローテーションを実行するプログラムを使用すると、ファイルが変更される可能性があります。このハンドラーは、Unix / Linuxでの使用を目的としており、ファイルを監視して、最後の発行以降にファイルが変更されているかどうかを確認します。（デバイスまたはiノードが変更された場合、ファイルは変更されたと見なされます。）ファイルが変更された場合、古いファイルストリームが閉じられ、ファイルが開かれて新しいストリームが取得されます。

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

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

emit(record) レコードをファイルに出力しますが、最初にファイルが変更されているかどうかを確認します。存在する場合は、レコードをファイルに出力する前に、既存のストリームがフラッシュされて閉じられ、ファイルが再度開かれます。

15.9.5。 RotatingFileHandler

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

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

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

maxBytes および backupCount の値を使用して、ファイルを所定のサイズでロールオーバーできるようにすることができます。サイズを超えようとすると、ファイルが閉じられ、出力用に新しいファイルがサイレントに開かれます。ロールオーバーは、現在のログファイルの長さがほぼ maxBytes になるたびに発生します。 maxBytes または backupCount のいずれかがゼロの場合、ロールオーバーは発生しません。 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などに名前が変更されます。それぞれ。

バージョン2.6で変更： delay が追加されました。

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

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

15.9.6。 TimedRotatingFileHandler

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

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

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

when を使用して、 interval のタイプを指定できます。可能な値のリストは以下のとおりです。大文字と小文字は区別されないことに注意してください。

価値	間隔のタイプ
`'S'`	秒
`'M'`	分
`'H'`	時間
`'D'`	日々
`'W0'-'W6'`	平日（0 =月曜日）
`'midnight'`	深夜にロールオーバー

平日ベースのローテーションを使用する場合は、月曜日に「W0」、火曜日に「W1」など、日曜日に「W6」まで指定します。この場合、 interval に渡された値は使用されません。

システムは、ファイル名に拡張子を追加することにより、古いログファイルを保存します。拡張機能は日付と時刻に基づいており、ロールオーバー間隔に応じて、strftime形式%Y-%m-%d_%H-%M-%Sまたはその先頭部分を使用します。

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

utc 引数がtrueの場合、UTC単位の時間が使用されます。それ以外の場合は現地時間が使用されます。

backupCount がゼロ以外の場合、最大で backupCount ファイルが保持され、ロールオーバーが発生したときにさらに作成される場合は、最も古いファイルが削除されます。削除ロジックは間隔を使用して削除するファイルを決定するため、間隔を変更すると古いファイルが残っている可能性があります。

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

バージョン2.6で変更： delay および utc が追加されました。

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

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

15.9.7。 SocketHandler

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

class logging.handlers.SocketHandler(host, port)

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

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

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

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

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

makePickle(record)

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

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

send(packet): ピクルス文字列パケットをソケットに送信します。この機能により、ネットワークがビジーのときに発生する可能性のある部分的な送信が可能になります。

createSocket()

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

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

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

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

15.9.8。 DatagramHandler

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

class logging.handlers.DatagramHandler(host, port)

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

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

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

send(s): 漬け物をソケットに送ります。

15.9.9。 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オプションを使用する必要があります。

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

close(): リモートホストへのソケットを閉じます。

emit(record): レコードはフォーマットされてから、syslogサーバーに送信されます。例外情報が存在する場合、サーバーには送信されません。

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名にマップし、他のすべてのレベル名は'警告'。

15.9.10。 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を返します。

15.9.11。 SMTPHandler

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

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

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

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

バージョン2.6で変更： クレデンシャルが追加されました。

バージョン2.7で変更： secure が追加されました。

emit(record): レコードをフォーマットして、指定された宛先に送信します。

getSubject(record): レコードに依存する件名を指定する場合は、このメソッドをオーバーライドします。

15.9.12。 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)

MemoryHandler クラスの新しいインスタンスを返します。インスタンスは、容量のバッファサイズで初期化されます。 flushLevel が指定されていない場合、ERRORが使用されます。 target が指定されていない場合、このハンドラーが何か役立つことを行う前に、 setTarget（）を使用してターゲットを設定する必要があります。

close(): flush（）を呼び出し、ターゲットを None に設定し、バッファーをクリアします。

flush(): MemoryHandler の場合、フラッシュとは、バッファリングされたレコードがあれば、それをターゲットに送信することを意味します。これが発生すると、バッファもクリアされます。別の動作が必要な場合はオーバーライドします。

setTarget(target): このハンドラーのターゲットハンドラーを設定します。

shouldFlush(record): バッファがいっぱいか、 flushLevel 以上のレコードをチェックします。

15.9.13。 HTTPHandler

logging.handlers モジュールにある HTTPHandler クラスは、GETまたはPOSTセマンティクスのいずれかを使用したWebサーバーへのロギングメッセージの送信をサポートします。

class logging.handlers.HTTPHandler(host, url, method='GET')

HTTPHandler クラスの新しいインスタンスを返します。 hostは、特定のポート番号を使用する必要がある場合、host:portの形式にすることができます。

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

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

ノート

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

も参照してください

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

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

目次