15.9. "logging.handlers" --- ロギングハンドラ
*********************************************


Important
^^^^^^^^^

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

* 基本チュートリアル

* 上級チュートリアル

* ロギングクックブック

**Source code:** Lib/logging/handlers.py

======================================================================

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


15.9.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()" 呼び出しを明示的に行う必要がある
      かもしれません。


15.9.2. FileHandler
===================

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

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

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

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

   close()

      ファイルを閉じます。

   emit(record)

      *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 で使われることを意図していますが、ファイルが
最後にログを出力してから変わったかどうかを監視します。 (ファイルはデバ
イスや inode が変わることで変わったと判断します。) ファイルが変わった
ら古いファイルのストリームは閉じて、現在のファイルを新しいストリームを
取得するために開きます。

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

class logging.handlers.WatchedFileHandler(filename[, mode[, encoding[, delay]]])

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

   *maxBytes* および *backupCount* 値を指定することで、あらかじめ決め
   られたサイズでファイルをロールオーバ (*rollover*) させることができ
   ます。指定サイズを超えそうになると、ファイルは閉じられ、暗黙のうち
   に新たなファイルが開かれます。ロールオーバは現在のログファイルの長
   さが *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" クラスの新たなインスタンスを返します。
   *filename* に指定したファイルを開き、ログ出力先のストリームとして使
   います。ログファイルのローテーション時には、ファイル名に拡張子
   (suffix) をつけます。ログファイルのローテーションは *when* および
   *interval* の積に基づいて行います。

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

   +------------------+-------------------------+
   | "値"             | *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* 個で、それ以上のファイルがロールオーバされる時に作ら
   れるならば、一番古いものが削除されます。削除のロジックは interval
   で決まるファイルを削除するので、 interval を変えると古いファイルが
   残ったままになることもあります。

   *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()

      レコードの属性辞書を 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 秒)。

      これは、リモートリスナがハンドラが使われた *後に* 起動すると、 (
      ハンドラは遅延が経過するまで接続を試みようとさえせず、遅延時間中
      に黙ってメッセージを落とすだけなので) メッセージが失われてしまう
      こともあるということです。


15.9.8. DatagramHandler
=======================

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

class logging.handlers.DatagramHandler(host, port)

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

   emit()

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

   makeSocket()

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

   send(s)

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


15.9.9. 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 オプションを使う
   必要性がかなり高いです。

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

   close()

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

   emit(record)

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

   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" に対応付けます。


15.9.10. 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 です。


15.9.11. SMTPHandler
====================

"logging.handlers" モジュールに含まれる "SMTPHandler" クラスは、 SMTP
を介したログ記録メッセージの送信機能をサポートします。

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

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

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

   バージョン 2.6 で変更: *credentials* が追加されました。

   バージョン 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" クラスの新たなインスタンスを返します。インスタンス
   はサイズ *capacity* のバッファとともに初期化されます。 *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)

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

   emit(record)

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

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

参考:

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

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