:mod:`logging` --- Python 用ロギング機能
========================================

.. module:: logging
   :synopsis: アプリケーションのための、柔軟なエラーロギングシステム


.. moduleauthor:: Vinay Sajip <vinay_sajip@red-dove.com>
.. sectionauthor:: Vinay Sajip <vinay_sajip@red-dove.com>


.. index:: pair: Errors; logging

.. sidebar:: Important

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

   * :ref:`基本チュートリアル <logging-basic-tutorial>`
   * :ref:`上級チュートリアル <logging-advanced-tutorial>`
   * :ref:`ロギングクックブック <logging-cookbook>`


.. versionadded:: 2.3

このモジュールは、アプリケーションやライブラリのための柔軟な
エラーログ記録 (logging) システムを実装するための関数やクラスを定義しています。

標準ライブラリモジュールとしてログ記録 API が提供される利点は、
すべての Python モジュールがログ記録に参加できることであり、
これによってあなたが書くアプリケーションのログにサードパーティーの
モジュールが出力するメッセージを含ませることができます。

このモジュールは、多くの機能性と柔軟性を提供します。
ロギングに慣れていないなら、つかむのに一番いいのはチュートリアルを
読むことです (右のリンクを参照してください)。

モジュールで定義されている基本的なクラスと関数を、以下に列挙します。

* ロガーは、アプリケーションコードが直接使うインタフェースを公開します。
* ハンドラは、(ロガーによって生成された) ログ記録を適切な送信先に送ります。
* フィルタは、どのログ記録を出力するかを決定する、きめ細かい機能を提供します。
* フォーマッタは、ログ記録が最終的に出力されるレイアウトを指定します。


.. _logger:

ロガーオブジェクト
------------------

ロガーには以下のような属性とメソッドがあります。ロガーを直接インスタンス化することはできず、
常にモジュール関数 ``logging.getLogger(name)`` を介してインスタンス化することに注意してください。

.. class:: Logger

.. attribute:: Logger.propagate

   この評価が true であれば、ロギングメッセージはこのロガーによって、
   またこの子ロガーによって、上位の (親) ロガーのハンドラに渡されます。
   メッセージは、親ロガーのハンドラに直接渡されます - 問題の親ロガーの
   レベルもフィルタも考慮されません。

   この値の評価結果が false になる場合、ロギングメッセージは
   上位の (親の) ロガーのハンドラに渡されません。

   コンストラクタはこの属性を 1 に設定します。


.. method:: Logger.setLevel(lvl)

   このロガーの閾値を *lvl* に設定します。
   ログ記録しようとするメッセージで、 *lvl* よりも深刻でないものは無視されます。
   ロガーが生成された際、レベルは :const:`NOTSET` (これによりすべてのメッセージについて、
   ロガーがルートロガーであれば処理される、そうでなくてロガーが非ルートロガーの場合には親ロガーに委譲させる) に設定されます。
   ルートロガーは :const:`WARNING` レベルで生成されることに注意してください。

   「親ロガーに委譲」という用語の意味は、もしロガーのレベルが NOTEST ならば、
   祖先ロガーの系列の中を NOTEST 以外のレベルの祖先を見つけるかルートに到達するまで辿っていく、ということです。

   もし NOTEST 以外のレベルの祖先が見つかったなら、その祖先のレベルが探索を開始したロガーの実効レベルとして扱われ、
   ログイベントがどのように処理されるかを決めるのに使われます。

   ルートに到達した場合、ルートのレベルが NOTEST ならばすべてのメッセージは処理されます。
   そうでなければルートのレベルが実効レベルとして使われます。


.. method:: Logger.isEnabledFor(lvl)

   深刻度が *lvl* のメッセージが、このロガーで処理されることになっているかどうかを示します。
   このメソッドはまず、 ``logging.disable(lvl)`` で設定されるモジュールレベルの深刻度レベルを調べ、
   次にロガーの実効レベルを :meth:`getEffectiveLevel` で調べます。


.. method:: Logger.getEffectiveLevel()

   このロガーの実効レベルを示します。 :const:`NOTSET` 以外の値が :meth:`setLevel` で設定されていた場合、その値が返されます。
   そうでない場合、 :const:`NOTSET` 以外の値が見つかるまでロガーの階層をルートロガーの方向に追跡します。
   見つかった場合、その値が返されます。


.. method:: Logger.getChild(suffix)

   このロガーの子であるロガーを、接頭辞によって決定し、返します。
   従って、 ``logging.getLogger('abc').getChild('def.ghi')`` は、
   ``logging.getLogger('abc.def.ghi')`` によって返されるのと同じロガーを
   返すことになります。コレは簡便なメソッドで、親ロガーがリテラルでなく
   ``__name__`` などを使って名付けられているときに便利です。

   .. versionadded:: 2.7


.. method:: Logger.debug(msg, *args, **kwargs)

   レベル :const:`DEBUG` のメッセージをこのロガーで記録します。
   *msg* はメッセージの書式化文字列で、 *args* は *msg* に文字列書式化演算子を使って取り込むための引数です。
   (これは、書式化文字列の中でキーワードを使い、引数として単一の辞書を渡すことができる、ということを意味します。)

   キーワード引数 *kwargs* からは 2 つのキーワードが調べられます。
   一つ目は *exc_info* で、この値の評価値が false でない場合、例外情報をログメッセージに追加します。
   (:func:`sys.exc_info` の返す形式の) 例外情報を表すタプルが与えられていれば、それをメッセージに使います。
   それ以外の場合には、 :func:`sys.exc_info` を呼び出して例外情報を取得します。

   もう一つのキーワード引数は *extra* で、当該ログイベント用に作られる
   LogRecoed の __dict__ にユーザー定義属性を加えるのに使われる辞書を渡すために用いられます。
   これらの属性は好きなように使えます。たとえば、ログメッセージの一部にすることもできます。
   以下の例を見てください::

      FORMAT = '%(asctime)-15s %(clientip)s %(user)-8s %(message)s'
      logging.basicConfig(format=FORMAT)
      d = { 'clientip' : '192.168.0.1', 'user' : 'fbloggs' }
      logger = logging.getLogger('tcpserver')
      logger.warning('Protocol problem: %s', 'connection reset', extra=d)

   出力はこのようになります::

      2006-02-08 22:20:02,165 192.168.0.1 fbloggs  Protocol problem: connection reset

   *extra* で渡される辞書のキーはロギングシステムで使われているものと衝突しないようにしなければなりません。
   (どのキーがロギングシステムで使われているかについての詳細は :class:`Formatter` のドキュメントを参照してください。)

   これらの属性をログメッセージに使うことにしたなら、少し注意が必要です。
   上の例では、 'clientip' と 'user' が LogRecord の属性辞書に含まれていることを期待した書式化文字列で
   :class:`Formatter` がセットアップされています。
   もしこれらが欠けていると、書式化例外が発生してしまうためメッセージはログに残りません。
   したがってこの場合、常にこれらのキーを含む *extra* 辞書を渡す必要があります。

   このようなことは煩わしいかもしれませんが、この機能は限定された場面で使われるように意図しているものなのです。
   たとえば同じコードがいくつものコンテキストで実行されるマルチスレッドのサーバで、
   興味のある条件が現れるのがそのコンテキストに依存している
   (上の例で言えば、リモートのクライアント IP アドレスや認証されたユーザ名など)、というような場合です。
   そういった場面では、それ用の :class:`Formatter` が特定の :class:`Handler` と共に使われるというのはよくあることです。


.. method:: Logger.info(msg, *args, **kwargs)

   レベル :const:`INFO` のメッセージをこのロガーで記録します。
   引数は :meth:`debug` と同じように解釈されます。


.. method:: Logger.warning(msg, *args, **kwargs)

   レベル :const:`WARNING` のメッセージをこのロガーで記録します。
   引数は :meth:`debug` と同じように解釈されます。


.. method:: Logger.error(msg, *args, **kwargs)

   レベル :const:`ERROR` のメッセージをこのロガーで記録します。
   引数は :meth:`debug` と同じように解釈されます。


.. method:: Logger.critical(msg, *args, **kwargs)

   レベル :const:`CRITICAL` のメッセージをこのロガーで記録します。
   引数は :meth:`debug` と同じように解釈されます。


.. method:: Logger.log(lvl, msg, *args, **kwargs)

   整数で表したレベル *lvl* のメッセージをこのロガーで記録します。
   その他の引数は :meth:`debug` と同じように解釈されます。


.. method:: Logger.exception(msg, *args)

   レベル :const:`ERROR` のメッセージをこのロガーで記録します。
   引数は :meth:`debug` と同じように解釈されます。
   例外情報がログメッセージに追加されます。
   このメソッドは例外ハンドラからのみ呼び出されるべきです。


.. method:: Logger.addFilter(filt)

   指定されたフィルタ *filt* をこのロガーに追加します。


.. method:: Logger.removeFilter(filt)

   指定されたフィルタ *filt* をこのロガーから取り除きます。


.. method:: Logger.filter(record)

   このロガーのフィルタをレコード (record) に適用し、
   レコードがフィルタを透過して処理されることになる場合には true を返します。


.. method:: Logger.addHandler(hdlr)

   指定されたハンドラ *hdlr* をこのロガーに追加します。


.. method:: Logger.removeHandler(hdlr)

   指定されたハンドラ *hdlr* をこのロガーから取り除きます。


.. method:: Logger.findCaller()

   呼び出し元のソースファイル名と行番号を調べます。
   ファイル名と行番号と関数名を 3 要素のタプルで返します。

   .. versionchanged:: 2.4
      関数名も加えられました。
      以前のバージョンではファイル名と行番号を 2 要素のタプルで返していました。

.. method:: Logger.handle(record)

   レコードを、このロガーおよびその上位ロガー (ただし *propagate* の値が false になったところまで)
   に関連付けられているすべてのハンドラに渡して処理します。
   このメソッドは、ローカルで生成されたレコードだけでなく、
   ソケットから受信した unpickle されたレコードに対しても同様に用いられます。
   :meth:`~Logger.filter` によって、ロガーレベルでのフィルタが適用されます。


.. method:: Logger.makeRecord(name, lvl, fn, lno, msg, args, exc_info, func=None, extra=None)

   このメソッドは、特殊な :class:`LogRecord` インスタンスを生成するために
   サブクラスでオーバライドできるファクトリメソッドです。

   .. versionchanged:: 2.5
      *func* と *extra* が追加されました。

.. _handler:

ハンドラオブジェクト
--------------------

ハンドラ (Handler) は以下の属性とメソッドを持ちます。
:class:`Handler` は直接インスタンス化されることはありません;
このクラスはより便利なサブクラスの基底クラスとして働きます。
しかしながら、サブクラスにおける :meth:`__init__` メソッドでは、
:meth:`Handler.__init__` を呼び出す必要があります。


.. method:: Handler.__init__(level=NOTSET)

   レベルを設定して、 :class:`Handler` インスタンスを初期化します。
   空のリストを使ってフィルタを設定し、 I/O 機構へのアクセスを直列化するために
   (:meth:`createLock` を使って) ロックを生成します。


.. method:: Handler.createLock()

   スレッドセーフでない背後の I/O 機能に対するアクセスを直列化するために用いられる
   スレッドロック (thread lock) を初期化します。


.. method:: Handler.acquire()

   :meth:`createLock` で生成されたスレッドロックを獲得します。


.. method:: Handler.release()

   :meth:`acquire` で獲得したスレッドロックを解放します。


.. method:: Handler.setLevel(lvl)

   このハンドラに対する閾値を *lvl* に設定します。
   ログ記録しようとするメッセージで、 *lvl* よりも深刻でないものは無視されます。
   ハンドラが生成された際、レベルは :const:`NOTSET` (すべてのメッセージが処理される) に設定されます。


.. method:: Handler.setFormatter(form)

   このハンドラのフォーマッタを *form* に設定します。


.. method:: Handler.addFilter(filt)

   指定されたフィルタ *filt* をこのハンドラに追加します。


.. method:: Handler.removeFilter(filt)

   指定されたフィルタ *filt* をこのハンドラから除去します。


.. method:: Handler.filter(record)

   このハンドラのフィルタをレコードに適用し、レコードがフィルタを透過して処理されることになる場合には true 値を返します。


.. method:: Handler.flush()

   すべてのログ出力がフラッシュされるようにします。
   このクラスのバージョンではなにも行わず、サブクラスで実装するためのものです。


.. method:: Handler.close()

   ハンドラで使われているすべてのリソースの後始末を行います。
   このバージョンでは何も出力せず、 :func:`shutdown` が呼ばれたときに閉じられたハンドラを内部リストから削除します。
   サブクラスではオーバライドされた :meth:`close` メソッドからこのメソッドが必ず呼ばれるようにしてください。


.. method:: Handler.handle(record)

   ハンドラに追加されたフィルタの条件に応じて、指定されたログレコードを出力します。
   このメソッドは I/O スレッドロックの獲得/解放を伴う実際のログ出力をラップします。


.. method:: Handler.handleError(record)

   このメソッドは :meth:`emit` の呼び出し中に例外に遭遇した際にハンドラから呼び出されます。
   デフォルトではこのメソッドは何も行いません。すなわち、例外は暗黙のまま無視されます。
   ほとんどの場合、これがロギングシステムの望ましい動作です -
   というのは、ほとんどのユーザはロギングシステム自体のエラーは気にせず、
   むしろアプリケーションのエラーに興味があるからです。
   しかしながら、望むならこのメソッドを自作のハンドラと置き換えることもできます。
   *record* には、例外発生時に処理されていたレコードが入ります。


.. method:: Handler.format(record)

   レコードに対する書式化を行います - フォーマッタが設定されていれば、それを使います。
   そうでない場合、モジュールにデフォルト指定されたフォーマッタを使います。


.. method:: Handler.emit(record)

   指定されたログ記録レコードを実際にログ記録する際のすべての処理を行います。
   このメソッドはサブクラスで実装されることを意図しており、
   そのためこのクラスのバージョンは :exc:`NotImplementedError` を送出します。

標準として含まれているハンドラについては、 :mod:`logging.handlers` を
参照してください。

.. _formatter-objects:

フォーマッタオブジェクト
------------------------

.. currentmodule:: logging

フォーマッタ (:class:`Formatter`) は以下の属性とメソッドを持っています。
:class:`Formatter` は :class:`LogRecord` を (通常は) 人間か外部のシステムで解釈できる文字列に変換する役割を担っています。
基底クラスの :class:`Formatter` では書式化文字列を指定することができます。
何も指定されなかった場合、 ``'%(message)s'`` の値が使われます。

Formatter は :class:`LogRecord` 属性の知識を利用できるような書式化文字列を用いて初期化することができます。
例えば、上で言及したデフォルト値では、ユーザによるメッセージと引数はあらかじめ書式化されて、
:class:`LogRecord` の *message* 属性に入っていることを利用しています。
この書式化文字列は、 Python 標準の % を使った変換文字列で構成されます。
文字列整形に関する詳細は :ref:`string-formatting` を参照してください。

:class:`LogRecord`  の便利なマッピングキーは、 :ref:`logrecord-attributes`
の節で与えられます。


.. class:: Formatter(fmt=None, datefmt=None)

   :class:`Formatter` クラスの新たなインスタンスを返します。
   インスタンスは全体としてのメッセージに対する書式化文字列と、
   メッセージの日付/時刻部分のための書式化文字列を伴って初期化されます。
   *fmt*  が指定されない場合、 ``'%(message)s'`` が使われます。
   *datefmt* が指定されない場合、 ISO8601 日付書式が使われます。

   .. method:: format(record)

      レコードの属性辞書が、文字列を書式化する演算で被演算子として使われます。
      書式化された結果の文字列を返します。辞書を書式化する前に、二つの準備段階を経ます。
      レコードの *message* 属性が *msg* % *args* を使って処理されます。
      書式化された文字列が :const:`'(asctime)'` を含むなら、
      :meth:`formatTime` が呼び出され、イベントの発生時刻を書式化します。
      例外情報が存在する場合、 :meth:`formatException`  を使って書式化され、メッセージに追加されます。
      ここで注意していただきたいのは、書式化された例外情報は *exc_text* にキャッシュされるという点です。
      これが有用なのは例外情報がピックル化されて回線上を送ることができるからですが、
      しかし二つ以上の :class:`Formatter` サブクラスで例外情報の書式化をカスタマイズしている場合には注意が必要になります。
      この場合、フォーマッタが書式化を終えるごとにキャッシュをクリアして、
      次のフォーマッタがキャッシュされた値を使わずに新鮮な状態で再計算するようにしなければならないことになります。


   .. method:: formatTime(record, datefmt=None)

      このメソッドは、フォーマッタが書式化された時間を利用したい際に、 :meth:`format` から呼び出されます。
      このメソッドは特定の要求を提供するためにフォーマッタで上書きすることができますが、
      基本的な振る舞いは以下のようになります: *datefmt* (文字列) が指定された場合、
      レコードが生成された時刻を書式化するために :func:`time.strftime` で使われます。
      そうでない場合、 ISO8601 書式が使われます。結果の文字列が返されます。

      この関数は、ユーザが設定できる関数を使って、生成時刻をタプルに変換します。
      デフォルトでは、 :func:`time.localtime` が使われます。
      これを特定のフォーマッタインスタンスに対して変更するには、 ``converter``
      属性を :func:`time.localtime` や :func:`time.gmtime` と同じシグネチャを
      持つ関数に設定してください。これをすべてのフォーマッタに対して
      変更するには、例えばすべてのロギング時刻を GMT で表されるようにするには、
      ``Formatter`` クラスの ``converter`` 属性を設定してください。
      

   .. method:: formatException(exc_info)

      指定された例外情報 (:func:`sys.exc_info` が返すような標準例外のタプル) を文字列として書式化します。
      デフォルトの実装は単に :func:`traceback.print_exception` を使います。
      結果の文字列が返されます。

.. _filter:

フィルタオブジェクト
--------------------

``フィルタ (Filter)`` は、 ``ハンドラ`` や ``ロガー`` によって使われ、
レベルによって提供されるのよりも洗練されたフィルタリングを実現します。
基底のフィルタクラスは、ロガー階層構造内の特定地点の配下にあるイベントだけを
許可します。例えば、'A.B' で初期化されたフィルタは、ロガー 'A.B', 'A.B.C',
'A.B.C.D', 'A.B.D' 等によって記録されたイベントは許可しますが、 'A.BB', 'B.A.B'
などは許可しません。
空の文字列で初期化された場合、すべてのイベントを通過させます。


.. class:: Filter(name='')

   :class:`Filter` クラスのインスタンスを返します。
   *name* が指定されていれば、 *name* はロガーの名前を表します。
   指定されたロガーとその子ロガーのイベントがフィルタを通過できるようになります。
   *name* が指定されなければ、すべてのイベントを通過させます。


   .. method:: filter(record)

      指定されたレコードがログされているか？
      されていなければゼロを、されていればゼロでない値を返します。
      適切と判断されれば、このメソッドによってレコードはその場で修正されることがあります。

なお、ハンドラに取り付けられたフィルタは、ハンドラからイベントが
放出されるたびに参照されますが、ロガーに取り付けられたフィルタは、
イベントがハンドラに (:meth:`debug`, :meth:`info` などを使って) 記録されるたび
に参照されます。これにより、子孫のロガーで生成されたイベントは、
ロガーのフィルタ設定には、そのフィルタが子孫のロガーにも適用されるので
ない限り、フィルタされなくなります。

実際には、 ``Filter`` をサブクラス化する必要はありません。
同じ意味の ``filter`` メソッドを持つ、すべてのインスタンスを通せます。

フィルタは本来、レコードをレベルよりも洗練された基準に基づいてフィルタする
ために使われますが、それが取り付けられたハンドラやロガーによって処理される
レコードをすべて監視します。これは、特定のロガーやハンドラに処理された
レコードの数を数えたり、処理されている LogRecord の属性を追加、変更、削除
したりするときに便利です。もちろん、LogRecord を変更するには注意が必要ですが、
これにより、ログにコンテキスト情報を注入できます (:ref:`filters-contextual` を
参照してください)。

.. _log-record:

LogRecord オブジェクト
----------------------

:class:`LogRecord` インスタンスは、何かをログ記録するたびに :class:`Logger` に
よって生成されます。また、 :func:`makeLogRecord` を通して
(例えば、ワイヤを通して受け取られた pickle 化されたイベントから) 手動で
生成することも出来ます。


.. class:: LogRecord(name, level, pathname, lineno, msg, args, exc_info, func=None)

   ロギングされているイベントに適切なすべての情報を含みます。

   一時情報が :attr:`msg` と :attr:`args` に渡され、それらは ``msg % args``
   を使って組み合わされ、レコードの :attr:`message` 属性を生成します。

   :param name:  この LogRecord で表されるイベントをロギングするのに使われる
                 ロガーの名前です。
   :param level: このロギングイベントの数値のレベル (DEBUG, INFO などの
                 いずれか) です。なお、これは LogRecord の *2* つの属性
                 に変換されます。数値 ``levelno`` と、対応するレベル名
                 ``levelname`` です。
   :param pathname: ロギングを呼び出したソースファイルの完全なパス名です。
   :param lineno: ロギングを呼び出したソースファイルの行番号です。
   :param msg: イベント記述メッセージで、これは変数データのプレースホルダを持つ
               フォーマット文字列になり得ます。
   :param args: *msg* 引数と組み合わせてイベント記述を得るための
                変数データです。
   :param exc_info: 現在の例外情報を含む例外タプルか、利用できる例外情報が
                    ないなら *None* です。
   :param func: ロギングの呼び出しを行った関数またはメソッドの名前です。

   .. versionchanged:: 2.5
      *func* が追加されました。

   .. method:: getMessage()

      ユーザが供給した引数をメッセージに交ぜた後、
      この :class:`LogRecord` インスタンスへのメッセージを返します。
      ユーザがロギングの呼び出しに与えた引数が文字列でなければ、
      その引数に :func:`str` が呼ばれ、文字列に変換されます。
      これにより、 ``__str__`` メソッドが実際のフォーマット文字列を返せるような
      ユーザ定義のクラスをメッセージとして使えます。


.. _logrecord-attributes:

LogRecord 属性
--------------

LogRecord には幾つかの属性があり、そのほとんどはコンストラクタのパラメタから
得られます。(なお、LogRecord コンストラクタのパラメタと LogRecord 属性が
常に厳密に対応するわけではありません。) これらの属性は、レコードからのデータを
フォーマット文字列に統合するのに使えます。以下のテーブルに、
属性名、意味、そして % 形式フォーマット文字列における対応するプレースホルダを
(アルファベット順に) 列挙します。

+----------------+--------------------------+-----------------------------------------------+
| 属性名         | フォーマット             | 説明                                          |
+================+==========================+===============================================+
| args           | このフォーマットを自分で | ``msg`` に組み合わせて ``message`` を         |
|                | 使う必要はないでしょう。 | 生成するための引数のタプル。                  |
+----------------+--------------------------+-----------------------------------------------+
| asctime        | ``%(asctime)s``          | :class:`LogRecord` が生成された時刻を         |
|                |                          | 人間が読める書式で表したもの。                |
|                |                          | デフォルトでは "2003-07-08 16:49:45,896" 形式 |
|                |                          | (コンマ以降の数字は時刻のミリ秒部分) です。   |
+----------------+--------------------------+-----------------------------------------------+
| created        | ``%(created)f``          | :class:`LogRecord` が生成された時刻           |
|                |                          | (:func:`time.time` によって返される形式で)。  |
+----------------+--------------------------+-----------------------------------------------+
| exc_info       | このフォーマットを自分で | (``sys.exc_info`` 風の) 例外タプルか、        |
|                | 使う必要はないでしょう。 | 例外が起こっていなければ *None* 。            |
+----------------+--------------------------+-----------------------------------------------+
| filename       | ``%(filename)s``         | ``pathname`` のファイル名部分。               |
+----------------+--------------------------+-----------------------------------------------+
| funcName       | ``%(funcName)s``         | ロギングの呼び出しを含む関数の名前。          |
+----------------+--------------------------+-----------------------------------------------+
| levelname      | ``%(levelname)s``        | メッセージのための文字のロギングレベル        |
|                |                          | (``'DEBUG'``, ``'INFO'``, ``'WARNING'``,      |
|                |                          | ``'ERROR'``, ``'CRITICAL'``)。                |
+----------------+--------------------------+-----------------------------------------------+
| levelno        | ``%(levelno)s``          | メッセージのための数値のロギングレベル        |
|                |                          | (:const:`DEBUG`, :const:`INFO`,               |
|                |                          | :const:`WARNING`, :const:`ERROR`,             |
|                |                          | :const:`CRITICAL`)。                          |
+----------------+--------------------------+-----------------------------------------------+
| lineno         | ``%(lineno)d``           | ロギングの呼び出しが発せられたソース行番号    |
|                |                          | (利用できる場合のみ)。                        |
+----------------+--------------------------+-----------------------------------------------+
| module         | ``%(module)s``           | モジュール (``filename`` の名前部分)。        |
+----------------+--------------------------+-----------------------------------------------+
| msecs          | ``%(msecs)d``            | :class:`LogRecord` が生成された時刻の         |
|                |                          | ミリ秒部分。                                  |
+----------------+--------------------------+-----------------------------------------------+
| message        | ``%(message)s``          | ``msg % args`` として求められた、             |
|                |                          | ログメッセージ。 :meth:`Formatter.format` が  |
|                |                          | 呼び出されたときに設定されます。              |
+----------------+--------------------------+-----------------------------------------------+
| msg            | このフォーマットを自分で | 元のロギングの呼び出しで渡されたフォーマット  |
|                | 使う必要はないでしょう。 | 文字列。 ``args`` と合わせて、 ``message`` 、 |
|                |                          | または任意のオブジェクトを生成します          |
|                |                          | (:ref:`arbitrary-object-messages` 参照)。     |
+----------------+--------------------------+-----------------------------------------------+
| name           | ``%(name)s``             | ロギングに使われたロガーの名前。              |
+----------------+--------------------------+-----------------------------------------------+
| pathname       | ``%(pathname)s``         | ロギングの呼び出しが発せられたファイルの      |
|                |                          | 完全なパス名 (利用できる場合のみ)。           |
+----------------+--------------------------+-----------------------------------------------+
| process        | ``%(process)d``          | プロセス ID (利用可能な場合のみ)。            |
+----------------+--------------------------+-----------------------------------------------+
| processName    | ``%(processName)s``      | プロセス名 (利用可能な場合のみ)。             |
+----------------+--------------------------+-----------------------------------------------+
| relativeCreated| ``%(relativeCreated)d``  | logging モジュール が読み込まれた時刻に       |
|                |                          | 対する、LogRecord が生成された時刻を、        |
|                |                          | ミリ秒で表したもの。                          |
+----------------+--------------------------+-----------------------------------------------+
| thread         | ``%(thread)d``           | スレッド ID (利用可能な場合のみ)。            |
+----------------+--------------------------+-----------------------------------------------+
| threadName     | ``%(threadName)s``       | スレッド名 (利用可能な場合のみ)。             |
+----------------+--------------------------+-----------------------------------------------+

.. versionchanged:: 2.5
   *funcName* が追加されました。

.. _logger-adapter:

LoggerAdapter オブジェクト
--------------------------

:class:`LoggerAdapter` インスタンスは文脈情報をログ記録呼び出しに渡すのを簡単にするために使われます。
使い方の例は :ref:`文脈情報をログ記録出力に付加する <context-info>` を参照してください。

.. versionadded:: 2.6


.. class:: LoggerAdapter(logger, extra)

   内部で使う :class:`Logger` インスタンスと辞書風 (dict-like) オブジェクトで初期化した
   :class:`LoggerAdapter` のインスタンスを返します。

   .. method:: process(msg, kwargs)

      文脈情報を挿入するために、ログ記録呼び出しに渡されたメッセージおよび/またはキーワード引数に変更を加えます。
      ここでの実装は *extra* としてコンストラクタに渡されたオブジェクトを取り、
      'extra' キーを使って *kwargs* に加えます。
      返り値は (*msg*, *kwargs*) というタプルで、 (変更されているはずの) 渡された引数を含みます。

上のメソッドに加えて、 :class:`LoggerAdapter` は :class:`Logger` にあるすべてのログ記録メソッド、
すなわち :meth:`debug`, :meth:`info`, :meth:`warning`, :meth:`error`, :meth:`exception`,
:meth:`critical`, :meth:`log`,
:meth:`isEnabledFor`, :meth:`getEffectiveLevel`, :meth:`setLevel`,
:meth:`hasHandlers` をサポートします。
これらのメソッドは対応する :class:`Logger` のメソッドと同じ引数を取りますので、
二つの型を取り替えて使うことができます。

.. versionchanged:: 2.7
   :meth:`isEnabledFor` メソッドが :class:`LoggerAdapter` に追加されました。
   このメソッドは、下にあるロガーに委譲します。


スレッドセーフ性
----------------

logging モジュールは、クライアントで特殊な作業を必要としない限りスレッドセーフになっています。
このスレッドセーフ性はスレッドロックによって達成されています;
モジュールの共有データへのアクセスを直列化するためのロックが一つ存在し、
各ハンドラでも背後にある I/O へのアクセスを直列化するためにロックを生成します。

:mod:`signal` モジュールを使用して非同期シグナルハンドラを実装している場合、
そのようなハンドラからはログ記録を使用できないかもしれません。
これは、 :mod:`threading` モジュールにおけるロック実装が常にリエントラントではなく、
そのようなシグナルハンドラから呼び出すことができないからです。


モジュールレベル関数
--------------------

上で述べたクラスに加えて、いくつかのモジュールレベルの関数が存在します。


.. function:: getLogger([name])

   指定された名前のロガーを返します。名前が指定されていない場合、ロガー階層のルート (root) にあるロガーを返します。
   *name* を指定する場合には、通常は *"a"*, *"a.b"*, *"a.b.c.d"* といったドット区切りの階層的な名前にします。
   名前の付け方はログ機能を使う開発者次第です。

   与えられた名前に対して、この関数はどの呼び出しでも同じロガーインスタンスを返します。
   したがって、ロガーインスタンスをアプリケーションの各部でやりとりする必要はありません。


.. function:: getLoggerClass()

   標準の :class:`Logger` クラスか、最後に :func:`setLoggerClass` に渡したクラスを返します。
   この関数は、新たなクラス定義の中で呼び出して、カスタマイズした :class:`Logger` クラスのインストールが
   既に他のコードで適用したカスタマイズを取り消さないことを保証するために使われることがあります。
   例えば以下のようにします::

      class MyLogger(logging.getLoggerClass()):
          # ... override behaviour here


.. function:: debug(msg[, *args[, **kwargs]])

   レベル :const:`DEBUG` のメッセージをルートロガーで記録します。
   *msg* はメッセージの書式化文字列で、 *args* は *msg* に文字列書式化演算子を使って取り込むための引数です。
   (これは、書式化文字列の中でキーワードを使い、引数として単一の辞書を渡すことができる、ということを意味します。)

   キーワード引数 *kwargs* からは 2 つのキーワードが調べられます。
   一つ目は *exc_info* で、この値の評価値が false でない場合、例外情報をログメッセージに追加します。
   (:func:`sys.exc_info` の返す形式の) 例外情報を表すタプルが与えられていれば、それをメッセージに使います。
   それ以外の場合には、 :func:`sys.exc_info` を呼び出して例外情報を取得します。

   もう一つのキーワード引数は *extra* で、当該ログイベント用に作られる
   LogRecoed の __dict__ にユーザー定義属性を加えるのに使われる辞書を渡すために用いられます。
   これらの属性は好きなように使えます。たとえば、ログメッセージの一部にすることもできます。
   以下の例を見てください::

      FORMAT = "%(asctime)-15s %(clientip)s %(user)-8s %(message)s"
      logging.basicConfig(format=FORMAT)
      d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}
      logging.warning("Protocol problem: %s", "connection reset", extra=d)

   出力はこのようになります::

      2006-02-08 22:20:02,165 192.168.0.1 fbloggs  Protocol problem: connection reset

   *extra* で渡される辞書のキーはロギングシステムで使われているものと衝突しないようにしなければなりません。
   (どのキーがロギングシステムで使われているかについての詳細は :class:`Formatter` のドキュメントを参照してください。)

   これらの属性をログメッセージに使うことにしたなら、少し注意が必要です。
   上の例では、 'clientip' と 'user' が LogRecord の属性辞書に含まれていることを期待した書式化文字列で
   :class:`Formatter` がセットアップされています。
   もしこれらが欠けていると、書式化例外が発生してしまうためメッセージはログに残りません。
   したがってこの場合、常にこれらのキーを含む *extra* 辞書を渡す必要があります。

   このようなことは煩わしいかもしれませんが、この機能は限定された場面で使われるように意図しているものなのです。
   たとえば同じコードがいくつものコンテキストで実行されるマルチスレッドのサーバで、
   興味のある条件が現れるのがそのコンテキストに依存している
   (上の例で言えば、リモートのクライアント IP アドレスや認証されたユーザ名など)、というような場合です。
   そういった場面では、それ用の :class:`Formatter` が特定の :class:`Handler` と共に使われるというのはよくあることです。

   .. versionchanged:: 2.5
      *extra* が追加されました。


.. function:: info(msg[, *args[, **kwargs]])

   レベル :const:`INFO` のメッセージをルートロガーで記録します。
   引数は :func:`debug` と同じように解釈されます。


.. function:: warning(msg[, *args[, **kwargs]])

   レベル :const:`WARNING` のメッセージをルートロガーで記録します。
   引数は :func:`debug` と同じように解釈されます。


.. function:: error(msg[, *args[, **kwargs]])

   レベル :const:`ERROR` のメッセージをルートロガーで記録します。
   引数は :func:`debug` と同じように解釈されます。


.. function:: critical(msg[, *args[, **kwargs]])

   レベル :const:`CRITICAL` のメッセージをルートロガーで記録します。
   引数は :func:`debug` と同じように解釈されます。


.. function:: exception(msg[, *args])

   レベル :const:`ERROR` のメッセージをルートロガーで記録します。
   引数は :func:`debug` と同じように解釈されます。
   例外情報がログメッセージに追加されます。
   このメソッドは例外ハンドラからのみ呼び出されます。


.. function:: log(level, msg[, *args[, **kwargs]])

   レベル *level* のメッセージをルートロガーで記録します。
   その他の引数は :func:`debug` と同じように解釈されます。

   注意事項: Python の 2.7.1 や 3.2 以前のバージョンでは、上述のルートロガーに
   委譲するモジュールレベル関数は、スレッドが開始される *前に* ハンドラが
   ルートロガーに加えられるのでない限り、スレッド内で使 *わない* べきです。
   これらの便利な関数は、 :func:`basicConfig` を呼び出して、少なくとも 1 つの
   ハンドラが利用できることを保証します。以前のバージョンの Python では、
   これは (珍しい状況下で) ハンドラがルートロガーに複数回加えられ、
   それにより同じイベントに複数のメッセージが現れることにつながります。

.. function:: disable(lvl)

   すべてのロガーに対して、ロガー自体のレベルに優先するような上書きレベル *lvl* を与えます。
   アプリケーション全体にわたって一時的にログ出力を抑制する必要が生じた場合にはこの関数が有効です。
   その効果は、深刻度 *lvl* 以下のすべてのログ呼び出しを無効にすることです。
   そのためこの関数を値 INFO を伴って呼び出した場合、すべての INFO と DEBUG イベントは捨てられ、
   ロガーの実効レベルに従って優先度 WARNING 以上のものは処理されるでしょう。


.. function:: addLevelName(lvl, levelName)

   内部的な辞書の中でレベル *lvl* をテキスト *levelName* に関連付けます。
   これは例えば :class:`Formatter` でメッセージを書式化する際のように、
   数字のレベルをテキスト表現に対応付ける際に用いられます。
   この関数は自作のレベルを定義するために使うこともできます。
   使われるレベルに対する唯一の制限は、レベルは正の整数でなくてはならず、
   メッセージの深刻度が上がるに従ってレベルの数も上がらなくてはならないということです。

   ノート: 独自のレベルを定義することを考えているなら、 :ref:`custom-levels`
   の節をご覧ください。

.. function:: getLevelName(lvl)

   ログ記録レベル *lvl* のテキスト表現を返します。レベルが定義済みのレベル :const:`CRITICAL`, :const:`ERROR`,
   :const:`WARNING`, :const:`INFO`, :const:`DEBUG` のいずれかである場合、対応する文字列が返されます。
   :func:`addLevelName` を使ってレベルに名前を関連付けていた場合、 *lvl* に関連付けられた名前が返されます。
   定義済みのレベルに対応する数値を指定した場合、レベルに対応した文字列表現を返します。
   そうでない場合、文字列 "Level %s" % lvl を返します。


.. function:: makeLogRecord(attrdict)

   属性が *attrdict* で定義された、新しい :class:`LogRecord` インスタンスを生成して返します。
   この関数は、 pickle された :class:`LogRecord` 属性の辞書をソケットを介して送信し、
   受信端で :class:`LogRecord` インスタンスとして再構成する場合に便利です。


.. function:: basicConfig([**kwargs])

   デフォルトの :class:`Formatter` を持つ :class:`StreamHandler` を生成してルートロガーに追加し、
   ロギングシステムの基本的な環境設定を行います。
   関数 :func:`debug`, :func:`info`, :func:`warning`, :func:`error`, :func:`critical` は、
   ルートロガーにハンドラが定義されていない場合に自動的に :func:`basicConfig` を呼び出します。

   この関数はルートロガーに設定されたハンドラがあれば何もしません。

   .. versionchanged:: 2.4
      以前は :func:`basicConfig` はキーワード引数を取りませんでした。

   注意事項: この関数は、他のスレッドが開始する前に、メインスレッドから
   呼ばれるべきです。Python の 2.7.1 や 3.2 以前のバージョンでは、
   この関数が複数のスレッドから呼び出されると、(珍しい状況下で)
   これは (珍しい状況下で) ハンドラがルートロガーに複数回加えられ、
   ログにメッセージが重複して現れるなど、予期せぬ結果につながります。

   以下のキーワード引数がサポートされます。

   +--------------+----------------------------------------------------------------------+
   | Format       | 説明                                                                 |
   +==============+======================================================================+
   | ``filename`` | StreamHandler ではなく指定された名前で FileHandler                   |
   |              | が作られます                                                         |
   +--------------+----------------------------------------------------------------------+
   | ``filemode`` | filename が指定されているとき、ファイルモードを指定します            |
   |              | (filemode が指定されない場合デフォルトは 'a' です)                   |
   +--------------+----------------------------------------------------------------------+
   | ``format``   | 指定された書式化文字列をハンドラで使います                           |
   +--------------+----------------------------------------------------------------------+
   | ``datefmt``  | 指定された日付/時刻の書式を使います                                  |
   +--------------+----------------------------------------------------------------------+
   | ``level``    | ルートロガーのレベルを指定されたものにします                         |
   +--------------+----------------------------------------------------------------------+
   | ``stream``   | 指定されたストリームを StreamHandler の初期化に使います。この引数は  |
   |              | 'filename' と同時には使えないことに注意してください。                |
   |              | 両方が指定されたときには 'stream' は無視されます                     |
   +--------------+----------------------------------------------------------------------+


.. function:: shutdown()

   ロギングシステムに対して、バッファのフラッシュを行い、
   すべてのハンドラを閉じることで順次シャットダウンを行うように告知します。
   この関数はアプリケーションの終了時に呼ばれるべきであり、
   また呼び出し以降はそれ以上ロギングシステムを使ってはなりません。


.. function:: setLoggerClass(klass)

   ロギングシステムに対して、ロガーをインスタンス化する際にクラス *klass* を使うように指示します。
   指定するクラスは引数として名前だけをとるようなメソッド :meth:`__init__` を定義していなければならず、
   :meth:`__init__` では :meth:`Logger.__init__` を呼び出さなければなりません。
   典型的な利用法として、この関数は自作のロガーを必要とするようなアプリケーションにおいて、
   他のロガーがインスタンス化される前にインスタンス化されます。


warnings モジュールとの統合
---------------------------

:func:`captureWarnings` 関数をつかって、 :mod:`logging` を :mod:`warnings`
モジュールと統合できます。

.. function:: captureWarnings(capture)

   この関数は、 logging による警告の補足を、有効にまたは無効にします。

   *capture* が ``True`` なら、 :mod:`warnings` モジュールに発せられた警告は、
   ロギングシステムにリダイレクトされるようになります。
   具体的には、警告が :func:`warnings.formatwarning` でフォーマット化され、
   結果の文字列が 'py.warnings' という名のロガーに、 `WARNING` の
   重大度でロギングされるようになります。

   *capture* が ``False`` なら、警告のロギングシステムに対するリダイレクトは
   止められ、警告は元の
   (すなわち、 `captureWarnings(True)` が呼び出される前に有効だった)
   送信先にリダイレクトされるようになります。


.. seealso::

   Module :mod:`logging.config`
      logging モジュールの環境設定 API です。

   Module :mod:`logging.handlers`
      logging モジュールに含まれる、便利なハンドラです。

   :pep:`282` - A Logging System
      この機能を Python 標準ライブラリに含めることを述べた提案です。

   `Original Python logging package <http://www.red-dove.com/python_logging.html>`_
      これは、 :mod:`logging` パッケージのオリジナルのソースです。
      このサイトから利用できるバージョンのパッケージは、
      :mod:`logging` パッケージを標準ライブラリに含まない、
      Python 1.5.2, 2.1.x および 2.2.x で使うのに適しています。


