# `logging` --- Logging facility for Python

ソースコード: Lib/logging/__init__.py

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

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

以下は慣用的な使い方の単純な例です:

    # myapp.py
    import logging
    import mylib
    logger = logging.getLogger(__name__)

    def main():
        logging.basicConfig(filename='myapp.log', level=logging.INFO)
        logger.info('Started')
        mylib.do_something()
        logger.info('Finished')

    if __name__ == '__main__':
        main()

    # mylib.py
    import logging
    logger = logging.getLogger(__name__)

    def do_something():
        logger.info('Doing something')

myapp.py を実行すれば、myapp.log でログが確認できます:

    INFO:__main__:Started
    INFO:mylib:Doing something
    INFO:__main__:Finished

The key features of this idiomatic usage is that the majority of code is simply creating a module level logger with `getLogger(__name__)`, and using that logger to do any needed logging. This is concise while allowing downstream code fine grained control if needed. Logged messages to the module-level logger get forwarded up to handlers of loggers in higher-level modules, all the way up to the root logger; for this reason this approach is known as hierarchical logging.

ロギングを有用なものとするためには、用途に応じて構成する必要があります: ログレベルの設定や各ロガーの出力先から、潜在的には特定のモジュールに対する振る舞いの変更などを、しばしばコマンドライン引数かアプリケーションの構成の一部として。上記の例を含めて、ほとんどの場合ではルートロガーのみを構成するだけで十分です。なぜならモジュールレベルの全ての下位のロガーは、全てのメッセージを最終的にルートロガーのハンドラに転送するからです。 `basicConfig()` は、多くのユースケースを上手に扱うことのできる簡便なルートロガーの構成方法を提供します。

このモジュールは、多くの機能性と柔軟性を提供します。ロギングに慣れていないなら、使い方を理解する最良の方法はチュートリアルを読むことです (右上のリンクを参照してください)。

The basic classes defined by the module, together with their functions, are listed below.

- ロガーは、アプリケーションコードが直接使うインターフェースを公開します。

- ハンドラは、(ロガーによって生成された) ログ記録を適切な送信先に送ります。

- フィルタは、どのログ記録を出力するかを決定する、きめ細かい機能を提供します。

- フォーマッタは、ログ記録が最終的に出力されるレイアウトを指定します。

## ロガーオブジェクト

ロガーには以下のような属性とメソッドがあります。 ロガーを直接インスタンス化することは 絶対に してはならず、常にモジュール関数 `logging.getLogger(name)` を介してインスタンス化することに注意してください。 同じ name で `getLogger()` を複数回呼び出すと、常に同じロガー・オブジェクトへの参照が返されます。

The `name` is potentially a period-separated hierarchical value, like `foo.bar.baz` (though it could also be just plain `foo`, for example). Loggers that are further down in the hierarchical list are children of loggers higher up in the list. For example, given a logger with a name of `foo`, loggers with names of `foo.bar`, `foo.bar.baz`, and `foo.bam` are all descendants of `foo`. The logger name hierarchy is analogous to the Python package hierarchy, and identical to it if you organise your loggers on a per-module basis using the recommended construction `logging.getLogger(__name__)`. That's because in a module, `__name__` is the module's name in the Python package namespace.

class logging.Logger
  name

    ロガーの名前です。また、ロガーを取得するために `getLogger()` を呼び出すときに渡された値です。

    注釈

    この属性は読み出し専用として扱われるべきです。

  level

    `setLevel()` メソッドで設定された、このロガーのしきい値です。

    注釈

    この属性を直接設定しないでください - `setLevel()` は渡されたレベルをチェックする機能を持っていますので、常にこのメソッドを使うようにしてください。

  parent

    このロガーの親にあたるロガーです。名前空間の階層構造で上位にあたるロガーのインスタンス化により、親ロガーは変わる可能性があります。

    注釈

    この値は読み出し専用として取り扱われるべきです。

  propagate

    この属性が真と評価された場合、このロガーに記録されたイベントは、このロガーに取り付けられた全てのハンドラに加え、上位 (祖先) ロガーのハンドラにも渡されます。 メッセージは、祖先ロガーのハンドラに直接渡されます - 今問題にしている祖先ロガーのレベルもフィルタも、どちらも考慮されません。

    この値の評価結果が偽になる場合、ロギングメッセージは祖先ロガーのハンドラに渡されません。

    具体的な例で説明します: `A.B.C` という名前のロガーの propagate 属性が真と評価された場合、 `logging.getLogger('A.B.C').error(...)` のようなメソッドの呼び出しを通じて `A.B.C` に記録された全てのイベントは、 [ログレベルとフィルタの設定を満たした場合に限り] 最初に `A.B.C` に接続されたハンドラに渡され、その後 `A.B`, `A` という名前のロガー、そしてルートロガーという順番で各ロガーに接続されたハンドラに渡されます。この連鎖構造において `A.B.C`, `A.B`, `A` のいずれかの `propagate` 属性が偽に設定された場合、そのロガーがイベントを処理する最後のロガーとなり、その時点でイベントの伝播は止まります。

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

    注釈

    ハンドラを、あるロガー と その祖先のロガーに接続した場合、同一レコードが複数回発行される場合があります。一般的に、ハンドラを複数のロガーに接続する必要はありません。propagate 設定が `True` のままになっていれば、ロガーの階層において最上位にある適切なロガーにハンドラを接続するだけで、そのハンドラは全ての子孫ロガーが記録する全てのイベントを確認することができます。一般的なシナリオでは、ハンドラをルートロガーに対してのみ接続し、残りは propagate にすべて委ねます。

  handlers

    このロガーインスタンスに直接接続されているハンドラのリストです。

    注釈

    この属性は読み出し専用として取り扱われるべきです; 通常この属性は `addHandler()` と `removeHandler()` の2つのメソッドを介して変更されます。これらのメソッドはスレッドセーフな処理を保証するためにロックを活用します。

  disabled

    この属性は、いかなるイベントの処理も作動しないようにします。イニシャライザはこの属性に `False` を設定します。また、この属性はロギングを設定するコードによってのみ変更されます。

    注釈

    この属性は読み出し専用として扱われるべきです。

  setLevel(level)

    このロガーの閾値を level に設定します。 level よりも深刻でないログメッセージは無視されます; 深刻さが level 以上のログメッセージは、ハンドラのレベルが level より上に設定されていない限り、このロガーに取り付けられているハンドラによって投げられます。

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

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

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

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

    レベルの一覧については ロギングレベル を参照してください。

    バージョン 3.2 で変更: level パラメータは、 `INFO` のような整数定数の代わりに 'INFO' のようなレベルの文字列表現も受け付けるようになりました。ただし、レベルは内部で整数として保存されますし、 `getEffectiveLevel()` や `isEnabledFor()` といったメソッドは、整数を返し、また渡されるものと期待します。

  isEnabledFor(level)

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

  getEffectiveLevel()

    このロガーの実効レベルを示します。 `NOTSET` 以外の値が `setLevel()` で設定されていた場合、その値が返されます。そうでない場合、 `NOTSET` 以外の値が見つかるまでロガーの階層をルートロガーの方向に追跡します。見つかった場合、その値が返されます。返される値は整数で、典型的には `logging.DEBUG`, `logging.INFO` 等のうち一つです。

  getChild(suffix)

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

    バージョン 3.2 で追加.

  debug(msg, *args, **kwargs)

    レベル `DEBUG` のメッセージをこのロガーで記録します。 msg はメッセージの書式文字列で、 args は msg に文字列書式化演算子を使って取り込むための引数です。 (これは、書式化文字列の中でキーワードを使い、引数として単一の辞書を渡すことができる、ということを意味します。) args が提供されない場合は msg の%フォーマットは実行されません。

    kwargs のうち、 exc_info, stack_info, stacklevel, extra という4つのキーワード引数の中身を調べます。

    exc_info は、この値の評価値が false でない場合、例外情報がロギングメッセージに追加されます。もし例外情報をあらわすタプル(`sys.exc_info()` 関数によって戻されるフォーマットにおいて)、または、例外情報をあらわすインスタンスが与えられていれば、それが使用されることになります。それ以外の場合には、 `sys.exc_info()` を呼び出して例外情報を取得します。

    2つ目の省略可能なキーワード引数は stack_info で、デフォルトは `False` です。真の場合、実際のロギング呼び出しを含むスタック情報がロギングメッセージに追加されます。これは exc_info 指定によって表示されるスタック情報と同じものではないことに注意してください: 前者はカレントスレッド内での、一番下からロギング呼び出しまでのスタックフレームですが、後者は例外に呼応して、例外ハンドラが見つかるところまで巻き戻されたスタックフレームの情報です。

    exc_info とは独立に stack_info を指定することもできます (例えば、例外が上げられなかった場合でも、コード中のある地点にどのように到着したかを単に示すために)。スタックフレームは、次のようなヘッダー行に続いて表示されます:

        Stack (most recent call last):

    これは、例外フレームを表示する場合に使用される `Traceback (most recent call last):` を模倣します。

    3番目のオプションキーワード引数は stacklevel で、デフォルトは `1` です。もしこれが1よりも大きい場合は、 `LogRecord` 内で行番号と関数名を算出する時に、指定されたスタックフレームの数をスキップします。これはログヘルパー内部で使われる場合、関数名、ファイル名、行番号はそのヘルパーの情報ではなく、そのヘルパーを呼び出した呼び出し元のものになります。このパラメータの名前は `warnings` モジュールと同じものになります。

    The fourth keyword argument is extra which can be used to pass a dictionary which is used to populate the __dict__ of the `LogRecord` created for the logging event with user-defined attributes. These custom attributes can then be used as you like. For example, they could be incorporated into logged messages. For example:

        FORMAT = '%(asctime)s %(clientip)-15s %(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 に渡される辞書のキーはロギングシステムで使われているものと衝突してはいけません。 (ロギングシステムが使うキーの詳細については LogRecord 属性 の節を参照してください。)

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

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

    If no handler is attached to this logger (or any of its ancestors, taking into account the relevant `Logger.propagate` attributes), the message will be sent to the handler set on `lastResort`.

    バージョン 3.2 で変更: stack_info パラメータが追加されました。

    バージョン 3.5 で変更: exc_info パラメータは例外インスタンスを受け入れることが可能です。

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

  info(msg, *args, **kwargs)

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

  warning(msg, *args, **kwargs)

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

    注釈

    `warning` と機能的に等価な古いメソッド `warn` があります。`warn` は廃止予定なので使わないでください - 代わりに `warning` を使ってください。

  error(msg, *args, **kwargs)

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

  critical(msg, *args, **kwargs)

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

  log(level, msg, *args, **kwargs)

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

  exception(msg, *args, **kwargs)

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

  addFilter(filter)

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

  removeFilter(filter)

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

  filter(record)

    レコードに対してこのロガーのフィルタを適用し、レコードが処理されるべき場合に `True` を返します。フィルタのいずれかの値が偽を返すまで、それらは順番に試されていきます。いずれも偽を返さなければ、レコードは処理される(ハンドラに渡される)ことになります。ひとつでも偽を返せば、発生したレコードはもはや処理されることはありません。

  addHandler(hdlr)

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

  removeHandler(hdlr)

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

  findCaller(stack_info=False, stacklevel=1)

    呼び出し元のソースファイル名と行番号を調べます。ファイル名と行番号、関数名、スタック情報を 4 要素のタプルで返します。stack_info が `True` でなければ、スタック情報は `None` が返されます。

    stacklevel パラメータは `debug()` や他のAPIを呼び出すコードから渡されます。もしこれが1よりも大きい場合は、その超過分は返す値を決定する前にスタックフレームをスキップする数として利用されます。これは通常、ログAPIをヘルパーやラッパー経由で呼び出す場合に便利です。こうすることで、イベントログに記録される情報はヘルパーやラッパーのコードではなく、それらを呼び出しているコードのものとなります。

  handle(record)

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

  makeRecord(name, level, fn, lno, msg, args, exc_info, func=None, extra=None, sinfo=None)

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

  hasHandlers()

    このロガーにハンドラが設定されているかどうかを調べます。 そのために、このロガーとロガー階層における祖先からハンドラを探します。 ハンドラが見つかれば `True` 、そうでなければ `False` を返します。 このメソッドは、'propagate' 属性が偽に設定されたロガーを見つけると、さらに上位の探索をやめます。そのロガーが、ハンドラが存在するかどうかチェックされる最後のロガーになります。

    バージョン 3.2 で追加.

  バージョン 3.7 で変更: ロガーの pickle 化と unpickle 化ができるようになりました。

## ロギングレベル

ログレベルの数値は以下の表のように与えられています。これらは基本的に自分でレベルを定義したい人のためのもので、定義するレベルを既存のレベルの間に位置づけるためには具体的な値が必要になります。もし数値が他のレベルと同じだったら、既存の値は上書きされその名前は失われます。

レベル | 数値 | どういう意味か / いつ使用するべきか
--- | --- | ---
logging.NOTSET | 0 | ロガーに対してこのレベルが設定された場合、実際のログレベルは祖先のロガーを参照して決めることを意味します。実効ログレベルも `NOTSET` となった場合は、全てのイベントが記録されます。ハンドラーに対してこのレベルが設定された場合、全てのイベントが処理されます。
logging.DEBUG | 10 | 詳細情報。典型的には、問題が発生した際に原因を突き止めようとする開発者向けの情報。
logging.INFO | 20 | 想定された通りのことが起こったことの確認。
logging.WARNING | 30 | 想定外の事象、または近い将来に問題が起きる可能性 (たとえば 'disk space low' すなわちディスク空き容量の低下) の表示。ソフトウエアは引き続き期待通りに動作している状態。
logging.ERROR | 40 | より重大な問題により、ソフトウェアがある機能を実行できないこと。
logging.CRITICAL | 50 | プログラム自体が実行を続けられないことを表す、重大なエラー。

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

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

class logging.Handler
  __init__(level=NOTSET)

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

  createLock()

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

  acquire()

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

  release()

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

  setLevel(level)

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

    レベルの一覧については ロギングレベル を参照してください。

    バージョン 3.2 で変更: level パラメータは、 `INFO` のような整数定数の代わりに 'INFO' のようなレベルの文字列表現も受け付けるようになりました。

  setFormatter(fmt)

    Sets the `Formatter` for this handler to fmt.

  addFilter(filter)

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

  removeFilter(filter)

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

  filter(record)

    レコードに対してこのハンドラのフィルタを適用し、レコードが処理されるべき場合に `True` を返します。フィルタのいずれかの値が偽を返すまで、それらは順番に試されていきます。いずれも偽を返さなければ、レコードは発行されることになります。ひとつでも偽を返せば、ハンドラはレコードを発行しません。

  flush()

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

  close()

    Tidy up any resources used by the handler. This version does no output but removes the handler from an internal list of handlers which is closed when `shutdown()` is called. Subclasses should ensure that this gets called from overridden `close()` methods.

  handle(record)

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

  handleError(record)

    このメソッドは、 `emit()` の呼び出し中に例外に遭遇した際にハンドラから呼び出されることを想定しています。モジュールレベルの属性 `raiseExceptions` が `False` の場合、例外は静かに無視されます。これは、ほとんどの場合でロギングシステムに期待される挙動です - なぜなら、ほとんどのユーザーはロギングシステムの中で起こったエラーなどに興味はなく、アプリケーションエラーの方により関心があるからです。しかし、必要ならばこの挙動を自作のハンドラで置き換えることができます。引数に指定されたレコードは例外発生時に処理されるものです。 (`raiseExceptions` のデフォルト値は、開発中にはその方が便利なので、 `True` です)。

  format(record)

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

  emit(record)

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

    警告

    このメソッドはハンドラレベルのロックを取得した後で呼び出されます。また、ロックはこのメソッドがリターンした後で解放されます。このメソッドをオーバーライドする場合、ロックを取得する可能性のある logging API の他の関数やメソッドの呼び出しに注意してください。そのような実装はデッドロックを引き起こす可能性があります。特に以下の点に注意してください:

    - ロギングを構成するための API はモジュールレベルのロックを取得し、その後ハンドラを構成する際に個々のハンドラに対してハンドラレベルのロックを取得します。

    - 多くのロギング API はモジュールレベルのロックを取得します。そのような API がこのメソッドから呼ばれた場合、他のスレッドからロギングを構成するための API 呼び出しが行われたときにデッドロックに陥る可能性があります。これは他のスレッドがハンドラレベルのロックを取得する 前に モジュールレベルのロックを取得しようとする一方で、 (このメソッドはハンドラレベルのロックが既に取得された状態で呼び出されているため) このメソッドを呼び出したスレッドはハンドラレベルのロックを取得した 後で モジュールレベルのロックを取得しようとするためです。

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

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

`Formatter` objects have the following attributes and methods. They are responsible for converting a `LogRecord` to (usually) a string which can be interpreted by either a human or an external system. The base `Formatter` allows a formatting string to be specified. If none is supplied, the default value of `'%(message)s'` is used, which just includes the message in the logging call. To have additional items of information in the formatted output (such as a timestamp), keep reading.

A Formatter can be initialized with a format string which makes use of knowledge of the `LogRecord` attributes - such as the default value mentioned above making use of the fact that the user's message and arguments are pre-formatted into a `LogRecord`'s message attribute. This format string contains standard Python %-style mapping keys. See section printf 形式の文字列書式化 for more information on string formatting.

The useful mapping keys in a `LogRecord` are given in the section on LogRecord 属性.

class logging.Formatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

  Returns a new instance of the `Formatter` class. The instance is initialized with a format string for the message as a whole, as well as a format string for the date/time portion of a message. If no fmt is specified, `'%(message)s'` is used. If no datefmt is specified, a format is used which is described in the `formatTime()` documentation.

  The style parameter can be one of '%', '{' or '$' and determines how the format string will be merged with its data: using one of %-formatting, `str.format()` or `string.Template`. This only applies to the format string fmt (e.g. `'%(message)s'` or `{message}`), not to the actual log messages passed to `Logger.debug` etc; see 固有の書式化スタイルをアプリケーション全体で使う for more information on using {- and $-formatting for log messages.

  The defaults parameter can be a dictionary with default values to use in custom fields. For example: `logging.Formatter('%(ip)s %(message)s', defaults={"ip": None})`

  バージョン 3.2 で変更: The style parameter was added.

  バージョン 3.8 で変更: The validate parameter was added. Incorrect or mismatched style and fmt will raise a `ValueError`. For example: `logging.Formatter('%(asctime)s - %(message)s', style='{')`.

  バージョン 3.10 で変更: The defaults parameter was added.

  format(record)

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

    スタック情報が利用可能な場合、(必要ならば `formatStack()` を使って整形した上で) スタック情報が例外情報の後に追加されます。

  formatTime(record, datefmt=None)

    このメソッドは、フォーマッタが書式化された時間を利用したい際に、 `format()` から呼び出されます。 このメソッドは特定の要求を提供するためにフォーマッタで上書きすることができますが、基本的な振る舞いは以下のようになります: datefmt (文字列) が指定された場合、レコードが生成された時刻を書式化するために `time.strftime()` で使われます。 そうでない場合、 '%Y-%m-%d %H:%M:%S,uuu' というフォーマットが使われます。 uuu 部分はミリ秒値で、それ以外の文字は `time.strftime()` ドキュメントに従います。 このフォーマットの時刻の例は `2003-01-23 00:29:50,411` です。 結果の文字列が返されます。

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

    バージョン 3.3 で変更: 以前は、デフォルトのフォーマットがこの例のようにハードコーディングされていました: `2010-09-06 22:38:15,292` ここで、コンマの前の部分は strptime フォーマット文字列 (`'%Y-%m-%d %H:%M:%S'`) によって扱われる部分で、コンマの後の部分はミリ秒値です。strptime にミリ秒のフォーマットプレースホルダーがないので、ミリ秒値は別のフォーマット文字列 `'%s,%03d'` を使用して追加されます。そして、これらのフォーマット文字列は両方ともこのメソッドでハードコーディングされていました。変更後は、これらの文字列はクラスレベル属性として定義され、必要ならインスタンスレベルでオーバーライドすることができます。属性の名前は `default_time_format` (strptime 書式文字列用) と `default_msec_format` (ミリ秒値の追加用) です。

    バージョン 3.9 で変更: `default_msec_format` 引数が `None` であることを許容します。

  formatException(exc_info)

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

  formatStack(stack_info)

    指定されたスタック情報を文字列としてフォーマットします (`traceback.print_stack()` によって返される文字列ですが、最後の改行が取り除かれています)。このデフォルト実装は、単に入力値をそのまま返します。

class logging.BufferingFormatter(linefmt=None)

  複数のレコードをまとめてフォーマットしたい場合のクラス定義に適した基底クラスです。各行 (単一のレコードに相当します) をフォーマットするために使う `Formatter` インスタンスを渡すことができます。特に指定がない場合はデフォルトのフォーマッタ (イベントのメッセージだけを出力するフォーマッタ) が使われます。

  formatHeader(records)

    複数のレコード のリストに対するヘッダを返します。基底クラスの実装は単に空の文字列を返すだけです。レコード数やタイトルを表示したり、あるいはセパレータ行したいなど、ヘッダに対して特別な振る舞いが必要な場合はこのメソッドをオーバーライドする必要があります。

  formatFooter(records)

    複数のレコード のリストに対するフッタを返します。基底クラスの実装は単に空の文字列を返すだけです。レコード数やセパレータ行の表示など、フッタに対して特別な振る舞いが必要な場合はこのメソッドをオーバーライドする必要があります。

  format(records)

    複数のレコード のリストに対するフォーマット済みテキストを返します。基底クラスの実装は、レコードがなければ空の文字列を返し、レコードがある場合はヘッダ、単一のレコードをフォーマットするためのラインフォーマッタで各レコードをフォーマットした文字列、そしてフッタを全て連結したものを返します。

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

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

class logging.Filter(name='')

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

  filter(record)

    Is the specified record to be logged? Returns zero for no, nonzero for yes. If deemed appropriate, the record may be modified in-place by this method.

ハンドラに対するフィルタはハンドラがイベントを発行する前に試され、一方ではロガーに対するフィルタは、イベントが(`debug()`, `info()` などによって)ロギングされる際には、ハンドラにイベントが送信される前にはいつでも試されることに注意してください。そのフィルタがそれら子孫ロガーにも適用されていない限り、子孫ロガーによって生成されたイベントはロガーのフィルタ設定によってフィルタされることはありません。

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

バージョン 3.2 で変更: 特殊な `Filter` クラスを作ったり、 `filter` メソッドを持つ他のクラスを使う必要はありません: 関数 (あるいは他の callable) をフィルタとして使用することができます。フィルタロジックは、フィルタオブジェクトが `filter` 属性を持っているかどうかチェックします: もし `filter` 属性を持っていたら、それは `Filter` であると仮定され、その `filter()` メソッドが呼び出されます。そうでなければ、それは callable であると仮定され、レコードを単一のパラメータとして呼び出されます。返される値は `filter()` によって返されるものと一致すべきです。

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

## LogRecord オブジェクト

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

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

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

  もっとも重要な情報は msg と args に渡され、 `msg % args` で結合されてレコードの `message` 属性を生成します。

  パラメータ:

    - name (str) -- この `LogRecord` であらわされるイベントを記録したロガーの名前です。 `LogRecord` が持つロガーの名前は、たとえ異なる (祖先の) ロガーに接続されたハンドラから出力されたとしても、常に同じ値を持つことに注意してください。

    - level (int) -- 記録されたイベントの 数値であらわしたロギングレベル (`10` が `DEBUG`, `20` が `INFO` など) です。このパラメータは LogRecord の 2つの 属性に変換されることに注意してください: 数値は `levelno` に、また対応するログレベルの名前は `levelname` に保持されます。

    - pathname (str) -- ロギングの呼び出しが行われたソースファイルへの完全なパス名をあらわす文字列です。

    - lineno (int) -- ロギングの呼び出しが発せられたソース行番号。

    - msg (Any) -- イベントの説明メッセージ。様々なデータのプレースホルダを含んだ %フォーマット文字列か、任意のオブジェクト (任意のオブジェクトをメッセージに使用する を参照)。

    - args (tuple | dict[str, Any]) -- msg 引数と組み合わせてイベント記述を得るための変数データです。

    - exc_info (tuple[type[BaseException], BaseException, types.TracebackType] | None) -- `sys.exc_info()` によって返される現在の例外情報を含む例外タプルです。例外情報がない場合は `None` です。

    - func (str | None) -- ロギングの呼び出しを行った関数またはメソッドの名前です。

    - sinfo (str | None) -- 現在のスレッドのスタックベースからログ呼び出しまでの間のスタック情報を表わすテキスト文字列。

  getMessage()

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

  バージョン 3.2 で変更: `LogRecord` の生成は、レコードを生成するために使用されるファクトリを提供することにより、さらに設定可能になりました。ファクトリは `getLogRecordFactory()` と `setLogRecordFactory()` を使用して設定することができます (ファクトリのシグネチャに関しては `setLogRecordFactory()` を参照)。

  この機能を使うと `LogRecord` の生成時に独自の値を注入することができます。次のパターンが使えます:

      old_factory = logging.getLogRecordFactory()

      def record_factory(*args, **kwargs):
          record = old_factory(*args, **kwargs)
          record.custom_attribute = 0xdecafbad
          return record

      logging.setLogRecordFactory(record_factory)

  このパターンでは複数のファクトリをつなぐこともできます。それらが互いの属性を上書きしたりせず、また上にリストされた標準属性を意図せず上書きしたりしない限り、驚くようなことは何も起こりません (there should be no surprises)。

## LogRecord 属性

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

{}-フォーマット (`str.format()`) を使用していれば、書式文字列の中でプレースホールダーとして `{attrname}` を使うことができます。 $-フォーマット (`string.Template`) を使用している場合は、 `${attrname}` 形式にしてください。もちろん、両方の場合で `attrname` は使用したい実際の属性名に置き換えてください。

{}-フォーマットの場合には、属性名の後にフォーマットフラグを指定することができます。属性名とフォーマットフラグの間はコロンで分割します。例: プレースホールダー `{msecs:03.0f}` は、ミリセカンド値 `4` を `004` としてフォーマットします。利用可能なオプション上の全詳細に関しては `str.format()` ドキュメンテーションを参照してください。

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

バージョン 3.1 で変更: processName が追加されました。

## LoggerAdapter オブジェクト

`LoggerAdapter` インスタンスは文脈情報をログ記録呼び出しに渡すのを簡単にするために使われます。使い方の例は コンテキスト情報をログ記録出力に付加する を参照してください。

class logging.LoggerAdapter(logger, extra)

  Returns an instance of `LoggerAdapter` initialized with an underlying `Logger` instance and a dict-like object.

  process(msg, kwargs)

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

  manager

    Delegates to the underlying `manager`` on logger.

  _log

    Delegates to the underlying `_log`()` method on logger.

  `LoggerAdapter` は上記に加え `Logger` のメソッド `debug()`, `info()`, `warning()`, `error()`, `exception()`, `critical()`, `log()`, `isEnabledFor()`, `getEffectiveLevel()`, `setLevel()`, `hasHandlers()` をサポートします。これらは `Logger` の対応するメソッドと同じシグニチャを持つため、2つのインスタンスは区別せずに利用出来ます。

  バージョン 3.2 で変更: `isEnabledFor()`, `getEffectiveLevel()`, `setLevel()`, `hasHandlers()` が `LoggerAdapter` に追加されました。これらメソッドは元のロガーに処理を委譲します。

  バージョン 3.6 で変更: 基底のロガーに移譲し、アダプターをネストできるようにするために `manager` 属性と `_log()` メソッドが追加されました。

## スレッドセーフ性

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

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

## モジュールレベルの関数

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

logging.getLogger(name=None)

  Return a logger with the specified name or, if name is `None`, return a logger which is the root logger of the hierarchy. If specified, the name is typically a dot-separated hierarchical name like 'a', 'a.b' or 'a.b.c.d'. Choice of these names is entirely up to the developer who is using logging.

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

logging.getLoggerClass()

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

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

logging.getLogRecordFactory()

  `LogRecord` を生成するのに使われる callable を返します。

  バージョン 3.2 で追加: この関数は、ログイベントを表現する `LogRecord` の構築方法に関して開発者により多くのコントロールを与えるため、 `setLogRecordFactory()` とともに提供されました。

  このファクトリがどのように呼ばれるかに関する詳細は `setLogRecordFactory()` を参照してください。

logging.debug(msg, *args, **kwargs)

  ルートロガーの `Logger.debug()` メソッドを呼び出す便利関数です。引数の取り扱いはあらゆる点で当該メソッドと同じです。

  唯一の違いはルートロガーがハンドラを持たない場合で、この場合はルートロガーの `debug` メソッドを呼び出す前に `basicConfig()` が呼ばれます。

  For very short scripts or quick demonstrations of `logging` facilities, `debug` and the other module-level functions may be convenient. However, most programs will want to carefully and explicitly control the logging configuration, and should therefore prefer creating a module-level logger and calling `Logger.debug()` (or other level-specific methods) on it, as described at the beginnning of this documentation.

logging.info(msg, *args, **kwargs)

  ルートロガーに対してログレベル `INFO` でメッセージを記録します。引数と振る舞いは、ログレベルを除けば `debug()` と同じです。

logging.warning(msg, *args, **kwargs)

  ルートロガーに対してログレベル `WARNING` でメッセージを記録します。引数と振る舞いは、ログレベルを除けば `debug()` と同じです。

  注釈

  `warning` と機能的に等価な古い関数 `warn` があります。`warn` は廃止予定なので使わないでください - 代わりに `warning` を使ってください。

logging.error(msg, *args, **kwargs)

  ルートロガーに対してログレベル `ERROR` でメッセージを記録します。引数と振る舞いは、ログレベルを除けば `debug()` と同じです。

logging.critical(msg, *args, **kwargs)

  ルートロガーに対してログレベル `CRITICAL` でメッセージを記録します。引数と振る舞いは、ログレベルを除けば `debug()` と同じです。

logging.exception(msg, *args, **kwargs)

  ルートロガーに対してログレベル `ERROR` でメッセージを記録します。引数と振る舞いは、ログレベルを除けば `debug()` と同じです。例外情報がログメッセージに追加されます。この関数は例外ハンドラからのみ呼び出されるべきです。

logging.log(level, msg, *args, **kwargs)

  ルートロガーに対して level で指定したログレベルでメッセージを記録します。引数と振る舞いは、ログレベルを除けば `debug()` と同じです。

logging.disable(level=CRITICAL)

  全てのロガーのレベル level を上書きし、これはロガー自身の出力レベルよりも優先されます。アプリケーション全体を横断するログ出力を一時的に調整する必要が生じたら、この関数は便利でしょう。これの効果は重大度 level 以下の全てのロギング呼び出しを無効にすることですので、INFO で呼び出しをすれば、INFO と DEBUG イベントが捨てられる一方で、重大度 WARNING 以上のものは、ロガーの有効レベルに基いて処理されます。 `logging.disable(logging.NOTSET)` が呼び出されると、この上書きレベルは削除され、ログ出力は再び個々のロガーの有効レベルに依存するようになります。

  `CRITICAL` より高い独自のログレベル (これは推奨されません) を定義した場合は、 level 引数のデフォルト値を当てにできなくなり、適切な値を明示的に与える必要があります。

  バージョン 3.7 で変更: level 引数のデフォルトが `CRITICAL` レベルになりました。この変更についてのより詳しいことは bpo-28524 を参照してください。

logging.addLevelName(level, levelName)

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

  注釈

  独自のレベルを定義したい場合、 カスタムレベル のセクションを参照してください。

logging.getLevelNamesMapping()

  ログレベルの名前と対応するログレベルのマッピングを返します。例えば、文字列 "CRITICAL" は `CRITICAL` にマップされます。この関数が返すマッピングオブジェクトは、関数呼び出しのたびに内部のマッピングをコピーしたものです。

  バージョン 3.11 で追加.

logging.getLevelName(level)

  テキストまたは数値表現でログレベル level を返してください。

  level が定義済みのレベル `CRITICAL`, `ERROR`, `WARNING`, `INFO`, `DEBUG` のいずれかである場合、対応する文字列が返されます。 `addLevelName()` を使ってレベルに名前を関連付けていた場合、 level に関連付けられた名前が返されます。定義済みのレベルに対応する数値を指定した場合、レベルに対応した文字列表現を返します。

  level パラメータは、 `INFO` のような整数定数の代わりに 'INFO' のようなレベルの文字列表現も受け付けます。この場合、この関数は関連するレベルの数値表現を返します。

  もし渡された数値や文字列がマッチしなければ、 'Level %s' % level が返されます。

  注釈

  レベルは内部的には整数です(これはロギングのロジックが大小比較をする必要があるからです)。この関数は、数値のレベルを、書式記述子 `%(levelname)s` (LogRecord 属性 参照)によって書式化されるログ出力の表示用レベル名に変換するなどの用途に使用されます。

  バージョン 3.4 で変更: Python 3.4以前のバージョンでは、この関数にはテキストのレベルも渡すことが出来、これは対応する数字レベルに読み替えられていました。このドキュメントされていなかった振る舞いは誤りであると判断され、Python 3.4 で一度削除されました。ただし後方互換性のために、これは 3.4.2 で元に戻されました。

logging.makeLogRecord(attrdict)

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

logging.basicConfig(**kwargs)

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

  この関数は force キーワード引数に `True` が設定されない限り、ルートロガーに設定されたハンドラがあれば何もしません。

  注釈

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

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

  フォーマット | 説明
  --- | ---
  filename | `StreamHandler` ではなく指定された名前で `FileHandler` が作られます。
  filemode | filename が指定された場合、この モード でファイルが開かれます。 デフォルトは `'a'` です。
  format | ハンドラーで指定されたフォーマット文字列を使います。デフォルトは `levelname`, `name`, `message` 属性をコロン区切りにしたものです。
  datefmt | 指定された日時の書式で `time.strftime()` が受け付けるものを使います。
  style | format が指定された場合、書式文字列にこのスタイルを仕様します。 `'%'`, `'{'`, `'$'` のうち1つで、それぞれ printf-style, `str.format()`, `string.Template` に対応します。 デフォルトは `'%'` です。
  level | ルートロガーのレベルを指定された レベル に設定します。
  stream | 指定されたストリームを `StreamHandler` の初期化に使います。 この引数は filename と同時には使えないことに注意してください。 両方が指定されたときには `ValueError` が送出されます。
  handlers | もし指定されれば、 これは root ロガーに追加される既に作られたハンドラのイテラブルになります。まだフォーマッタがセットされていないすべてのハンドラは、この関数で作られたデフォルトフォーマッタが割り当てられることになります。この引数は filename や stream と互換性がないことに注意してください。両方が存在する場合 `ValueError` が上げられます。
  force | このキーワード引数が真に設定されている場合、ルートのロガーに取り付けられたハンドラは全て取り除かれ、他の引数によって指定された設定が有効になる前に閉じられます。
  encoding | もしこのキーワード引数が filename とともに指定された場合、 `FileHandler` が作成されるときにこの値が利用され、出力ファイルを開く時に使用されます。
  errors | もしこのキーワード引数が filename とともに指定された場合、 `FileHandler` が作成されるときのこの値が使用され、出力ファイルを開く時に使われます。もし指定されなかった場合、 'backslashreplace' が使用されます。もし `None` が指定されると `open()` のように渡され、'errors' を渡したのと同じように扱われます。

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

  バージョン 3.3 で変更: 互換性のない引数が指定された状況 (例えば handlers が stream や filename と一緒に指定されたり、stream が filename と一緒に指定された場合) を捕捉するために、追加のチェックが加えられました。

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

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

logging.shutdown()

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

  loggingモジュールがインポートされると、この関数が終了ハンドラーとして登録されます（ `atexit` 参照）。そのため、通常はこれを手動で行う必要はありません。

logging.setLoggerClass(klass)

  ロギングシステムに対して、ロガーをインスタンス化する際にクラス klass を使うように指示します。 指定するクラスは引数として名前だけをとるようなメソッド `__init__()` を定義していなければならず、 `__init__()` では `Logger.__init__()` を呼び出さなければなりません。 この関数が呼び出されるのはたいてい、独自の振る舞いをするロガーを使う必要のあるアプリケーションでロガーがインスタンス化される前です。 呼び出された後は、いつでもそのサブクラスを使ってロガーのインスタンス化をしてはいけません: 引き続き `logging.getLogger()` API を使用してロガーを取得してください。

logging.setLogRecordFactory(factory)

  `LogRecord` を生成するのに使われる callable をセットします。

  パラメータ:

    factory -- ログレコードを生成するファクトリとして振舞う callable。

  バージョン 3.2 で追加: この関数は、ログイベントを表現する `LogRecord` の構築方法に関して開発者により多くのコントロールを与えるため、 `getLogRecordFactory()` とともに提供されました。

  ファクトリは以下のようなシグネチャを持っています:

  `factory(name, level, fn, lno, msg, args, exc_info, func=None, sinfo=None, **kwargs)`

  > name:

  >   ロガーの名前。

  > level:

  >   ログレベル (数値)。

  > fn:

  >   ログ呼び出しが行われたファイルのフルパス名。

  > lno:

  >   ログ呼び出しが行われたファイルの行数。

  > msg:

  >   ログメッセージ。

  > `args`:

  >   ログメッセージに対する引数。

  > exc_info:

  >   例外タプルまたは `None`。

  > func:

  >   ログ呼び出しを起動した関数またはメソッドの名前。

  > sinfo:

  >   `traceback.print_stack()` で提供されるような、呼び出し階層を示すスタックトレースバック。

  > `kwargs`:

  >   追加のキーワード引数。

## モジュールレベル属性

logging.lastResort

  「最後の手段のハンドラ」が、この属性で利用可能です。これは `StreamHandler` が `sys.stderr` に `WARNING` レベルで書き出しているのがそうですし、ロギングの設定がなにか不在のロギングイベントを扱う場合に使われます。最終的な結果は、メッセージを単に `sys.stderr` に出力することです。これはかつて「logger XYZ についてのハンドラが見つかりません」と言っていたエラーメッセージを置き換えています。もしも何らかの理由でその昔の振る舞いが必要な場合は、 `lastResort` に `None` をセットすれば良いです。

  バージョン 3.2 で追加.

logging.raiseExceptions

  ログメッセージの処理中に発生した例外を伝播させるかどうかを調べるために使われます。

  デフォルト: `True`.

  `raiseExceptions` が `False` の場合、発生した例外は静かに無視されます。これはほとんどのログシステムにおいて望ましい動作です - ほとんどのユーザーはログシステムのエラーには興味がなく、アプリケーションのエラーにより強い関心を持つでしょう。

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

`captureWarnings()` 関数を使って、 `logging` を `warnings` モジュールと統合できます。

logging.captureWarnings(capture)

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

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

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

参考

`logging.config` モジュール

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

`logging.handlers` モジュール

  logging モジュールに含まれる、便利なハンドラです。

PEP 282 - ログシステム

  この機能を Python 標準ライブラリに含めることを述べた提案です。

Python の最初のロギングパッケージ

  これは、 `logging` パッケージのオリジナルのソースです。このサイトから利用できるバージョンのパッケージは、 `logging` パッケージを標準ライブラリに含まない、 Python 1.5.2, 2.1.x および 2.2.x で使うのに適しています。