logging
--- 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
この慣用的な使い方における重要な特色は、大部分のコードは getLogger(__name__)
で単にモジュールレベルのロガーを作るだけで、そのロガーを必要なロギングに使えるということです。これは簡潔であると同時に、下位のコードにおいて、必要に応じてきめ細やかな制御を可能にしています。モジュールレベルのロガーに対するログメッセージは、最終的にルートロガーとして知られる最上位のロガーに達するまで順次転送されます。ロギングに対するこのようなアプローチは、階層的ロギングとして知られています。
ロギングを有用なものとするためには、用途に応じて構成する必要があります: ログレベルの設定や各ロガーの出力先から、潜在的には特定のモジュールに対する振る舞いの変更などを、しばしばコマンドライン引数かアプリケーションの構成の一部として。上記の例を含めて、ほとんどの場合ではルートロガーのみを構成するだけで十分です。なぜならモジュールレベルの全ての下位のロガーは、全てのメッセージを最終的にルートロガーのハンドラに転送するからです。 basicConfig()
は、多くのユースケースを上手に扱うことのできる簡便なルートロガーの構成方法を提供します。
このモジュールは、多くの機能性と柔軟性を提供します。ロギングに慣れていないなら、使い方を理解する最良の方法はチュートリアルを読むことです (右上のリンクを参照してください)。
モジュールで定義されている基本的なクラスと、その属性およびメソッドを以下に列挙します。
ロガーは、アプリケーションコードが直接使うインターフェースを公開します。
ハンドラは、(ロガーによって生成された) ログ記録を適切な送信先に送ります。
フィルタは、どのログ記録を出力するかを決定する、きめ細かい機能を提供します。
フォーマッタは、ログ記録が最終的に出力されるレイアウトを指定します。
ロガーオブジェクト¶
ロガーには以下のような属性とメソッドがあります。
ロガーを直接インスタンス化することは 絶対に してはならず、常にモジュール関数 logging.getLogger(name)
を介してインスタンス化することに注意してください。
同じ name で getLogger()
を複数回呼び出すと、常に同じロガー・オブジェクトへの参照が返されます。
name
は、潜在的に foo.bar.baz
のようなピリオドで区切られた階層的な値です (ただし、たとえば foo
のような単純な値も可能です)。階層構造の下位にあるロガーは、上位のロガーの子になります。たとえば foo
という名前のロガーに対して、 foo.bar
、 foo.bar.baz
、 foo.bam
という名前のロガーは全て foo
の子孫です。さらに、全てのロガーはルートロガーの子孫です。ロガー名の階層構造は Python パッケージの階層構造に類似しています。また、推奨される構築方法である logging.getLogger(__name__)
を使ってモジュール単位でロガーを構築すれば、パッケージの階層構造とロガーの階層構造は同一になります。なぜなら、モジュールの中で、 __name__
は Python パッケージの名前空間におけるモジュール名だからです。
- 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__
などを使って名付けられているときに便利です。Added in version 3.2.
- getChildren()¶
Returns a set of loggers which are immediate children of this logger. So for example
logging.getLogger().getChildren()
might return a set containing loggers namedfoo
andbar
, but a logger namedfoo.bar
wouldn't be included in the set. Likewise,logging.getLogger('foo').getChildren()
might return a set including a logger namedfoo.bar
, but it wouldn't include one namedfoo.bar.baz
.Added in version 3.12.
- 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 theLogRecord
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
と共に使われるというのはよくあることです。このロガー (および
Logger.propagate
属性を考慮した上で実効的にイベントが伝播する祖先のロガー) にハンドラが接続されていない場合、メッセージはlastResort
に設定されたハンドラーに送られます。バージョン 3.2 で変更: stack_info パラメータが追加されました。
バージョン 3.5 で変更: exc_info パラメータは例外インスタンスを受け入れることが可能です。
バージョン 3.8 で変更: stacklevel 引数が追加されました。
- warning(msg, *args, **kwargs)¶
レベル
WARNING
のメッセージをこのロガーで記録します。引数はdebug()
と同じように解釈されます。注釈
warning
と機能的に等価な古いメソッドwarn
があります。warn
は廃止予定なので使わないでください - 代わりにwarning
を使ってください。
- 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' 属性が偽に設定されたロガーを見つけると、さらに上位の探索をやめます。そのロガーが、ハンドラが存在するかどうかチェックされる最後のロガーになります。Added in version 3.2.
バージョン 3.7 で変更: ロガーの pickle 化と unpickle 化ができるようになりました。
ロギングレベル¶
ログレベルの数値は以下の表のように与えられています。これらは基本的に自分でレベルを定義したい人のためのもので、定義するレベルを既存のレベルの間に位置づけるためには具体的な値が必要になります。もし数値が他のレベルと同じだったら、既存の値は上書きされその名前は失われます。
レベル |
数値 |
What it means / When to use it |
---|---|---|
|
0 |
When set on a logger, indicates that
ancestor loggers are to be consulted
to determine the effective level.
If that still resolves to
|
|
10 |
Detailed information, typically only of interest to a developer trying to diagnose a problem. |
|
20 |
想定された通りのことが起こったことの確認。 |
|
30 |
An indication that something unexpected happened, or that a problem might occur in the near future (e.g. 'disk space low'). The software is still working as expected. |
|
40 |
より重大な問題により、ソフトウェアがある機能を実行できないこと。 |
|
50 |
プログラム自体が実行を続けられないことを表す、重大なエラー。 |
ハンドラオブジェクト¶
ハンドラ (Handler) は以下の属性とメソッドを持ちます。 Handler
は直接インスタンス化されることはありません; このクラスはより便利なサブクラスの基底クラスとして働きます。しかしながら、サブクラスにおける __init__()
メソッドでは、 Handler.__init__()
を呼び出す必要があります。
- class logging.Handler¶
- __init__(level=NOTSET)¶
レベルを設定して、
Handler
インスタンスを初期化します。空のリストを使ってフィルタを設定し、 I/O 機構へのアクセスを直列化するために (createLock()
を使って) ロックを生成します。
- createLock()¶
スレッドセーフでない背後の I/O 機能に対するアクセスを直列化するために用いられるスレッドロック (thread lock) を初期化します。
- acquire()¶
createLock()
で生成されたスレッドロックを獲得します。
- setLevel(level)¶
このハンドラに対する閾値を level に設定します。 level よりも深刻でないログメッセージは無視されます。 ハンドラが生成された際、レベルは
NOTSET
(すべてのメッセージが処理される) に設定されます。レベルの一覧については ロギングレベル を参照してください。
バージョン 3.2 で変更: level パラメータは、
INFO
のような整数定数の代わりに 'INFO' のようなレベルの文字列表現も受け付けるようになりました。
- addFilter(filter)¶
指定されたフィルタ filter をこのハンドラに追加します。
- removeFilter(filter)¶
指定されたフィルタ filter をこのハンドラから除去します。
- filter(record)¶
レコードに対してこのハンドラのフィルタを適用し、レコードが処理されるべき場合に
True
を返します。フィルタのいずれかの値が偽を返すまで、それらは順番に試されていきます。いずれも偽を返さなければ、レコードは発行されることになります。ひとつでも偽を返せば、ハンドラはレコードを発行しません。
- flush()¶
すべてのログ出力がフラッシュされるようにします。このクラスのバージョンではなにも行わず、サブクラスで実装するためのものです。
- close()¶
ハンドラで使われているすべてのリソースの後始末を行います。このバージョンでは何も出力せず、
shutdown()
が呼ばれたときに閉じられたハンドラを内部リストから削除します。サブクラスではオーバライドされたclose()
メソッドからこのメソッドが必ず呼ばれるようにしてください。
- handle(record)¶
ハンドラに追加されたフィルタの条件に応じて、指定されたログレコードを出力します。このメソッドは I/O スレッドロックの獲得/解放を伴う実際のログ出力をラップします。
- handleError(record)¶
This method should be called from handlers when an exception is encountered during an
emit()
call. If the module-level attributeraiseExceptions
isFalse
, exceptions get silently ignored. This is what is mostly wanted for a logging system - most users will not care about errors in the logging system, they are more interested in application errors. You could, however, replace this with a custom handler if you wish. The specified record is the one which was being processed when the exception occurred. (The default value ofraiseExceptions
isTrue
, as that is more useful during development).
- format(record)¶
レコードに対する書式化を行います - フォーマッタが設定されていれば、それを使います。そうでない場合、モジュールにデフォルト指定されたフォーマッタを使います。
- emit(record)¶
指定されたログ記録レコードを実際にログ記録する際のすべての処理を行います。このメソッドはサブクラスで実装されることを意図しており、そのためこのクラスのバージョンは
NotImplementedError
を送出します。警告
このメソッドはハンドラレベルのロックを取得した後で呼び出されます。また、ロックはこのメソッドがリターンした後で解放されます。このメソッドをオーバーライドする場合、ロックを取得する可能性のある logging API の他の関数やメソッドの呼び出しに注意してください。そのような実装はデッドロックを引き起こす可能性があります。特に以下の点に注意してください:
ロギングを構成するための API はモジュールレベルのロックを取得し、その後ハンドラを構成する際に個々のハンドラに対してハンドラレベルのロックを取得します。
多くのロギング API はモジュールレベルのロックを取得します。そのような API がこのメソッドから呼ばれた場合、他のスレッドからロギングを構成するための API 呼び出しが行われたときにデッドロックに陥る可能性があります。これは他のスレッドがハンドラレベルのロックを取得する 前に モジュールレベルのロックを取得しようとする一方で、 (このメソッドはハンドラレベルのロックが既に取得された状態で呼び出されているため) このメソッドを呼び出したスレッドはハンドラレベルのロックを取得した 後で モジュールレベルのロックを取得しようとするためです。
標準として含まれているハンドラについては、 logging.handlers
を参照してください。
フォーマッタオブジェクト¶
- class logging.Formatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)¶
Responsible for converting a
LogRecord
to an output string to be interpreted by a human or external system.- パラメータ:
fmt (str) -- A format string in the given style for the logged output as a whole. The possible mapping keys are drawn from the
LogRecord
object's LogRecord 属性. If not specified,'%(message)s'
is used, which is just the logged message.datefmt (str) -- A format string in the given style for the date/time portion of the logged output. If not specified, the default described in
formatTime()
is used.style (str) -- Can be one of
'%'
,'{'
or'$'
and determines how the format string will be merged with its data: using one of printf 形式の文字列書式化 (%
),str.format()
({
) orstring.Template
($
). This only applies to fmt and datefmt (e.g.'%(message)s'
versus'{message}'
), not to the actual log messages passed to the logging methods. However, there are other ways to use{
- and$
-formatting for log messages.validate (bool) -- If
True
(the default), incorrect or mismatched fmt and style will raise aValueError
; for example,logging.Formatter('%(asctime)s - %(message)s', style='{')
.defaults (dict[str, Any]) -- A dictionary with default values to use in custom fields. For example,
logging.Formatter('%(ip)s %(message)s', defaults={"ip": None})
バージョン 3.2 で変更: Added the style parameter.
バージョン 3.8 で変更: Added the validate parameter.
バージョン 3.10 で変更: Added the defaults parameter.
- 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)¶
複数のレコード のリストに対するヘッダを返します。基底クラスの実装は単に空の文字列を返すだけです。レコード数やタイトルを表示したり、あるいはセパレータ行したいなど、ヘッダに対して特別な振る舞いが必要な場合はこのメソッドをオーバーライドする必要があります。
複数のレコード のリストに対するフッタを返します。基底クラスの実装は単に空の文字列を返すだけです。レコード数やセパレータ行の表示など、フッタに対して特別な振る舞いが必要な場合はこのメソッドをオーバーライドする必要があります。
- 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 false for no, true for yes. Filters can either modify log records in-place or return a completely different record instance which will replace the original log record in any future processing of the event.
ハンドラに対するフィルタはハンドラがイベントを発行する前に試され、一方ではロガーに対するフィルタは、イベントが(debug()
, info()
などによって)ロギングされる際には、ハンドラにイベントが送信される前にはいつでも試されることに注意してください。そのフィルタがそれら子孫ロガーにも適用されていない限り、子孫ロガーによって生成されたイベントはロガーのフィルタ設定によってフィルタされることはありません。
実際には、Filter
をサブクラス化する必要はありません。同じ意味の filter
メソッドを持つ、すべてのインスタンスを通せます。
バージョン 3.2 で変更: 特殊な Filter
クラスを作ったり、 filter
メソッドを持つ他のクラスを使う必要はありません: 関数 (あるいは他の callable) をフィルタとして使用することができます。フィルタロジックは、フィルタオブジェクトが filter
属性を持っているかどうかチェックします: もし filter
属性を持っていたら、それは Filter
であると仮定され、その filter()
メソッドが呼び出されます。そうでなければ、それは callable であると仮定され、レコードを単一のパラメータとして呼び出されます。返される値は filter()
によって返されるものと一致すべきです。
バージョン 3.12 で変更: You can now return a LogRecord
instance from filters to replace
the log record rather than modifying it in place. This allows filters attached to
a Handler
to modify the log record before it is emitted, without
having side effects on other handlers.
フィルタは本来、レコードをレベルよりも洗練された基準に基づいてフィルタするために使われますが、それが取り付けられたハンドラやロガーによって処理されるレコードをすべて監視します。これは、特定のロガーやハンドラに処理されたレコードの数を数えたり、処理されている 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()
ドキュメンテーションを参照してください。
属性名 |
フォーマット |
説明 |
---|---|---|
|
このフォーマットを自分で使う必要はないでしょう。 |
|
asctime |
|
|
created |
|
Time when the |
exc_info |
このフォーマットを自分で使う必要はないでしょう。 |
( |
ファイル名 |
|
|
funcName |
|
ロギングの呼び出しを含む関数の名前。 |
levelname |
|
メッセージのための文字のロギングレベル ( |
levelno |
|
メッセージのための数値のロギングレベル ( |
lineno |
|
ロギングの呼び出しが発せられたソース行番号 (利用できる場合のみ)。 |
message |
|
|
module |
|
モジュール ( |
msecs |
|
|
msg |
このフォーマットを自分で使う必要はないでしょう。 |
元のロギングの呼び出しで渡されたフォーマット文字列。 |
name |
|
ロギングに使われたロガーの名前。 |
pathname |
|
ロギングの呼び出しが発せられたファイルの完全なパス名 (利用できる場合のみ)。 |
process |
|
プロセス ID (利用可能な場合のみ)。 |
processName |
|
プロセス名 (利用可能な場合のみ)。 |
relativeCreated |
|
logging モジュールが読み込まれた時刻に対する、LogRecord が生成された時刻を、ミリ秒で表したもの。 |
stack_info |
このフォーマットを自分で使う必要はないでしょう。 |
現在のスレッドでのスタックの底からこのレコードの生成に帰着したログ呼び出しまでのスタックフレーム情報 (利用可能な場合)。 |
thread |
|
スレッド ID (利用可能な場合のみ)。 |
threadName |
|
スレッド名 (利用可能な場合のみ)。 |
taskName |
|
|
バージョン 3.1 で変更: processName が追加されました。
バージョン 3.12 で変更: taskName が追加されました。
LoggerAdapter オブジェクト¶
LoggerAdapter
インスタンスは文脈情報をログ記録呼び出しに渡すのを簡単にするために使われます。使い方の例は コンテキスト情報をログ記録出力に付加する を参照してください。
- class logging.LoggerAdapter(logger, extra, merge_extra=False)¶
Returns an instance of
LoggerAdapter
initialized with an underlyingLogger
instance, a dict-like object (extra), and a boolean (merge_extra) indicating whether or not the extra argument of individual log calls should be merged with theLoggerAdapter
extra. The default behavior is to ignore the extra argument of individual log calls and only use the one of theLoggerAdapter
instance- 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()
メソッドが追加されました。バージョン 3.13 で変更: The merge_extra argument was added.
スレッドセーフ性¶
logging モジュールは、クライアントで特殊な作業を必要としない限りスレッドセーフになっています。このスレッドセーフ性はスレッドロックによって達成されています; モジュールの共有データへのアクセスを直列化するためのロックが一つ存在し、各ハンドラでも背後にある I/O へのアクセスを直列化するためにロックを生成します。
signal
モジュールを使用して非同期シグナルハンドラを実装している場合、そのようなハンドラからはログ記録を使用できないかもしれません。これは、 threading
モジュールにおけるロック実装が常にリエントラントではなく、そのようなシグナルハンドラから呼び出すことができないからです。
モジュールレベルの関数¶
上で述べたクラスに加えて、いくつかのモジュールレベルの関数が存在します。
- logging.getLogger(name=None)¶
Return a logger with the specified name or, if name is
None
, return 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, though it is recommended that__name__
be used unless you have a specific reason for not doing that, as mentioned in ロガーオブジェクト.与えられた名前に対して、この関数はどの呼び出しでも同じロガーインスタンスを返します。したがって、ロガーインスタンスをアプリケーションの各部でやりとりする必要はありません。
- logging.getLoggerClass()¶
標準の
Logger
クラスか、最後にsetLoggerClass()
に渡したクラスを返します。この関数は、新たなクラス定義の中で呼び出して、カスタマイズしたLogger
クラスのインストールが既に他のコードで適用したカスタマイズを取り消さないことを保証するために使われることがあります。例えば以下のようにします:class MyLogger(logging.getLoggerClass()): # ... override behaviour here
- logging.getLogRecordFactory()¶
LogRecord
を生成するのに使われる callable を返します。Added in version 3.2: この関数は、ログイベントを表現する
LogRecord
の構築方法に関して開発者により多くのコントロールを与えるため、setLogRecordFactory()
とともに提供されました。このファクトリがどのように呼ばれるかに関する詳細は
setLogRecordFactory()
を参照してください。
- logging.debug(msg, *args, **kwargs)¶
This is a convenience function that calls
Logger.debug()
, on the root logger. The handling of the arguments is in every way identical to what is described in that method.The only difference is that if the root logger has no handlers, then
basicConfig()
is called, prior to callingdebug
on the root logger.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 callingLogger.debug()
(or other level-specific methods) on it, as described at the beginnning of this documentation.
- logging.info(msg, *args, **kwargs)¶
Logs a message with level
INFO
on the root logger. The arguments and behavior are otherwise the same as fordebug()
.
- logging.warning(msg, *args, **kwargs)¶
Logs a message with level
WARNING
on the root logger. The arguments and behavior are otherwise the same as fordebug()
.注釈
warning
と機能的に等価な古い関数warn
があります。warn
は廃止予定なので使わないでください - 代わりにwarning
を使ってください。
- logging.error(msg, *args, **kwargs)¶
Logs a message with level
ERROR
on the root logger. The arguments and behavior are otherwise the same as fordebug()
.
- logging.critical(msg, *args, **kwargs)¶
Logs a message with level
CRITICAL
on the root logger. The arguments and behavior are otherwise the same as fordebug()
.
- logging.exception(msg, *args, **kwargs)¶
Logs a message with level
ERROR
on the root logger. The arguments and behavior are otherwise the same as fordebug()
. Exception info is added to the logging message. This function should only be called from an exception handler.
- logging.log(level, msg, *args, **kwargs)¶
Logs a message with level level on the root logger. The arguments and behavior are otherwise the same as for
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
にマップされます。この関数が返すマッピングオブジェクトは、関数呼び出しのたびに内部のマッピングをコピーしたものです。Added in version 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.getHandlerByName(name)¶
Returns a handler with the specified name, or
None
if there is no handler with that name.Added in version 3.12.
- logging.getHandlerNames()¶
Returns an immutable set of all known handler names.
Added in version 3.12.
- 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。
Added in version 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
をセットすれば良いです。Added in version 3.2.
- logging.raiseExceptions¶
Used to see if exceptions during handling should be propagated.
Default:
True
.If
raiseExceptions
isFalse
, exceptions get silently ignored. This is what is mostly wanted for a logging system - most users will not care about errors in the logging system, they are more interested in application errors.
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 で使うのに適しています。