"logging.handlers" --- 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 。

      戻り値:
         the old stream, if the stream was changed, or *None* if it
         wasn't.

      バージョン 3.7 で追加.

   terminator

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

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

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

      バージョン 3.2 で追加.


FileHandler
===========

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

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

   Returns a new instance of the "FileHandler" class. The specified
   file is opened and used as the stream for logging. If *mode* is not
   specified, "'a'" is used.  If *encoding* is not "None", it is used
   to open the file with that encoding.  If *delay* is true, then file
   opening is deferred until the first call to "emit()". By default,
   the file grows indefinitely. If *errors* is specified, it's used to
   determine how encoding errors are handled.

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

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

   close()

      ファイルを閉じます。

   emit(record)

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

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


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

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

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

   Returns a new instance of the "WatchedFileHandler" class. The
   specified file is opened and used as the stream for logging. If
   *mode* is not specified, "'a'" is used.  If *encoding* is not
   "None", it is used to open the file with that encoding.  If *delay*
   is true, then file opening is deferred until the first call to
   "emit()".  By default, the file grows indefinitely. If *errors* is
   provided, it determines how encoding errors are handled.

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

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

   reopenIfNeeded()

      ファイルが変更されていないかチェックします。 もし変更されていれ
      ば、手始めにレコードをファイルに出力し、既存のストリームはフラッ
      シュして閉じられ、ファイルが再度開かれます。

      バージョン 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" の派生クラス内
        で使う必要があるでしょう)。

      バージョン 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 を使ってログローテートをカスタマイズする を
参照してください。


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)

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


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

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


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)

   Returns a new instance of the "SysLogHandler" class intended to
   communicate with a remote Unix machine whose address is given by
   *address* in the form of a "(host, port)" tuple.  If *address* is
   not specified, "('localhost', 514)" is used.  The address is used
   to open a socket.  An alternative to providing a "(host, port)"
   tuple is providing an address as a string, for example '/dev/log'.
   In this case, a Unix domain socket is used to send the message to
   the syslog. If *facility* is not specified, "LOG_USER" is used. The
   type of socket opened depends on the *socktype* argument, which
   defaults to "socket.SOCK_DGRAM" and thus opens a UDP socket. To
   open a TCP socket (for use with the newer syslog daemons such as
   rsyslog), specify a value of "socket.SOCK_STREAM".

   使用中のサーバが 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* が追加されました。

   close()

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

   createSocket()

      Tries to create a socket and, if it's not a datagram socket,
      connect it to the other end. This method is called during
      handler initialization, but it's not regarded as an error if the
      other end isn't listening at this point - the method will be
      called again when emitting an event, if there is no socket at
      that point.

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

      For a "BufferingHandler" instance, flushing means that it sets
      the buffer to an empty list. This method can be overwritten to
      implement more useful flushing behavior.

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

      For a "MemoryHandler" instance, flushing means just sending the
      buffered records to the target, if there is one. The buffer is
      also cleared when buffered records are sent to the target.
      Override if you want different behavior.

   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
============

バージョン 3.2 で追加.

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

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

class logging.handlers.QueueHandler(queue)

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

   注釈:

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

   emit(record)

      Enqueues the result of preparing the LogRecord. Should an
      exception occur (e.g. because a bounded queue has filled up),
      the "handleError()" method is called to handle the error. This
      can result in the record silently being dropped (if
      "logging.raiseExceptions" is "False") or a message printed to
      "sys.stderr" (if "logging.raiseExceptions" is "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()" を使ってエンキューします; ブ
      ロッキングやタイムアウト、あるいはなにか特別なキューの実装を使い
      たければ、これをオーバライドしてみてください。


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()"
   メソッドによって使用されます。そのメソッドはメッセージを送る方法を
   知っている必要があります。もしタスクのトラッキングAPIにキューが必要
   でない場合はキューとして "SimpleQueue" のインスタンスが使用できます
   （トラッキングAPIが使用可能な場合は使用されます）。

   注釈:

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

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

   バージョン 3.5 で変更: The "respect_handler_level" 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 です。
