Logging クックブック
********************

著者:
   Vinay Sajip <vinay_sajip at red-dove dot com>

このページでは、過去に見つかった logging に関するいくつかの便利なレシ
ピを紹介します。


複数のモジュールで logging を使う
=================================

"logging.getLogger('someLogger')" の複数回の呼び出しは同じ logger への
参照を返します。これは同じ Python インタプリタプロセス上で動いている限
り、一つのモジュールの中からに限らず、モジュールをまたいでも当てはまり
ます。同じオブジェクトへの参照という点でも正しいです。さらに、一つのモ
ジュールの中で親 logger を定義して設定し、別のモジュールで子 logger を
定義する (ただし設定はしない) ことが可能で、すべての子 logger への呼び
出しは親にまで渡されます。まずはメインのモジュールです:

   import logging
   import auxiliary_module

   # create logger with 'spam_application'
   logger = logging.getLogger('spam_application')
   logger.setLevel(logging.DEBUG)
   # create file handler which logs even debug messages
   fh = logging.FileHandler('spam.log')
   fh.setLevel(logging.DEBUG)
   # create console handler with a higher log level
   ch = logging.StreamHandler()
   ch.setLevel(logging.ERROR)
   # create formatter and add it to the handlers
   formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
   fh.setFormatter(formatter)
   ch.setFormatter(formatter)
   # add the handlers to the logger
   logger.addHandler(fh)
   logger.addHandler(ch)

   logger.info('creating an instance of auxiliary_module.Auxiliary')
   a = auxiliary_module.Auxiliary()
   logger.info('created an instance of auxiliary_module.Auxiliary')
   logger.info('calling auxiliary_module.Auxiliary.do_something')
   a.do_something()
   logger.info('finished auxiliary_module.Auxiliary.do_something')
   logger.info('calling auxiliary_module.some_function()')
   auxiliary_module.some_function()
   logger.info('done with auxiliary_module.some_function()')

そして補助モジュール (auxiliary module) がこちらです:

   import logging

   # create logger
   module_logger = logging.getLogger('spam_application.auxiliary')

   class Auxiliary:
       def __init__(self):
           self.logger = logging.getLogger('spam_application.auxiliary.Auxiliary')
           self.logger.info('creating an instance of Auxiliary')

       def do_something(self):
           self.logger.info('doing something')
           a = 1 + 1
           self.logger.info('done doing something')

   def some_function():
       module_logger.info('received a call to "some_function"')

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

   2005-03-23 23:47:11,663 - spam_application - INFO -
      creating an instance of auxiliary_module.Auxiliary
   2005-03-23 23:47:11,665 - spam_application.auxiliary.Auxiliary - INFO -
      creating an instance of Auxiliary
   2005-03-23 23:47:11,665 - spam_application - INFO -
      created an instance of auxiliary_module.Auxiliary
   2005-03-23 23:47:11,668 - spam_application - INFO -
      calling auxiliary_module.Auxiliary.do_something
   2005-03-23 23:47:11,668 - spam_application.auxiliary.Auxiliary - INFO -
      doing something
   2005-03-23 23:47:11,669 - spam_application.auxiliary.Auxiliary - INFO -
      done doing something
   2005-03-23 23:47:11,670 - spam_application - INFO -
      finished auxiliary_module.Auxiliary.do_something
   2005-03-23 23:47:11,671 - spam_application - INFO -
      calling auxiliary_module.some_function()
   2005-03-23 23:47:11,672 - spam_application.auxiliary - INFO -
      received a call to 'some_function'
   2005-03-23 23:47:11,673 - spam_application - INFO -
      done with auxiliary_module.some_function()


複数のスレッドからのロギング
============================

複数スレッドからのロギングでは特別に何かをする必要はありません。 次の
例はmain (初期) スレッドとそれ以外のスレッドからのロギングの例です:

   import logging
   import threading
   import time

   def worker(arg):
       while not arg['stop']:
           logging.debug('Hi from myfunc')
           time.sleep(0.5)

   def main():
       logging.basicConfig(level=logging.DEBUG, format='%(relativeCreated)6d %(threadName)s %(message)s')
       info = {'stop': False}
       thread = threading.Thread(target=worker, args=(info,))
       thread.start()
       while True:
           try:
               logging.debug('Hello from main')
               time.sleep(0.75)
           except KeyboardInterrupt:
               info['stop'] = True
               break
       thread.join()

   if __name__ == '__main__':
       main()

実行すると、出力は以下のようになるはずです:

      0 Thread-1 Hi from myfunc
      3 MainThread Hello from main
    505 Thread-1 Hi from myfunc
    755 MainThread Hello from main
   1007 Thread-1 Hi from myfunc
   1507 MainThread Hello from main
   1508 Thread-1 Hi from myfunc
   2010 Thread-1 Hi from myfunc
   2258 MainThread Hello from main
   2512 Thread-1 Hi from myfunc
   3009 MainThread Hello from main
   3013 Thread-1 Hi from myfunc
   3515 Thread-1 Hi from myfunc
   3761 MainThread Hello from main
   4017 Thread-1 Hi from myfunc
   4513 MainThread Hello from main
   4518 Thread-1 Hi from myfunc

予想した通りかもしれませんが、ログ出力が散らばっているのが分かります。
もちろん、この手法はより多くのスレッドでも上手くいきます。


複数の handler と formatter
===========================

logger は通常の Python オブジェクトです。 "addHandler()" メソッドは追
加されるハンドラの個数について最小値も最大値も定めていません。時にアプ
リケーションがすべての深刻度のすべてのメッセージをテキストファイルに記
録しつつ、同時にエラーやそれ以上のものをコンソールに出力することが役に
立ちます。これを実現する方法は、単に適切なハンドラを設定するだけです。
アプリケーションコードの中のログ記録の呼び出しは変更されずに残ります。
少し前に取り上げた単純なモジュール式の例を少し変えるとこうなります:

   import logging

   logger = logging.getLogger('simple_example')
   logger.setLevel(logging.DEBUG)
   # create file handler which logs even debug messages
   fh = logging.FileHandler('spam.log')
   fh.setLevel(logging.DEBUG)
   # create console handler with a higher log level
   ch = logging.StreamHandler()
   ch.setLevel(logging.ERROR)
   # create formatter and add it to the handlers
   formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
   ch.setFormatter(formatter)
   fh.setFormatter(formatter)
   # add the handlers to logger
   logger.addHandler(ch)
   logger.addHandler(fh)

   # 'application' code
   logger.debug('debug message')
   logger.info('info message')
   logger.warn('warn message')
   logger.error('error message')
   logger.critical('critical message')

'application' 部分のコードは複数の handler について何も気にしていない
ことに注目してください。変更した箇所は新しい *fh* という名の handler
を追加して設定したところがすべてです。

新しい handler を、異なる深刻度に対する filter と共に生成できることは
、アプリケーションを書いてテストを行うときとても助けになります。デバッ
グ用にたくさんの "print" 文を使う代わりに "logger.debug" を使いましょ
う。あとで消したりコメントアウトしたりしなければならない print 文と違
って、logger.debug 命令はソースコードの中にそのまま残しておいて再び必
要になるまで休眠させておけます。その時必要になるのはただ logger および
/または handler の深刻度の設定をいじることだけです。


複数の出力先にログを出力する
============================

コンソールとファイルに、別々のメッセージ書式で、別々の状況に応じたログ
出力を行わせたいとしましょう。例えば DEBUG よりも高いレベルのメッセー
ジはファイルに記録し、INFO 以上のレベルのメッセージはコンソールに出力
したいという場合です。また、ファイルにはタイムスタンプを記録し、コンソ
ールには出力しないとします。以下のようにすれば、こうした挙動を実現でき
ます:

   import logging

   # set up logging to file - see previous section for more details
   logging.basicConfig(level=logging.DEBUG,
                       format='%(asctime)s %(name)-12s %(levelname)-8s %(message)s',
                       datefmt='%m-%d %H:%M',
                       filename='/temp/myapp.log',
                       filemode='w')
   # define a Handler which writes INFO messages or higher to the sys.stderr
   console = logging.StreamHandler()
   console.setLevel(logging.INFO)
   # set a format which is simpler for console use
   formatter = logging.Formatter('%(name)-12s: %(levelname)-8s %(message)s')
   # tell the handler to use this format
   console.setFormatter(formatter)
   # add the handler to the root logger
   logging.getLogger('').addHandler(console)

   # Now, we can log to the root logger, or any other logger. First the root...
   logging.info('Jackdaws love my big sphinx of quartz.')

   # Now, define a couple of other loggers which might represent areas in your
   # application:

   logger1 = logging.getLogger('myapp.area1')
   logger2 = logging.getLogger('myapp.area2')

   logger1.debug('Quick zephyrs blow, vexing daft Jim.')
   logger1.info('How quickly daft jumping zebras vex.')
   logger2.warning('Jail zesty vixen who grabbed pay from quack.')
   logger2.error('The five boxing wizards jump quickly.')

これを実行すると、コンソールには以下のように出力されます。

   root        : INFO     Jackdaws love my big sphinx of quartz.
   myapp.area1 : INFO     How quickly daft jumping zebras vex.
   myapp.area2 : WARNING  Jail zesty vixen who grabbed pay from quack.
   myapp.area2 : ERROR    The five boxing wizards jump quickly.

そして、ファイルには以下のように出力されるはずです:

   10-22 22:19 root         INFO     Jackdaws love my big sphinx of quartz.
   10-22 22:19 myapp.area1  DEBUG    Quick zephyrs blow, vexing daft Jim.
   10-22 22:19 myapp.area1  INFO     How quickly daft jumping zebras vex.
   10-22 22:19 myapp.area2  WARNING  Jail zesty vixen who grabbed pay from quack.
   10-22 22:19 myapp.area2  ERROR    The five boxing wizards jump quickly.

これを見て分かる通り、DEBUG メッセージはファイルだけに出力され、その他
のメッセージは両方に出力されます。

この例ではコンソールとファイルのハンドラだけを使っていますが、実際には
任意の数のハンドラや組み合わせを使えます。


設定サーバの例
==============

ログ記録設定サーバを使うモジュールの例です:

   import logging
   import logging.config
   import time
   import os

   # read initial config file
   logging.config.fileConfig('logging.conf')

   # create and start listener on port 9999
   t = logging.config.listen(9999)
   t.start()

   logger = logging.getLogger('simpleExample')

   try:
       # loop through logging calls to see the difference
       # new configurations make, until Ctrl+C is pressed
       while True:
           logger.debug('debug message')
           logger.info('info message')
           logger.warn('warn message')
           logger.error('error message')
           logger.critical('critical message')
           time.sleep(5)
   except KeyboardInterrupt:
       # cleanup
       logging.config.stopListening()
       t.join()

そしてファイル名を受け取ってそのファイルをサーバに送るスクリプトですが
、それに先だってバイナリエンコード長を新しいログ記録の設定として先に送
っておきます:

   #!/usr/bin/env python
   import socket, sys, struct

   with open(sys.argv[1], 'rb') as f:
       data_to_send = f.read()

   HOST = 'localhost'
   PORT = 9999
   s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
   print('connecting...')
   s.connect((HOST, PORT))
   print('sending config...')
   s.send(struct.pack('>L', len(data_to_send)))
   s.send(data_to_send)
   s.close()
   print('complete')


ブロックする handler を扱う
===========================

ときどき、logging を行っているスレッドをブロックせずに、handler が動く
ようにしないといけないときがあります。これは Web アプリケーションでは
よくあることですし、もちろん他のシナリオでも起きる話です。

動作が鈍くなるときの元凶はたいてい、開発者のコントロール外にあるいくつ
もの理由で (例えば、残念なパフォーマンスのメールやネットワークのインフ
ラ) 、 "SMTPHandler": が電子メールを送るのに時間がかかることです。しか
し、ほとんどのネットワークをまたぐ handler はブロックする可能性があり
ます: "SocketHandler" による処理でさえ、裏で DNS への問い合わせという
とても遅い処理を行うことがあります (そしてこの問い合わせ処理は、
Python の層より下のあなたの手の届かない、ソケットライブラリの深いとこ
ろにある可能性もあります)。

解決策の1つは、2パートに分離したアプローチを用いることです。最初のパー
トは、パフォーマンスが重要なスレッドからアクセスされる、
"QueueHandler" だけをアタッチした logger です。この logger は単に、十
分大きい、あるいは無制限の容量を持ったキューに書き込むだけです。キュー
への書き込みは通常すぐに完了しますが、念の為に "queue.Full" 例外をキャ
ッチする必要があるかもしれません。もしパフォーマンスクリティカルなスレ
ッドを持つライブラリの開発者であるなら、このことを ("QueueHandler" だ
けをアタッチした logger についての言及を添えて) ドキュメントに書いてお
きましょう。

2つ目のパートは "QueueHandler" の対向として作られた "QueueListener" で
す。 "QueueListener" はとてもシンプルで、キューと handler を渡され、内
部で "QueueHandler" (もしくは他の "LogRecord" の出力元) から送られた
LogRecord をキューから受け取るスレッドを起動します。 "LogRecord" をキ
ューから取り出して、 handler に渡して処理させます。

分離した "QueueListener" クラスを持つメリットは、複数の "QueueHandler"
に対して1つのインスタンスで logging できることです。既存の handler の
スレッド利用版を使って handler ごとにスレッドを持つよりはずっとリソー
スにやさしくなります。

この2つのクラスを利用する例です (import は省略):

   que = queue.Queue(-1)  # no limit on size
   queue_handler = QueueHandler(que)
   handler = logging.StreamHandler()
   listener = QueueListener(que, handler)
   root = logging.getLogger()
   root.addHandler(queue_handler)
   formatter = logging.Formatter('%(threadName)s: %(message)s')
   handler.setFormatter(formatter)
   listener.start()
   # The log output will display the thread which generated
   # the event (the main thread) rather than the internal
   # thread which monitors the internal queue. This is what
   # you want to happen.
   root.warning('Look out!')
   listener.stop()

実行すると次のように出力します:

   MainThread: Look out!

バージョン 3.5 で変更: Python 3.5 以前は、 "QueueListener" クラスは常
にキューから受け取ったメッセージを、初期化元となっているそれぞれのハン
ドラーに受け渡していました。 ( というのも、レベルフィルターリングは別
サイド、つまり、キューが満たされている場所で処理されるということが想定
されているからです) Python 3.5以降では、キーワードとなる引数
"respect_handler_level=True"  をリスナーのコントラクターに受け渡すこと
で、この挙動を変更することができるようになっています。これが行われると
、各メッセージのレベルをハンドラーのレベルと比較して、そうすることが適
切な場合のみ、メッセージをハンドラーに渡します。


ネットワーク越しの logging イベントの送受信
===========================================

ログイベントをネットワーク越しに送信し、受信端でそれを処理したいとしま
しょう。 "SocketHandler" インスタンスを送信端の root logger にアタッチ
すれば、簡単に実現できます:

   import logging, logging.handlers

   rootLogger = logging.getLogger('')
   rootLogger.setLevel(logging.DEBUG)
   socketHandler = logging.handlers.SocketHandler('localhost',
                       logging.handlers.DEFAULT_TCP_LOGGING_PORT)
   # don't bother with a formatter, since a socket handler sends the event as
   # an unformatted pickle
   rootLogger.addHandler(socketHandler)

   # Now, we can log to the root logger, or any other logger. First the root...
   logging.info('Jackdaws love my big sphinx of quartz.')

   # Now, define a couple of other loggers which might represent areas in your
   # application:

   logger1 = logging.getLogger('myapp.area1')
   logger2 = logging.getLogger('myapp.area2')

   logger1.debug('Quick zephyrs blow, vexing daft Jim.')
   logger1.info('How quickly daft jumping zebras vex.')
   logger2.warning('Jail zesty vixen who grabbed pay from quack.')
   logger2.error('The five boxing wizards jump quickly.')

受信端では "socketserver" モジュールを使って受信プログラムを作成してお
きます。簡単な実用プログラムを以下に示します:

   import pickle
   import logging
   import logging.handlers
   import socketserver
   import struct


   class LogRecordStreamHandler(socketserver.StreamRequestHandler):
       """Handler for a streaming logging request.

       This basically logs the record using whatever logging policy is
       configured locally.
       """

       def handle(self):
           """
           Handle multiple requests - each expected to be a 4-byte length,
           followed by the LogRecord in pickle format. Logs the record
           according to whatever policy is configured locally.
           """
           while True:
               chunk = self.connection.recv(4)
               if len(chunk) < 4:
                   break
               slen = struct.unpack('>L', chunk)[0]
               chunk = self.connection.recv(slen)
               while len(chunk) < slen:
                   chunk = chunk + self.connection.recv(slen - len(chunk))
               obj = self.unPickle(chunk)
               record = logging.makeLogRecord(obj)
               self.handleLogRecord(record)

       def unPickle(self, data):
           return pickle.loads(data)

       def handleLogRecord(self, record):
           # if a name is specified, we use the named logger rather than the one
           # implied by the record.
           if self.server.logname is not None:
               name = self.server.logname
           else:
               name = record.name
           logger = logging.getLogger(name)
           # N.B. EVERY record gets logged. This is because Logger.handle
           # is normally called AFTER logger-level filtering. If you want
           # to do filtering, do it at the client end to save wasting
           # cycles and network bandwidth!
           logger.handle(record)

   class LogRecordSocketReceiver(socketserver.ThreadingTCPServer):
       """
       Simple TCP socket-based logging receiver suitable for testing.
       """

       allow_reuse_address = True

       def __init__(self, host='localhost',
                    port=logging.handlers.DEFAULT_TCP_LOGGING_PORT,
                    handler=LogRecordStreamHandler):
           socketserver.ThreadingTCPServer.__init__(self, (host, port), handler)
           self.abort = 0
           self.timeout = 1
           self.logname = None

       def serve_until_stopped(self):
           import select
           abort = 0
           while not abort:
               rd, wr, ex = select.select([self.socket.fileno()],
                                          [], [],
                                          self.timeout)
               if rd:
                   self.handle_request()
               abort = self.abort

   def main():
       logging.basicConfig(
           format='%(relativeCreated)5d %(name)-15s %(levelname)-8s %(message)s')
       tcpserver = LogRecordSocketReceiver()
       print('About to start TCP server...')
       tcpserver.serve_until_stopped()

   if __name__ == '__main__':
       main()

先にサーバを起動しておき、次にクライアントを起動します。クライアント側
では、コンソールには何も出力されません; サーバ側では以下のようなメッセ
ージを目にするはずです:

   About to start TCP server...
      59 root            INFO     Jackdaws love my big sphinx of quartz.
      59 myapp.area1     DEBUG    Quick zephyrs blow, vexing daft Jim.
      69 myapp.area1     INFO     How quickly daft jumping zebras vex.
      69 myapp.area2     WARNING  Jail zesty vixen who grabbed pay from quack.
      69 myapp.area2     ERROR    The five boxing wizards jump quickly.

特定のシナリオでは pickle にはいくつかのセキュリティ上の問題があること
に注意してください。これが問題になる場合、 "makePickle()" メソッドをオ
ーバーライドして代替手段を実装することで異なるシリアライズ手法を使用で
きます。代替シリアライズ手法を使うように上記のスクリプトを修正すること
もできます。


コンテキスト情報をログ記録出力に付加する
========================================

時にはログ記録出力にログ関数の呼び出し時に渡されたパラメータに加えてコ
ンテキスト情報を含めたいこともあるでしょう。たとえば、ネットワークアプ
リケーションで、クライアント固有の情報 (例: リモートクライアントの名前
、 IP アドレス) もログ記録に残しておきたいと思ったとしましょう。
*extra* パラメータをこの目的に使うこともできますが、いつでもこの方法で
情報を渡すのが便利なやり方とも限りません。また接続ごとに "Logger" イン
スタンスを生成する誘惑に駆られるかもしれませんが、生成した "Logger" イ
ンスタンスはガーベジコレクションで回収されないので、これは良いアイデア
とは言えません。この例は現実的な問題ではないかもしれませんが、
"Logger" インスタンスの個数がアプリケーションの中でログ記録が行われる
レベルの粒度に依存する場合、 "Logger" インスタンスの個数が事実上無制限
にならないと、管理が難しくなります。


LoggerAdapter を使ったコンテキスト情報の伝達
--------------------------------------------

logging イベントの情報と一緒に出力されるコンテキスト情報を渡す簡単な方
法は、 "LoggerAdapter" を使うことです。このクラスは "Logger" のように
見えるように設計されていて、 "debug()", "info()", "warning()",
"error()", "exception()", "critical()", "log()" の各メソッドを呼び出せ
るようになっています。これらのメソッドは対応する "Logger" のメソッドと
同じ引数を取るので、二つの型を取り替えて使うことができます。

"LoggerAdapter" のインスタンスを生成する際には、 "Logger" インスタンス
とコンテキスト情報を収めた辞書風 (dict-like) のオブジェクトを渡します
。 "LoggerAdapter" のログ記録メソッドを呼び出すと、呼び出しをコンスト
ラクタに渡された配下の "Logger" インスタンスに委譲し、その際コンテキス
ト情報をその委譲された呼び出しに埋め込みます。 "LoggerAdapter" のコー
ドから少し抜き出してみます:

   def debug(self, msg, *args, **kwargs):
       """
       Delegate a debug call to the underlying logger, after adding
       contextual information from this adapter instance.
       """
       msg, kwargs = self.process(msg, kwargs)
       self.logger.debug(msg, *args, **kwargs)

"LoggerAdapter" の "process()" メソッドがコンテキスト情報をログ出力に
加える場所です。そこではログ記録呼び出しのメッセージとキーワード引数が
渡され、加工された (可能性のある) それらの情報を配下のロガーへの呼び出
しに渡し直します。このメソッドのデフォルト実装ではメッセージは元のまま
ですが、キーワード引数にはコンストラクタに渡された辞書風オブジェクトを
値として "extra" キーが挿入されます。もちろん、呼び出し時に "extra" キ
ーワードを使った場合には何事もなかったかのように上書きされます。

"extra" を用いる利点は辞書風オブジェクトの中の値が "LogRecord" インス
タンスの __dict__ にマージされることで、辞書風オブジェクトのキーを知っ
ている "Formatter" を用意して文字列をカスタマイズするようにできること
です。それ以外のメソッドが必要なとき、たとえばコンテキスト情報をメッセ
ージの前や後ろにつなげたい場合には、 "LoggerAdapter" から "process()"
を望むようにオーバライドしたサブクラスを作ることが必要なだけです。次に
挙げるのはこのクラスを使った例で、コンストラクタで使われる「辞書風」オ
ブジェクトにどの振る舞いが必要なのかも示しています:

   class CustomAdapter(logging.LoggerAdapter):
       """
       This example adapter expects the passed in dict-like object to have a
       'connid' key, whose value in brackets is prepended to the log message.
       """
       def process(self, msg, kwargs):
           return '[%s] %s' % (self.extra['connid'], msg), kwargs

これを次のように使うことができます:

   logger = logging.getLogger(__name__)
   adapter = CustomAdapter(logger, {'connid': some_conn_id})

これで、この adapter 経由でログした全てのイベントに対して、
"some_conn_id" の値がログメッセージの前に追加されます。


コンテキスト情報を渡すために dict 以外のオブジェクトを使う
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

"LoggerAdapter" に渡すのは本物の dict でなくても構いません。
"__getitem__" と "__iter__" を実装していて logging が辞書のように扱え
るクラスのインスタンスを利用することができます。これは (dict の値が固
定されるのに対して) 値を動的に生成できるので便利です。


Filter を使ったコンテキスト情報の伝達
-------------------------------------

ユーザ定義の "Filter" を使ってログ出力にコンテキスト情報を加えることも
できます。 "Filter" インスタンスは、渡された "LogRecords" を修正するこ
とができます。これにより、適切なフォーマット文字列や必要なら
"Formatter" を使って、出力となる属性を新しく追加することも出来ます。

例えば、web アプリケーションで、処理されるリクエスト (または、少なくと
もその重要な部分) は、スレッドローカル ("threading.local") な変数に保
存して、 "Filter" からアクセスすることで、 "LogRecord" にリクエストの
情報を追加できます。例えば、リモート IP アドレスやリモートユーザのユー
ザ名にアクセスしたいなら、上述の "LoggerAdapter" の例のように属性名
'ip' や 'user' を使うといったようにです。その場合、同じフォーマット文
字列を使って以下に示すように似たような出力を得られます。これはスクリプ
トの例です:

   import logging
   from random import choice

   class ContextFilter(logging.Filter):
       """
       This is a filter which injects contextual information into the log.

       Rather than use actual contextual information, we just use random
       data in this demo.
       """

       USERS = ['jim', 'fred', 'sheila']
       IPS = ['123.231.231.123', '127.0.0.1', '192.168.0.1']

       def filter(self, record):

           record.ip = choice(ContextFilter.IPS)
           record.user = choice(ContextFilter.USERS)
           return True

   if __name__ == '__main__':
       levels = (logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR, logging.CRITICAL)
       logging.basicConfig(level=logging.DEBUG,
                           format='%(asctime)-15s %(name)-5s %(levelname)-8s IP: %(ip)-15s User: %(user)-8s %(message)s')
       a1 = logging.getLogger('a.b.c')
       a2 = logging.getLogger('d.e.f')

       f = ContextFilter()
       a1.addFilter(f)
       a2.addFilter(f)
       a1.debug('A debug message')
       a1.info('An info message with %s', 'some parameters')
       for x in range(10):
           lvl = choice(levels)
           lvlname = logging.getLevelName(lvl)
           a2.log(lvl, 'A message at %s level with %d %s', lvlname, 2, 'parameters')

実行すると、以下のようになります:

   2010-09-06 22:38:15,292 a.b.c DEBUG    IP: 123.231.231.123 User: fred     A debug message
   2010-09-06 22:38:15,300 a.b.c INFO     IP: 192.168.0.1     User: sheila   An info message with some parameters
   2010-09-06 22:38:15,300 d.e.f CRITICAL IP: 127.0.0.1       User: sheila   A message at CRITICAL level with 2 parameters
   2010-09-06 22:38:15,300 d.e.f ERROR    IP: 127.0.0.1       User: jim      A message at ERROR level with 2 parameters
   2010-09-06 22:38:15,300 d.e.f DEBUG    IP: 127.0.0.1       User: sheila   A message at DEBUG level with 2 parameters
   2010-09-06 22:38:15,300 d.e.f ERROR    IP: 123.231.231.123 User: fred     A message at ERROR level with 2 parameters
   2010-09-06 22:38:15,300 d.e.f CRITICAL IP: 192.168.0.1     User: jim      A message at CRITICAL level with 2 parameters
   2010-09-06 22:38:15,300 d.e.f CRITICAL IP: 127.0.0.1       User: sheila   A message at CRITICAL level with 2 parameters
   2010-09-06 22:38:15,300 d.e.f DEBUG    IP: 192.168.0.1     User: jim      A message at DEBUG level with 2 parameters
   2010-09-06 22:38:15,301 d.e.f ERROR    IP: 127.0.0.1       User: sheila   A message at ERROR level with 2 parameters
   2010-09-06 22:38:15,301 d.e.f DEBUG    IP: 123.231.231.123 User: fred     A message at DEBUG level with 2 parameters
   2010-09-06 22:38:15,301 d.e.f INFO     IP: 123.231.231.123 User: fred     A message at INFO level with 2 parameters


複数のプロセスからの単一ファイルへのログ記録
============================================

ログ記録はスレッドセーフであり、単一プロセスの複数のスレッドからの単一
ファイルへのログ記録はサポート *されています* が、 *複数プロセス* から
の単一ファイルへのログ記録はサポート *されません* 。なぜなら、複数のプ
ロセスをまたいで単一のファイルへのアクセスを直列化する標準の方法が
Python には存在しないからです。複数のプロセスから単一ファイルへログ記
録しなければならないなら、最も良い方法は、すべてのプロセスが
"SocketHandler" に対してログ記録を行い、独立したプロセスとしてソケット
サーバを動かすことです。ソケットサーバはソケットから読み取ってファイル
にログを書き出します。 (この機能を実行するために、既存のプロセスの 1
つのスレッドを割り当てることもできます) この節 では、このアプローチを
さらに詳細に文書化しています。動作するソケット受信プログラムが含まれて
いるので、アプリケーションに組み込むための出発点として使用できるでしょ
う。

"multiprocessing" モジュールを含む最近のバージョンの Python を使用して
いるなら、複数のプロセスからファイルへのアクセスを直列化するために
"Lock" クラスを使って独自のハンドラを書くことができます。既存の
"FileHandler" とそのサブクラスは現在のところ "multiprocessing" を利用
していませんが、将来は利用するようになるかもしれません。現在のところ
"multiprocessing" モジュールが提供するロック機能はすべてのプラットホー
ムで動作するわけではないことに注意してください
(https://bugs.python.org/issue3770 参照)。

別の方法として、 "Queue" と "QueueHandler" を使って、マルチプロセスア
プリケーションの1つのプロセスに全ての logging イベントを送る事ができま
す。次の例はこれを行う方法を示します。この例では独立した listener プロ
セスが他のプロセスから送られた event を受け取り、それを独自の logging
設定にしたがって保存します。この例は実装の方法の1つを示しているだけ (
例えば、 listener プロセスを分離する代わりに listener スレッドを使うこ
ともできます) ですが、これは listener とアプリケーション内の他のプロセ
スで完全に異なる設定を使う例になっているので、各自の要求に応じたコード
を書く叩き台になるでしょう:

   # You'll need these imports in your own code
   import logging
   import logging.handlers
   import multiprocessing

   # Next two import lines for this demo only
   from random import choice, random
   import time

   #
   # Because you'll want to define the logging configurations for listener and workers, the
   # listener and worker process functions take a configurer parameter which is a callable
   # for configuring logging for that process. These functions are also passed the queue,
   # which they use for communication.
   #
   # In practice, you can configure the listener however you want, but note that in this
   # simple example, the listener does not apply level or filter logic to received records.
   # In practice, you would probably want to do this logic in the worker processes, to avoid
   # sending events which would be filtered out between processes.
   #
   # The size of the rotated files is made small so you can see the results easily.
   def listener_configurer():
       root = logging.getLogger()
       h = logging.handlers.RotatingFileHandler('mptest.log', 'a', 300, 10)
       f = logging.Formatter('%(asctime)s %(processName)-10s %(name)s %(levelname)-8s %(message)s')
       h.setFormatter(f)
       root.addHandler(h)

   # This is the listener process top-level loop: wait for logging events
   # (LogRecords)on the queue and handle them, quit when you get a None for a
   # LogRecord.
   def listener_process(queue, configurer):
       configurer()
       while True:
           try:
               record = queue.get()
               if record is None:  # We send this as a sentinel to tell the listener to quit.
                   break
               logger = logging.getLogger(record.name)
               logger.handle(record)  # No level or filter logic applied - just do it!
           except Exception:
               import sys, traceback
               print('Whoops! Problem:', file=sys.stderr)
               traceback.print_exc(file=sys.stderr)

   # Arrays used for random selections in this demo

   LEVELS = [logging.DEBUG, logging.INFO, logging.WARNING,
             logging.ERROR, logging.CRITICAL]

   LOGGERS = ['a.b.c', 'd.e.f']

   MESSAGES = [
       'Random message #1',
       'Random message #2',
       'Random message #3',
   ]

   # The worker configuration is done at the start of the worker process run.
   # Note that on Windows you can't rely on fork semantics, so each process
   # will run the logging configuration code when it starts.
   def worker_configurer(queue):
       h = logging.handlers.QueueHandler(queue)  # Just the one handler needed
       root = logging.getLogger()
       root.addHandler(h)
       # send all messages, for demo; no other level or filter logic applied.
       root.setLevel(logging.DEBUG)

   # This is the worker process top-level loop, which just logs ten events with
   # random intervening delays before terminating.
   # The print messages are just so you know it's doing something!
   def worker_process(queue, configurer):
       configurer(queue)
       name = multiprocessing.current_process().name
       print('Worker started: %s' % name)
       for i in range(10):
           time.sleep(random())
           logger = logging.getLogger(choice(LOGGERS))
           level = choice(LEVELS)
           message = choice(MESSAGES)
           logger.log(level, message)
       print('Worker finished: %s' % name)

   # Here's where the demo gets orchestrated. Create the queue, create and start
   # the listener, create ten workers and start them, wait for them to finish,
   # then send a None to the queue to tell the listener to finish.
   def main():
       queue = multiprocessing.Queue(-1)
       listener = multiprocessing.Process(target=listener_process,
                                          args=(queue, listener_configurer))
       listener.start()
       workers = []
       for i in range(10):
           worker = multiprocessing.Process(target=worker_process,
                                            args=(queue, worker_configurer))
           workers.append(worker)
           worker.start()
       for w in workers:
           w.join()
       queue.put_nowait(None)
       listener.join()

   if __name__ == '__main__':
       main()

上のスクリプトの亜種で、logging をメインプロセスの別スレッドで行う例:

   import logging
   import logging.config
   import logging.handlers
   from multiprocessing import Process, Queue
   import random
   import threading
   import time

   def logger_thread(q):
       while True:
           record = q.get()
           if record is None:
               break
           logger = logging.getLogger(record.name)
           logger.handle(record)


   def worker_process(q):
       qh = logging.handlers.QueueHandler(q)
       root = logging.getLogger()
       root.setLevel(logging.DEBUG)
       root.addHandler(qh)
       levels = [logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR,
                 logging.CRITICAL]
       loggers = ['foo', 'foo.bar', 'foo.bar.baz',
                  'spam', 'spam.ham', 'spam.ham.eggs']
       for i in range(100):
           lvl = random.choice(levels)
           logger = logging.getLogger(random.choice(loggers))
           logger.log(lvl, 'Message no. %d', i)

   if __name__ == '__main__':
       q = Queue()
       d = {
           'version': 1,
           'formatters': {
               'detailed': {
                   'class': 'logging.Formatter',
                   'format': '%(asctime)s %(name)-15s %(levelname)-8s %(processName)-10s %(message)s'
               }
           },
           'handlers': {
               'console': {
                   'class': 'logging.StreamHandler',
                   'level': 'INFO',
               },
               'file': {
                   'class': 'logging.FileHandler',
                   'filename': 'mplog.log',
                   'mode': 'w',
                   'formatter': 'detailed',
               },
               'foofile': {
                   'class': 'logging.FileHandler',
                   'filename': 'mplog-foo.log',
                   'mode': 'w',
                   'formatter': 'detailed',
               },
               'errors': {
                   'class': 'logging.FileHandler',
                   'filename': 'mplog-errors.log',
                   'mode': 'w',
                   'level': 'ERROR',
                   'formatter': 'detailed',
               },
           },
           'loggers': {
               'foo': {
                   'handlers': ['foofile']
               }
           },
           'root': {
               'level': 'DEBUG',
               'handlers': ['console', 'file', 'errors']
           },
       }
       workers = []
       for i in range(5):
           wp = Process(target=worker_process, name='worker %d' % (i + 1), args=(q,))
           workers.append(wp)
           wp.start()
       logging.config.dictConfig(d)
       lp = threading.Thread(target=logger_thread, args=(q,))
       lp.start()
       # At this point, the main process could do some useful work of its own
       # Once it's done that, it can wait for the workers to terminate...
       for wp in workers:
           wp.join()
       # And now tell the logging thread to finish up, too
       q.put(None)
       lp.join()

こちらは特定の logger に設定を適用する例になっています。"foo" logger
は "foo" サブシステムの中の全てのイベントを "mplog-foo.log" に保存する
特別な handler を持っています。これはメインプロセス側の log 処理で使わ
れ、(logging イベントは worker プロセス側で生成されますが) 各メッセー
ジを適切な出力先に出力します。


ファイルをローテートする
========================

ログファイルがある大きさに達したら、新しいファイルを開いてそこにログを
取りたいことがあります。そのファイルをある数だけ残し、その数のファイル
が生成されたらファイルを循環し、ファイルの数も大きさも制限したいことも
あるでしょう。この利用パターンのために、logging パッケージは
"RotatingFileHandler" を提供しています:

   import glob
   import logging
   import logging.handlers

   LOG_FILENAME = 'logging_rotatingfile_example.out'

   # Set up a specific logger with our desired output level
   my_logger = logging.getLogger('MyLogger')
   my_logger.setLevel(logging.DEBUG)

   # Add the log message handler to the logger
   handler = logging.handlers.RotatingFileHandler(
                 LOG_FILENAME, maxBytes=20, backupCount=5)

   my_logger.addHandler(handler)

   # Log some messages
   for i in range(20):
       my_logger.debug('i = %d' % i)

   # See what files are created
   logfiles = glob.glob('%s*' % LOG_FILENAME)

   for filename in logfiles:
       print(filename)

The result should be 6 separate files, each with part of the log
history for the application:

   logging_rotatingfile_example.out
   logging_rotatingfile_example.out.1
   logging_rotatingfile_example.out.2
   logging_rotatingfile_example.out.3
   logging_rotatingfile_example.out.4
   logging_rotatingfile_example.out.5

最新のファイルはいつでも "logging_rotatingfile_example.out" で、サイズ
の上限に達するたびに拡張子 ".1" を付けた名前に改名されます。既にあるバ
ックアップファイルはその拡張子がインクリメントされ (".1" が ".2" にな
るなど)、 ".6" ファイルは消去されます。

明らかに、ここでは極端な例示のためにファイルの大きさをかなり小さな値に
設定しています。実際に使うときは *maxBytes* を適切な値に設定してくださ
い。


別の format スタイルを利用する
==============================

logging が Python 標準ライブラリに追加された時、メッセージを動的な内容
でフォーマットする唯一の方法は % を使ったフォーマットでした。その後、
Python には新しい文字列フォーマット機構として "string.Template"
(Python 2.4 で追加) と "str.format()" (Python 2.6 で追加) が加わりまし
た。

logging は (3.2 から) この2つの追加されたフォーマット方法をサポートし
ています。 "Formatter" クラスが "style" という名前のオプションのキーワ
ード引数を受け取ります。このデフォルト値は "'%'" ですが、他に "'{'" と
"'$'" が指定可能で、それぞれのフォーマット方法に対応しています。後方互
換性はデフォルト値によって維持されていますが、明示的に style 引数を指
定することで、 "str.format()" か "string.Template" を使った format を
指定する事ができます。次の例はこの機能を使ってみています:

   >>> import logging
   >>> root = logging.getLogger()
   >>> root.setLevel(logging.DEBUG)
   >>> handler = logging.StreamHandler()
   >>> bf = logging.Formatter('{asctime} {name} {levelname:8s} {message}',
   ...                        style='{')
   >>> handler.setFormatter(bf)
   >>> root.addHandler(handler)
   >>> logger = logging.getLogger('foo.bar')
   >>> logger.debug('This is a DEBUG message')
   2010-10-28 15:11:55,341 foo.bar DEBUG    This is a DEBUG message
   >>> logger.critical('This is a CRITICAL message')
   2010-10-28 15:12:11,526 foo.bar CRITICAL This is a CRITICAL message
   >>> df = logging.Formatter('$asctime $name ${levelname} $message',
   ...                        style='$')
   >>> handler.setFormatter(df)
   >>> logger.debug('This is a DEBUG message')
   2010-10-28 15:13:06,924 foo.bar DEBUG This is a DEBUG message
   >>> logger.critical('This is a CRITICAL message')
   2010-10-28 15:13:11,494 foo.bar CRITICAL This is a CRITICAL message
   >>>

最終的に出力されるログメッセージの format と、各メッセージを生成する部
分は完全に独立していることに注意してください。次の例でわかるように、メ
ッセージを生成する部分では % を使い続けています:

   >>> logger.error('This is an%s %s %s', 'other,', 'ERROR,', 'message')
   2010-10-28 15:19:29,833 foo.bar ERROR This is another, ERROR, message
   >>>

logging の呼び出し ("logger.debug()" や "logger.info()" など) は、ログ
メッセージのために位置引数しか受け取らず、キーワード引数はそれを処理す
るときのオプションを指定するためだけに使われます。 (例えば、
"exc_info" キーワード引数を使ってログを取るトレースバック情報を指定し
たり、 "extra" キーワード引数を使ってログに付与する追加のコンテキスト
情報を指定します。) logging パッケージは内部で % を使って format 文字
列と引数をマージしているので、 "str.format()" や "string.Template" を
使って logging を呼び出す事はできません。既存の logging 呼び出しは
%-format を使っているので、後方互換性のためにこの部分を変更することは
できません。

しかし、{} や $ を使ってログメッセージをフォーマットする方法はあります
。ログメッセージには任意のオブジェクトを format 文字列として渡すことが
でき、logging パッケージはそのオブジェクトに対して "str()" を使って実
際の format 文字列を生成します。次の2つのクラスを見てください:

   class BraceMessage:
       def __init__(self, fmt, *args, **kwargs):
           self.fmt = fmt
           self.args = args
           self.kwargs = kwargs

       def __str__(self):
           return self.fmt.format(*self.args, **self.kwargs)

   class DollarMessage:
       def __init__(self, fmt, **kwargs):
           self.fmt = fmt
           self.kwargs = kwargs

       def __str__(self):
           from string import Template
           return Template(self.fmt).substitute(**self.kwargs)

どちらのクラスも format 文字列の代わりに利用して、 {} や $ を使って実
際のログの "%(message)s", "{message}", "$message" で指定された
"message" 部分を生成することができます。これは何かログを取りたいときに
常に使うには使いにくいクラス名ですが、 __ (アンダースコア2つ ---
"gettext.gettext()" やその仲間によくエイリアスとして使われるアンダース
コア1つと混同しないように) などの使いやすいエイリアスを使うことができ
ます。

上のクラスは Python には含まれませんが、自分のコードにコピペして使うの
は簡単です。これらは次の例のようにして利用できます。(上のクラスが
"wherever" というモジュールで定義されていると仮定します):

   >>> from wherever import BraceMessage as __
   >>> print(__('Message with {0} {name}', 2, name='placeholders'))
   Message with 2 placeholders
   >>> class Point: pass
   ...
   >>> p = Point()
   >>> p.x = 0.5
   >>> p.y = 0.5
   >>> print(__('Message with coordinates: ({point.x:.2f}, {point.y:.2f})',
   ...       point=p))
   Message with coordinates: (0.50, 0.50)
   >>> from wherever import DollarMessage as __
   >>> print(__('Message with $num $what', num=2, what='placeholders'))
   Message with 2 placeholders
   >>>

上の例ではフォーマットの動作を示すために "print()" を使っていますが、
もちろん実際にこの方法でログを出力するには "logger.debug()" などを使い
ます。

注意点として、この方法には大きなパフォーマンスのペナルティはありません
。実際のフォーマット操作は logging の呼び出し時ではなくて、メッセージ
が実際に handler によって出力されるときに起こります。(出力されないなら
フォーマットもされません) そのため、この方法で注意しないといけないのは
、追加の括弧がフォーマット文字列だけではなく引数も囲わないといけないこ
とだけです。これは __ が XXXMessage クラスのコンストラクタ呼び出しのシ
ンタックスシュガーでしか無いからです。

次の例のように、 "LoggerAdapter" を利用して上と似たような効果を実現す
る方法もあります:

   import logging

   class Message(object):
       def __init__(self, fmt, args):
           self.fmt = fmt
           self.args = args

       def __str__(self):
           return self.fmt.format(*self.args)

   class StyleAdapter(logging.LoggerAdapter):
       def __init__(self, logger, extra=None):
           super(StyleAdapter, self).__init__(logger, extra or {})

       def log(self, level, msg, *args, **kwargs):
           if self.isEnabledFor(level):
               msg, kwargs = self.process(msg, kwargs)
               self.logger._log(level, Message(msg, args), (), **kwargs)

   logger = StyleAdapter(logging.getLogger(__name__))

   def main():
       logger.debug('Hello, {}', 'world!')

   if __name__ == '__main__':
       logging.basicConfig(level=logging.DEBUG)
       main()

上のスクリプトは Python 3.2 以降では "Hello, world!" というメッセージ
をログするはずです。


"LogRecord" のカスタマイズ
==========================

全ての logging イベントは "LogRecord" のインスタンスとして表現されます
。イベントのログが取られて logger のレベルでフィルタされなかった場合、
イベントの情報を含む "LogRecord" が生成され、その logger (と、
propagate が無効になるまでの上位 logger) の handler に渡されます。
Python 3.2 までは、この生成が行われているのは2箇所だけでした:

* "Logger.makeRecord()": 通常のイベント logging プロセスで呼ばれます。
  これは "LogRecord" を直接読んでインスタンスを生成します。

* "makeLogRecord()": LogRecord に追加される属性を含む辞書を渡して呼び
  出されます。これはネットワーク越しに (pickle 形式で "SocketHandler"
  経由で、あるいは JSON 形式で "HTTPHandler" 経由で) 辞書を受け取った
  場合などに利用されます。

そのために "LogRecord" で何か特別なことをしたい場合は、次のどちらかを
しなければなりません。

* "Logger.makeRecord()" をオーバーライドした独自の "Logger" のサブクラ
  スを作り、利用したい logger のどれかがインスタンス化される前に、それ
  を "setLoggerClass()" を使って登録する。

* "filter()" メソッドで必要な特殊な処理を行う "Filter" を logger か
  handler に追加する。

最初の方法は、複数の異なるライブラリが別々のことをしようとした場合にう
まく行きません。各ライブラリが独自の "Logger" のサブクラスを登録しよう
として、最後に登録されたライブラリが生き残ります。

2つ目の方法はほとんどのケースでうまくいきますが、たとえば "LogRecord"
を特殊化したサブクラスを使うことなどはできません。ライブラリの開発者は
利用している logger に適切な filter を設定できますが、新しい logger を
作るたびに忘れずに設定しないといけなくなります。 (新しいパッケージやモ
ジュールを追加し、モジュールレベルで次の式を実行することで、新しい
logger が作られます)

   logger = logging.getLogger(__name__)

これでは考えることが余計に1つ増えてしまうでしょう。開発者は、最も高い
レベルのロガーに取り付けられた "NullHandler" に、フィルタを追加するこ
ともできますが、アプリケーション開発者が、より低いレベルに対するライブ
ラリのロガーにハンドラを取り付けた場合、フィルタは呼び出されません ---
従って、そのハンドラからの出力はライブラリ開発者の意図を反映したものに
はなりません。

Python 3.2 以降では、 "LogRecord" の生成は、指定できるファクトリ経由に
なります。ファクトリは callable で、 "setLogRecordFactory()" で登録で
き、 "getLogRecordFactory()" で現在のファクトリを取得できます。ファク
トリは "LogRecord" コンストラクタと同じシグネチャで呼び出され、
"LogRecord" がデフォルトのファクトリとして設定されています。

このアプローチはカスタムのファクトリが 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)

このアプローチでは複数の異なるライブラリがファクトリをチェインさせて、
お互いに同じ属性を上書きしたり、標準で提供されている属性を意図せず上書
きしない限りはうまくいきます。しかし、チェインのつながり全てが、全ての
logging の操作に対しての実行時のオーバーヘッドになることを念頭に置き、
このテクニックは "Filter" を利用するだけでは望む結果が得られない場合に
のみ使うべきです。


QueueHandler を継承する - ZeroMQ を使う例
=========================================

"QueueHandler" のサブクラスを作ってメッセージを他のキュー、例えば
ZeroMQ の 'publish' ソケットに送信することができます。下の例では、ソケ
ットを別に作ってそれを handler に ('queue' として) 渡します:

   import zmq   # using pyzmq, the Python binding for ZeroMQ
   import json  # for serializing records portably

   ctx = zmq.Context()
   sock = zmq.Socket(ctx, zmq.PUB)  # or zmq.PUSH, or other suitable value
   sock.bind('tcp://*:5556')        # or wherever

   class ZeroMQSocketHandler(QueueHandler):
       def enqueue(self, record):
           self.queue.send_json(record.__dict__)


   handler = ZeroMQSocketHandler(sock)

もちろん同じことを別の設計でもできます。socket を作るのに必要な情報を
handler に渡す例です:

   class ZeroMQSocketHandler(QueueHandler):
       def __init__(self, uri, socktype=zmq.PUB, ctx=None):
           self.ctx = ctx or zmq.Context()
           socket = zmq.Socket(self.ctx, socktype)
           socket.bind(uri)
           super().__init__(socket)

       def enqueue(self, record):
           self.queue.send_json(record.__dict__)

       def close(self):
           self.queue.close()


QueueListener のサブクラスを作る - ZeroMQ を使う例
==================================================

"QueueListener" のサブクラスを作って、メッセージを他のキュー、例えば
ZeroMQ の 'subscribe' ソケットから取得する事もできます。サンプルです:

   class ZeroMQSocketListener(QueueListener):
       def __init__(self, uri, *handlers, **kwargs):
           self.ctx = kwargs.get('ctx') or zmq.Context()
           socket = zmq.Socket(self.ctx, zmq.SUB)
           socket.setsockopt_string(zmq.SUBSCRIBE, '')  # subscribe to everything
           socket.connect(uri)
           super().__init__(socket, *handlers, **kwargs)

       def dequeue(self):
           msg = self.queue.recv_json()
           return logging.makeLogRecord(msg)

参考:

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

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

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

  logging 基本チュートリアル

  logging 上級チュートリアル


辞書ベースで構成する例
======================

次の例は辞書を使った logging の構成です。この例は Django プロジェクト
のドキュメント から持ってきました。この辞書を "dictConfig()" に渡して
設定を有効にします:

   LOGGING = {
       'version': 1,
       'disable_existing_loggers': True,
       'formatters': {
           'verbose': {
               'format': '%(levelname)s %(asctime)s %(module)s %(process)d %(thread)d %(message)s'
           },
           'simple': {
               'format': '%(levelname)s %(message)s'
           },
       },
       'filters': {
           'special': {
               '()': 'project.logging.SpecialFilter',
               'foo': 'bar',
           }
       },
       'handlers': {
           'null': {
               'level':'DEBUG',
               'class':'django.utils.log.NullHandler',
           },
           'console':{
               'level':'DEBUG',
               'class':'logging.StreamHandler',
               'formatter': 'simple'
           },
           'mail_admins': {
               'level': 'ERROR',
               'class': 'django.utils.log.AdminEmailHandler',
               'filters': ['special']
           }
       },
       'loggers': {
           'django': {
               'handlers':['null'],
               'propagate': True,
               'level':'INFO',
           },
           'django.request': {
               'handlers': ['mail_admins'],
               'level': 'ERROR',
               'propagate': False,
           },
           'myproject.custom': {
               'handlers': ['console', 'mail_admins'],
               'level': 'INFO',
               'filters': ['special']
           }
       }
   }

この構成方法についてのより詳しい情報は、 Django のドキュメントの 該当
のセクション で見ることができます。


rotator と namer を使ってログローテートをカスタマイズする
=========================================================

次の、ログファイルを zlib ベースの圧縮をするスニペットでは、namer と
rotater を定義する方法の例を提供してます:

   def namer(name):
       return name + ".gz"

   def rotator(source, dest):
       with open(source, "rb") as sf:
           data = sf.read()
           compressed = zlib.compress(data, 9)
           with open(dest, "wb") as df:
               df.write(compressed)
       os.remove(source)

   rh = logging.handlers.RotatingFileHandler(...)
   rh.rotator = rotator
   rh.namer = namer

これは本当の .gz ファイルではなく、実際の gzip ファイルが持っている "
コンテナ" がない生の圧縮データです。このスニペットはただの解説用です。


より手の込んだ multiprocessing の例
===================================

次の実際に動作する例は、logging を multiprocessing と設定ファイルを使
って利用する方法を示しています。設定内容はかなりシンプルですが、より複
雑な構成を実際の multiprocessing を利用するシナリオで実装する方法を示
しています。

この例では、メインプロセスは listener プロセスといくつかのワーカープロ
セスを起動します。メイン、listener、ワーカープロセスはそれぞれ分離した
設定を持っています (ワーカープロセス群は同じ設定を共有します)。この例
から、メインプロセスの logging, ワーカーが QueueHandler でログを送って
いるところ、listener が利用する QueueListener の実装、複雑な設定、キュ
ーから受け取ったイベントを設定された handler に分配する部分を見ること
ができます。この設定は説明用のものですが、この例を自分のシナリオに適応
させることができるでしょう。

これがそのスクリプトです。docstring とコメントで動作を説明しています:

   import logging
   import logging.config
   import logging.handlers
   from multiprocessing import Process, Queue, Event, current_process
   import os
   import random
   import time

   class MyHandler:
       """
       A simple handler for logging events. It runs in the listener process and
       dispatches events to loggers based on the name in the received record,
       which then get dispatched, by the logging system, to the handlers
       configured for those loggers.
       """
       def handle(self, record):
           logger = logging.getLogger(record.name)
           # The process name is transformed just to show that it's the listener
           # doing the logging to files and console
           record.processName = '%s (for %s)' % (current_process().name, record.processName)
           logger.handle(record)

   def listener_process(q, stop_event, config):
       """
       This could be done in the main process, but is just done in a separate
       process for illustrative purposes.

       This initialises logging according to the specified configuration,
       starts the listener and waits for the main process to signal completion
       via the event. The listener is then stopped, and the process exits.
       """
       logging.config.dictConfig(config)
       listener = logging.handlers.QueueListener(q, MyHandler())
       listener.start()
       if os.name == 'posix':
           # On POSIX, the setup logger will have been configured in the
           # parent process, but should have been disabled following the
           # dictConfig call.
           # On Windows, since fork isn't used, the setup logger won't
           # exist in the child, so it would be created and the message
           # would appear - hence the "if posix" clause.
           logger = logging.getLogger('setup')
           logger.critical('Should not appear, because of disabled logger ...')
       stop_event.wait()
       listener.stop()

   def worker_process(config):
       """
       A number of these are spawned for the purpose of illustration. In
       practice, they could be a heterogeneous bunch of processes rather than
       ones which are identical to each other.

       This initialises logging according to the specified configuration,
       and logs a hundred messages with random levels to randomly selected
       loggers.

       A small sleep is added to allow other processes a chance to run. This
       is not strictly needed, but it mixes the output from the different
       processes a bit more than if it's left out.
       """
       logging.config.dictConfig(config)
       levels = [logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR,
                 logging.CRITICAL]
       loggers = ['foo', 'foo.bar', 'foo.bar.baz',
                  'spam', 'spam.ham', 'spam.ham.eggs']
       if os.name == 'posix':
           # On POSIX, the setup logger will have been configured in the
           # parent process, but should have been disabled following the
           # dictConfig call.
           # On Windows, since fork isn't used, the setup logger won't
           # exist in the child, so it would be created and the message
           # would appear - hence the "if posix" clause.
           logger = logging.getLogger('setup')
           logger.critical('Should not appear, because of disabled logger ...')
       for i in range(100):
           lvl = random.choice(levels)
           logger = logging.getLogger(random.choice(loggers))
           logger.log(lvl, 'Message no. %d', i)
           time.sleep(0.01)

   def main():
       q = Queue()
       # The main process gets a simple configuration which prints to the console.
       config_initial = {
           'version': 1,
           'formatters': {
               'detailed': {
                   'class': 'logging.Formatter',
                   'format': '%(asctime)s %(name)-15s %(levelname)-8s %(processName)-10s %(message)s'
               }
           },
           'handlers': {
               'console': {
                   'class': 'logging.StreamHandler',
                   'level': 'INFO',
               },
           },
           'root': {
               'level': 'DEBUG',
               'handlers': ['console']
           },
       }
       # The worker process configuration is just a QueueHandler attached to the
       # root logger, which allows all messages to be sent to the queue.
       # We disable existing loggers to disable the "setup" logger used in the
       # parent process. This is needed on POSIX because the logger will
       # be there in the child following a fork().
       config_worker = {
           'version': 1,
           'disable_existing_loggers': True,
           'handlers': {
               'queue': {
                   'class': 'logging.handlers.QueueHandler',
                   'queue': q,
               },
           },
           'root': {
               'level': 'DEBUG',
               'handlers': ['queue']
           },
       }
       # The listener process configuration shows that the full flexibility of
       # logging configuration is available to dispatch events to handlers however
       # you want.
       # We disable existing loggers to disable the "setup" logger used in the
       # parent process. This is needed on POSIX because the logger will
       # be there in the child following a fork().
       config_listener = {
           'version': 1,
           'disable_existing_loggers': True,
           'formatters': {
               'detailed': {
                   'class': 'logging.Formatter',
                   'format': '%(asctime)s %(name)-15s %(levelname)-8s %(processName)-10s %(message)s'
               },
               'simple': {
                   'class': 'logging.Formatter',
                   'format': '%(name)-15s %(levelname)-8s %(processName)-10s %(message)s'
               }
           },
           'handlers': {
               'console': {
                   'class': 'logging.StreamHandler',
                   'level': 'INFO',
                   'formatter': 'simple',
               },
               'file': {
                   'class': 'logging.FileHandler',
                   'filename': 'mplog.log',
                   'mode': 'w',
                   'formatter': 'detailed',
               },
               'foofile': {
                   'class': 'logging.FileHandler',
                   'filename': 'mplog-foo.log',
                   'mode': 'w',
                   'formatter': 'detailed',
               },
               'errors': {
                   'class': 'logging.FileHandler',
                   'filename': 'mplog-errors.log',
                   'mode': 'w',
                   'level': 'ERROR',
                   'formatter': 'detailed',
               },
           },
           'loggers': {
               'foo': {
                   'handlers': ['foofile']
               }
           },
           'root': {
               'level': 'DEBUG',
               'handlers': ['console', 'file', 'errors']
           },
       }
       # Log some initial events, just to show that logging in the parent works
       # normally.
       logging.config.dictConfig(config_initial)
       logger = logging.getLogger('setup')
       logger.info('About to create workers ...')
       workers = []
       for i in range(5):
           wp = Process(target=worker_process, name='worker %d' % (i + 1),
                        args=(config_worker,))
           workers.append(wp)
           wp.start()
           logger.info('Started worker: %s', wp.name)
       logger.info('About to create listener ...')
       stop_event = Event()
       lp = Process(target=listener_process, name='listener',
                    args=(q, stop_event, config_listener))
       lp.start()
       logger.info('Started listener')
       # We now hang around for the workers to finish their work.
       for wp in workers:
           wp.join()
       # Workers all done, listening can now stop.
       # Logging in the parent still works normally.
       logger.info('Telling listener to stop ...')
       stop_event.set()
       lp.join()
       logger.info('All done.')

   if __name__ == '__main__':
       main()


SysLogHandler に送るメッセージに BOM を挿入する
===============================================

**RFC 5424** requires that a Unicode message be sent to a syslog
daemon as a set of bytes which have the following structure: an
optional pure-ASCII component, followed by a UTF-8 Byte Order Mark
(BOM), followed by Unicode encoded using UTF-8. (See the **relevant
section of the specification**.)

Python 3.1 で "SysLogHandler" に、 message に BOM を挿入するコードが追
加されました。しかし、そのときの実装が悪くて、 message の先頭に BOM を
つけてしまうのでピュアASCII 部分をその前に書くことができませんでした。

As this behaviour is broken, the incorrect BOM insertion code is being
removed from Python 3.2.4 and later. However, it is not being
replaced, and if you want to produce **RFC 5424**-compliant messages
which include a BOM, an optional pure-ASCII sequence before it and
arbitrary Unicode after it, encoded using UTF-8, then you need to do
the following:

1. "SysLogHandler" のインスタンスに、次のような format 文字列を持った
   "Formatter" インスタンスをアタッチする:

      'ASCII section\ufeffUnicode section'

   Unicode のコードポイント U+FEFF は、UTF-8 でエンコードすると BOM --
   "b'\xef\xbb\xbf'" -- になります。

2. ASCII セクションを好きなプレースホルダに変更する。ただしその部分の
   置換結果が常に ASCII になるように注意する(UTF-8 でエンコードされて
   もその部分が変化しないようにする)。

3. Unicode セクションを任意のプレースホルダに置き換える。この部分を置
   換したデータに ASCII 外の文字が含まれていても、それは単に UTF-8 で
   エンコードされるだけです。

The formatted message *will* be encoded using UTF-8 encoding by
"SysLogHandler". If you follow the above rules, you should be able to
produce **RFC 5424**-compliant messages. If you don't, logging may not
complain, but your messages will not be RFC 5424-compliant, and your
syslog daemon may complain.


構造化ログを実装する
====================

多くのログメッセージは人間が読むために書かれるため、機械的に処理しにく
くなっていますが、場合によっては (複雑な正規表現を使ってログメッセージ
をパースしなくても) プログラムがパース *できる* 構造化されたフォーマッ
トでメッセージを出力したい場合があります。 logging パッケージを使うと
、これを簡単に実現できます。 実現する方法は幾つもありますが、次の例は
JSON を使ってイベントを、機械でパースできる形にシリアライズする単純な
方法です:

   import json
   import logging

   class StructuredMessage(object):
       def __init__(self, message, **kwargs):
           self.message = message
           self.kwargs = kwargs

       def __str__(self):
           return '%s >>> %s' % (self.message, json.dumps(self.kwargs))

   _ = StructuredMessage   # optional, to improve readability

   logging.basicConfig(level=logging.INFO, format='%(message)s')
   logging.info(_('message 1', foo='bar', bar='baz', num=123, fnum=123.456))

If the above script is run, it prints:

   message 1 >>> {"fnum": 123.456, "num": 123, "bar": "baz", "foo": "bar"}

要素の順序は Python のバージョンによって異なることに注意してください。

より特殊な処理が必要な場合、次の例のように、カスタムの JSON エンコーダ
を作ることができます:

   from __future__ import unicode_literals

   import json
   import logging

   # This next bit is to ensure the script runs unchanged on 2.x and 3.x
   try:
       unicode
   except NameError:
       unicode = str

   class Encoder(json.JSONEncoder):
       def default(self, o):
           if isinstance(o, set):
               return tuple(o)
           elif isinstance(o, unicode):
               return o.encode('unicode_escape').decode('ascii')
           return super(Encoder, self).default(o)

   class StructuredMessage(object):
       def __init__(self, message, **kwargs):
           self.message = message
           self.kwargs = kwargs

       def __str__(self):
           s = Encoder().encode(self.kwargs)
           return '%s >>> %s' % (self.message, s)

   _ = StructuredMessage   # optional, to improve readability

   def main():
       logging.basicConfig(level=logging.INFO, format='%(message)s')
       logging.info(_('message 1', set_value={1, 2, 3}, snowman='\u2603'))

   if __name__ == '__main__':
       main()

When the above script is run, it prints:

   message 1 >>> {"snowman": "\u2603", "set_value": [1, 2, 3]}

要素の順序は Python のバージョンによって異なることに注意してください。


handler を "dictConfig()" を使ってカスタマイズする
==================================================

logging handler に特定のカスタマイズを何度もしたい場合で、
"dictConfig()" を使っているなら、サブクラスを作らなくてもカスタマイズ
が可能です。例えば、ログファイルの owner を設定したいとします。これは
POSIX 環境では "shutil.chown()" を使って簡単に実現できますが、標準ライ
ブラリの file handler はこの機能を組み込みでサポートしていません。
handler の生成を通常の関数を使ってカスタマイズすることができます:

   def owned_file_handler(filename, mode='a', encoding=None, owner=None):
       if owner:
           if not os.path.exists(filename):
               open(filename, 'a').close()
           shutil.chown(filename, *owner)
       return logging.FileHandler(filename, mode, encoding)

そして、 "dictConfig()" に渡される構成設定の中で、この関数を使って
logging handler を生成するように指定することができます:

   LOGGING = {
       'version': 1,
       'disable_existing_loggers': False,
       'formatters': {
           'default': {
               'format': '%(asctime)s %(levelname)s %(name)s %(message)s'
           },
       },
       'handlers': {
           'file':{
               # The values below are popped from this dictionary and
               # used to create the handler, set the handler's level and
               # its formatter.
               '()': owned_file_handler,
               'level':'DEBUG',
               'formatter': 'default',
               # The values below are passed to the handler creator callable
               # as keyword arguments.
               'owner': ['pulse', 'pulse'],
               'filename': 'chowntest.log',
               'mode': 'w',
               'encoding': 'utf-8',
           },
       },
       'root': {
           'handlers': ['file'],
           'level': 'DEBUG',
       },
   }

この例は説明用のものですが、owner の user と group を "pulse" に設定し
ています。これを動くスクリプトに "chowntest.py" に組み込んでみます:

   import logging, logging.config, os, shutil

   def owned_file_handler(filename, mode='a', encoding=None, owner=None):
       if owner:
           if not os.path.exists(filename):
               open(filename, 'a').close()
           shutil.chown(filename, *owner)
       return logging.FileHandler(filename, mode, encoding)

   LOGGING = {
       'version': 1,
       'disable_existing_loggers': False,
       'formatters': {
           'default': {
               'format': '%(asctime)s %(levelname)s %(name)s %(message)s'
           },
       },
       'handlers': {
           'file':{
               # The values below are popped from this dictionary and
               # used to create the handler, set the handler's level and
               # its formatter.
               '()': owned_file_handler,
               'level':'DEBUG',
               'formatter': 'default',
               # The values below are passed to the handler creator callable
               # as keyword arguments.
               'owner': ['pulse', 'pulse'],
               'filename': 'chowntest.log',
               'mode': 'w',
               'encoding': 'utf-8',
           },
       },
       'root': {
           'handlers': ['file'],
           'level': 'DEBUG',
       },
   }

   logging.config.dictConfig(LOGGING)
   logger = logging.getLogger('mylogger')
   logger.debug('A debug message')

これを実行するには、 "root" 権限で実行する必要があるかもしれません:

   $ sudo python3.3 chowntest.py
   $ cat chowntest.log
   2013-11-05 09:34:51,128 DEBUG mylogger A debug message
   $ ls -l chowntest.log
   -rw-r--r-- 1 pulse pulse 55 2013-11-05 09:34 chowntest.log

"shutil.chown()" が追加されたのが Python 3.3 からなので、この例は
Python 3.3 を使っています。このアプローチ自体は "dictConfig()" をサポ
ートした全ての Python バージョン - Python 2.7, 3.2 以降 - で利用できま
す。 3.3 以前のバージョンでは、オーナーを変更するのに "os.chown()" を
利用する必要があるでしょう。

実際には、handler を生成する関数はプロジェクト内のどこかにあるユーティ
リティモジュールに置くことになるでしょう。設定の中で直接関数を参照する
代わりに:

   '()': owned_file_handler,

次のように書くこともできます:

   '()': 'ext://project.util.owned_file_handler',

"project.util" は関数がある実際の場所に置き換えてください。上のスクリ
プトでは "'ext://__main__.owned_file_handler'" で動くはずです。
"dictConfig()" は "ext://" から実際の callable を見つけます。

この例は他のファイルに対する変更を実装する例にもなっています。例えば
"os.chmod()" を使って、同じ方法で POSIX パーミッションを設定できるでし
ょう。

もちろん、このアプローチは "FileHandler" 以外の handler 、ローテートす
る file handler のいずれかやその他の handler にも適用できます。


固有の書式化スタイルをアプリケーション全体で使う
================================================

Python 3.2 では、"Formatter" クラスが "style" という名前のオプションの
キーワード引数を受け取ります。このデフォルト値は後方互換性を維持するた
めに "%" となっていますが、 "{" か "$"  を指定することで、
"str.format()" か "string.Template" でサポートされているのと同じ書式化
のアプローチを採れます。これは最終的に出力されるログメッセージの書式化
に影響を与えますが、個々のログメッセージが構築される方法とは完全に直交
していることに注意してください。

logging の呼び出し ("debug()", "info()"  など) は、ログメッセージのた
めに位置引数しか受け取らず、キーワード引数はそれを処理するときのオプシ
ョンを指定するためだけに使われます。 (例えば、 "exc_info" キーワード引
数を使ってログを取るトレースバック情報を指定したり、 "extra" キーワー
ド引数を使ってログに付与する追加のコンテキスト情報を指定します。
)logging パッケージは内部で % を使って format 文字列と引数をマージして
いるので、 "str.format()" や "string.Template" を使って logging を呼び
出す事はできません。既存の logging 呼び出しは %-format を使っているの
で、後方互換性のためにこの部分を変更することはできません。

特定のロガーに関連付ける書式スタイルへの提案がなされてきましたが、その
アプローチは同時に後方互換性の問題にぶち当たります。あらゆる既存のコー
ドはロガーの名前を使っているでしょうし、 % 形式書式化を使っているでし
ょう。

あらゆるサードパーティのライブラリ、あらゆるあなたのコードの間で相互運
用可能なようにロギングを行うには、書式化についての決定は、個々のログ呼
び出しのレベルで行う必要があります。これは受け容れ可能な代替書式化スタ
イルに様々な手段の可能性を広げます。


LogRecord ファクトリを使う
--------------------------

Python 3.2 において、上述した "Formatter" の変更とともに、
"setLogRecordFactory()" 関数を使って "LogRecord" のサブクラスをユーザ
に指定することを可能にするロギングパッケージの機能拡張がありました。こ
れにより、 "getMessage()" をオーバライドして た　だ　し　い　ことをす
る、あなた自身の手による "LogRecord" のサブクラスをセットすることが出
来ます。このメソッドの実装は基底クラスでは "msg % args" 書式化をし、あ
なたの代替の書式化の置換が出来る場所ですが、他のコードとの相互運用性を
保障するために、全ての書式化スタイルをサポートするよう注意深く行うべき
であり、また、%-書式化をデフォルトで認めるべきです。基底クラスの実装が
そうしているように、 "str(self.msg)" 呼び出しもしてください。

さらに詳しい情報は、リファレンスの "setLogRecordFactory()",
"LogRecord" を参照してください。


カスタムなメッセージオブジェクトを使う
--------------------------------------

あなた独自のログメッセージを構築するのに {}- および $- 書式化を使える
ようにするための、もうひとつの、おそらくもっと簡単な方法があります。ロ
ギングの際には、あなたはメッセージ書式文字列として、任意のオブジェクト
を使えることを(任意のオブジェクトをメッセージに使用する より)思い出し
てみましょう、そしてロギングパッケージはそのオブジェクトに対して実際の
書式文字列を得るために "str()" を呼び出すことも。以下 2 つのクラスを検
討してみましょう:

   class BraceMessage(object):
       def __init__(self, fmt, *args, **kwargs):
           self.fmt = fmt
           self.args = args
           self.kwargs = kwargs

       def __str__(self):
           return self.fmt.format(*self.args, **self.kwargs)

   class DollarMessage(object):
       def __init__(self, fmt, **kwargs):
           self.fmt = fmt
           self.kwargs = kwargs

       def __str__(self):
           from string import Template
           return Template(self.fmt).substitute(**self.kwargs)

どちらのクラスも format 文字列の代わりに利用して、 {} や $ を使って実
際のログの “%(message)s”, “{message}”, “$message” で指定された
"message" 部分を生成することができます。これは何かログを取りたいときに
常に使うには使いにくいクラス名ですが、使いやすいようにエイリアスを作れ
ば良いでしょう、 "M" であるとか "_" のような(あるいは地域化のために既
に "_" を使っているのであれば "__" が良いかもしれません)。

このアプローチによる例をお見せします。最初は "str.format()" を使ってフ
ォーマットする例です:

   >>> __ = BraceMessage
   >>> print(__('Message with {0} {1}', 2, 'placeholders'))
   Message with 2 placeholders
   >>> class Point: pass
   ...
   >>> p = Point()
   >>> p.x = 0.5
   >>> p.y = 0.5
   >>> print(__('Message with coordinates: ({point.x:.2f}, {point.y:.2f})', point=p))
   Message with coordinates: (0.50, 0.50)

2つめは "string.Template" でフォーマットする例です:

   >>> __ = DollarMessage
   >>> print(__('Message with $num $what', num=2, what='placeholders'))
   Message with 2 placeholders
   >>>

ひとつ注目すべきは、この方法には大きなパフォーマンス上のペナルティはな
いことです。実際のフォーマット操作は logging の呼び出し時ではなくて、
メッセージが実際に(そして必要な場合のみ) handler によって出力されると
きに起こります。ですので、この方法での唯一の些細な注意点は、追加の括弧
がフォーマット文字列だけではなく引数も囲わないといけないこと、だけです
。__ は上でお見せした通り "XXXMessage" クラスのコンストラクタ呼び出し
のシンタックスシュガーに過ぎません。


filter を "dictConfig()" を使ってカスタマイズする
=================================================

"dictConfig()" によってフィルタを設定 *出来ます* が、どうやってそれを
行うのかが初見では明快とは言えないでしょう(そのためのこのレシピです)。
"Filter" のみが唯一標準ライブラリに含まれているだけですし、それは何の
要求にも応えてはくれません(ただの基底クラスですから)ので、典型的には
"filter()" メソッドをオーバライドした "Filter" のサブクラスをあなた自
身で定義する必要があります。これをするには、設定辞書内のフィルタ指定部
分に、 "()" キーでそのフィルタを作るのに使われる callable を指定してく
ださい(クラスを指定するのが最もわかりやすいですが、 "Filter" インスタ
ンスを返却する callable を提供することでも出来ます)。以下に完全な例を
示します:

   import logging
   import logging.config
   import sys

   class MyFilter(logging.Filter):
       def __init__(self, param=None):
           self.param = param

       def filter(self, record):
           if self.param is None:
               allow = True
           else:
               allow = self.param not in record.msg
           if allow:
               record.msg = 'changed: ' + record.msg
           return allow

   LOGGING = {
       'version': 1,
       'filters': {
           'myfilter': {
               '()': MyFilter,
               'param': 'noshow',
           }
       },
       'handlers': {
           'console': {
               'class': 'logging.StreamHandler',
               'filters': ['myfilter']
           }
       },
       'root': {
           'level': 'DEBUG',
           'handlers': ['console']
       },
   }

   if __name__ == '__main__':
       logging.config.dictConfig(LOGGING)
       logging.debug('hello')
       logging.debug('hello - noshow')

This example shows how you can pass configuration data to the callable
which constructs the instance, in the form of keyword parameters. When
run, the above script will print:

   changed: hello

設定した通りに動いていますね。

ほかにもいくつか特筆すべき点があります:

* 設定内で直接その callable を参照出来ない場合(例えばそれが異なるモジ
  ュール内にあり、設定辞書のある場所からそれを直接インポート出来ない、
  など)には、 外部オブジェクトへのアクセス に記述されている
  "ext://..." 形式を使えます。例えば、上記例のように "MyFilter" と指定
  する代わりに、 "'ext://__main__.MyFilter'" と記述することが出来ます
  。

* フィルタについてとともに、このテクニックは、カスタムハンドラ、カスタ
  ムフォーマッタに対しても同様に使えます。ロギングが設定において、どの
  ようにユーザ定義のオブジェクトをサポートするのかについてのさらなる詳
  細については、 ユーザ定義オブジェクト と、本クックブックの上の方のレ
  シピ handler を dictConfig() を使ってカスタマイズする を参照してくだ
  さい。


例外の書式化をカスタマイズする
==============================

例外の書式化をカスタマイズしたいことがあるでしょう - わかりやすさのた
めに、例外情報がある場合でもログイベントごとに一行に収まることを死守し
たいと望むとしましょう。フォーマッタのクラスをカスタマイズして、このよ
うに出来ます:

   import logging

   class OneLineExceptionFormatter(logging.Formatter):
       def formatException(self, exc_info):
           """
           Format an exception so that it prints on a single line.
           """
           result = super(OneLineExceptionFormatter, self).formatException(exc_info)
           return repr(result)  # or format into one line however you want to

       def format(self, record):
           s = super(OneLineExceptionFormatter, self).format(record)
           if record.exc_text:
               s = s.replace('\n', '') + '|'
           return s

   def configure_logging():
       fh = logging.FileHandler('output.txt', 'w')
       f = OneLineExceptionFormatter('%(asctime)s|%(levelname)s|%(message)s|',
                                     '%d/%m/%Y %H:%M:%S')
       fh.setFormatter(f)
       root = logging.getLogger()
       root.setLevel(logging.DEBUG)
       root.addHandler(fh)

   def main():
       configure_logging()
       logging.info('Sample message')
       try:
           x = 1 / 0
       except ZeroDivisionError as e:
           logging.exception('ZeroDivisionError: %s', e)

   if __name__ == '__main__':
       main()

When run, this produces a file with exactly two lines:

   28/01/2015 07:21:23|INFO|Sample message|
   28/01/2015 07:21:23|ERROR|ZeroDivisionError: integer division or modulo by zero|'Traceback (most recent call last):\n  File "logtest7.py", line 30, in main\n    x = 1 / 0\nZeroDivisionError: integer division or modulo by zero'|

これは扱いとしては単純過ぎますが、例外情報をどのようにしてあなた好みの
書式化出来るかを示しています。さらに特殊なニーズが必要な場合には
"traceback" モジュールが有用です。


ロギングメッセージを喋る
========================

ロギングメッセージを目で見る形式ではなく音で聴く形式として出力したい、
という状況があるかもしれません。これはあなたのシステムで text- to-
speech (TTS) 機能が利用可能であれば、容易です。それが Python バインデ
ィングを持っていなくとも、です。ほとんどの TTS システムはあなたが実行
出来るコマンドラインプログラムを持っていて、このことで、 "subprocess"
を使うことでハンドラが呼び出せます。ここでは、TTS コマンドラインプログ
ラムはユーザとの対話を期待せず、完了には時間がかかり、そしてログメッセ
ージの頻度はユーザをメッセージで圧倒してしまうほどには高くはなく、そし
て並列で喋るよりはメッセージ一つにつき一回喋ることが受け容れられる、と
しておきます。ここでお見せする実装例では、次が処理される前に一つのメッ
セージを喋り終わるまで待ち、結果としてほかのハンドラを待たせることにな
ります。 "espeak" TTS パッケージが手許にあるとして、このアプローチによ
る短い例はこのようなものです:

   import logging
   import subprocess
   import sys

   class TTSHandler(logging.Handler):
       def emit(self, record):
           msg = self.format(record)
           # Speak slowly in a female English voice
           cmd = ['espeak', '-s150', '-ven+f3', msg]
           p = subprocess.Popen(cmd, stdout=subprocess.PIPE,
                                stderr=subprocess.STDOUT)
           # wait for the program to finish
           p.communicate()

   def configure_logging():
       h = TTSHandler()
       root = logging.getLogger()
       root.addHandler(h)
       # the default formatter just returns the message
       root.setLevel(logging.DEBUG)

   def main():
       logging.info('Hello')
       logging.debug('Goodbye')

   if __name__ == '__main__':
       configure_logging()
       sys.exit(main())

実行すれば、女性の声で "Hello" に続き "Goodbye" と喋るはずです。

このアプローチは、もちろんほかの TTS システムにも採用出来ますし、メッ
セージをコマンドライン経由で外部プログラムに渡せるようなものであれば、
ほかのシステムであっても全く同じです。


ロギングメッセージをバッファリングし、条件に従って出力する
==========================================================

メッセージを一次領域に記録し、ある種の特定の状況になった場合にだけ出力
したい、ということがあるかもしれません。たとえばある関数内でのデバッグ
のためのログ出力をしたくても、エラーなしで終了する限りにおいては収集さ
れたデバッグ情報による混雑は喰らいたくはなく、エラーがあった場合にだけ
エラー出力とともにデバッグ情報を見たいのだ、のようなことがあるでしょう
。

このような振る舞いをするロギングをしたい関数に対して、デコレータを用い
てこれを行う例をお見せします。それには
"logging.handlers.MemoryHandler" を使います。これにより何か条件を満た
すまでロギングイベントを溜め込むことが出来、条件を満たせば溜め込まれた
イベントが "flushed" として他のハンドラ ("target" のハンドラ)に渡され
ます。デフォルトでは、 "MemoryHandler" はそのバッファが一杯になるか、
指定された閾値のレベル以上のイベントが起こるとフラッシュされます。何か
特別なフラッシュの振る舞いをしたければ、このレシピはさらに特殊化した
"MemoryHandler" とともに利用出来ます。

スクリプト例では、 "foo" という、単に全てのログレベルについて、
"sys.stderr" にもどのレベルを出力したのかについて書き出しながら実際の
ログ出力も行う、という単純な関数を使っています。 "foo" に真を与えると
ERROR と CRITICAL の出力をし、そうでなければ DEBUG, INFO, WARNING だけ
を出力します。

スクリプトが行うことは単に、 "foo" を必要とされている特定の条件でのロ
ギングを行うようにするデコレータで修飾することだけです。このデコレータ
はパラメータとしてロガーを取り、修飾された関数が呼ばれている間だけメモ
リハンドラをアタッチします。追加のパラメータとして、ターゲットのハンド
ラ、フラッシュが発生すべきレベル、バッファの容量も受け取れます。これら
のデフォルトは順に "sys.stderr" へ書き出す "StreamHandler",
"logging.ERROR", "100" です。

スクリプトはこれです:

   import logging
   from logging.handlers import MemoryHandler
   import sys

   logger = logging.getLogger(__name__)
   logger.addHandler(logging.NullHandler())

   def log_if_errors(logger, target_handler=None, flush_level=None, capacity=None):
       if target_handler is None:
           target_handler = logging.StreamHandler()
       if flush_level is None:
           flush_level = logging.ERROR
       if capacity is None:
           capacity = 100
       handler = MemoryHandler(capacity, flushLevel=flush_level, target=target_handler)

       def decorator(fn):
           def wrapper(*args, **kwargs):
               logger.addHandler(handler)
               try:
                   return fn(*args, **kwargs)
               except Exception:
                   logger.exception('call failed')
                   raise
               finally:
                   super(MemoryHandler, handler).flush()
                   logger.removeHandler(handler)
           return wrapper

       return decorator

   def write_line(s):
       sys.stderr.write('%s\n' % s)

   def foo(fail=False):
       write_line('about to log at DEBUG ...')
       logger.debug('Actually logged at DEBUG')
       write_line('about to log at INFO ...')
       logger.info('Actually logged at INFO')
       write_line('about to log at WARNING ...')
       logger.warning('Actually logged at WARNING')
       if fail:
           write_line('about to log at ERROR ...')
           logger.error('Actually logged at ERROR')
           write_line('about to log at CRITICAL ...')
           logger.critical('Actually logged at CRITICAL')
       return fail

   decorated_foo = log_if_errors(logger)(foo)

   if __name__ == '__main__':
       logger.setLevel(logging.DEBUG)
       write_line('Calling undecorated foo with False')
       assert not foo(False)
       write_line('Calling undecorated foo with True')
       assert foo(True)
       write_line('Calling decorated foo with False')
       assert not decorated_foo(False)
       write_line('Calling decorated foo with True')
       assert decorated_foo(True)

When this script is run, the following output should be observed:

   Calling undecorated foo with False
   about to log at DEBUG ...
   about to log at INFO ...
   about to log at WARNING ...
   Calling undecorated foo with True
   about to log at DEBUG ...
   about to log at INFO ...
   about to log at WARNING ...
   about to log at ERROR ...
   about to log at CRITICAL ...
   Calling decorated foo with False
   about to log at DEBUG ...
   about to log at INFO ...
   about to log at WARNING ...
   Calling decorated foo with True
   about to log at DEBUG ...
   about to log at INFO ...
   about to log at WARNING ...
   about to log at ERROR ...
   Actually logged at DEBUG
   Actually logged at INFO
   Actually logged at WARNING
   Actually logged at ERROR
   about to log at CRITICAL ...
   Actually logged at CRITICAL

見ての通り、実際のログ出力は重要度 ERROR かそれより大きい場合にのみ行
っていますが、この場合はそれよりも重要度の低い ERROR よりも前に発生し
たイベントも出力されます。

当然のことですが、デコレーションはいつものやり方でどうぞ:

   @log_if_errors(logger)
   def foo(fail=False):
       ...


設定によって時刻を UTC(GMT) で書式化する
========================================

場合によっては、時刻として UTC を使いたいと思うかもしれません。これに
は以下に示すような *UTCFormatter* のようなクラスを使って出来ます:

   import logging
   import time

   class UTCFormatter(logging.Formatter):
       converter = time.gmtime

そしてコード中で "UTCFormatter" を "Formatter" の代わりに使えます。こ
れを設定を通して行いたい場合、 "dictConfig()" API を以下の完全な例で示
すようなアプローチで使うことが出来ます:

   import logging
   import logging.config
   import time

   class UTCFormatter(logging.Formatter):
       converter = time.gmtime

   LOGGING = {
       'version': 1,
       'disable_existing_loggers': False,
       'formatters': {
           'utc': {
               '()': UTCFormatter,
               'format': '%(asctime)s %(message)s',
           },
           'local': {
               'format': '%(asctime)s %(message)s',
           }
       },
       'handlers': {
           'console1': {
               'class': 'logging.StreamHandler',
               'formatter': 'utc',
           },
           'console2': {
               'class': 'logging.StreamHandler',
               'formatter': 'local',
           },
       },
       'root': {
           'handlers': ['console1', 'console2'],
      }
   }

   if __name__ == '__main__':
       logging.config.dictConfig(LOGGING)
       logging.warning('The local time is %s', time.asctime())

When this script is run, it should print something like:

   2015-10-17 12:53:29,501 The local time is Sat Oct 17 13:53:29 2015
   2015-10-17 13:53:29,501 The local time is Sat Oct 17 13:53:29 2015

時刻をローカル時刻と UTC の両方に書式化するのに、それぞれのハンドラに
それぞれフォーマッタを与えています。


ロギングの選択にコンテキストマネージャを使う
============================================

一時的にロギングの設定を変えて、作業をした後に設定を戻せると便利なとき
があります。 こういうときの、ロギングコンテキストの保存と復元をする方
法ではコンテキストマネージャを使うのが一番です。 以下にあるのがそのた
めのコンテキストマネージャの簡単な例で、これを使うと、任意にロギングレ
ベルを変更し、コンテキストマネージャのスコープ内で他に影響を及ぼさずロ
ギングハンドラを追加できるようになります:

   import logging
   import sys

   class LoggingContext(object):
       def __init__(self, logger, level=None, handler=None, close=True):
           self.logger = logger
           self.level = level
           self.handler = handler
           self.close = close

       def __enter__(self):
           if self.level is not None:
               self.old_level = self.logger.level
               self.logger.setLevel(self.level)
           if self.handler:
               self.logger.addHandler(self.handler)

       def __exit__(self, et, ev, tb):
           if self.level is not None:
               self.logger.setLevel(self.old_level)
           if self.handler:
               self.logger.removeHandler(self.handler)
           if self.handler and self.close:
               self.handler.close()
           # implicit return of None => don't swallow exceptions

レベル値を指定した場合、コンテキストマネージャがカバーする with ブロッ
クのスコープ内でロガーのレベルがその値に設定されます。 ハンドラーを指
定した場合、ブロックに入るときにロガーに追加され、ブロックから抜けると
きに取り除かれます。 ブロックを抜けるときに、自分で追加したハンドラを
クローズするようコンテキストマネージャに指示することもできます - その
ハンドラがそれ以降必要無いのであればクローズしてしまって構いません。

どのように動作するのかを示すためには、次のコード群を上のコードに付け加
えるとよいです:

   if __name__ == '__main__':
       logger = logging.getLogger('foo')
       logger.addHandler(logging.StreamHandler())
       logger.setLevel(logging.INFO)
       logger.info('1. This should appear just once on stderr.')
       logger.debug('2. This should not appear.')
       with LoggingContext(logger, level=logging.DEBUG):
           logger.debug('3. This should appear once on stderr.')
       logger.debug('4. This should not appear.')
       h = logging.StreamHandler(sys.stdout)
       with LoggingContext(logger, level=logging.DEBUG, handler=h, close=True):
           logger.debug('5. This should appear twice - once on stderr and once on stdout.')
       logger.info('6. This should appear just once on stderr.')
       logger.debug('7. This should not appear.')

最初はロガーのレベルを "INFO" に設定しているので、メッセージ #1 は現れ
、メッセージ #2 は現れません。 次に、その後の "with" ブロック内で一時
的にレベルを "DEBUG" に変更したため、メッセージ #3 が現れます。 そのブ
ロックを抜けた後、ロガーのレベルは "INFO" に復元され、メッセージ #4 は
現れません。 次の "with" ブロック内では、再度レベルを "DEBUG" に設定し
、 "sys.stdout" に書き出すハンドラを追加します。 そのおかげでメッセー
ジ #5 が 2 回 (1回は "stderr" を通して、もう1回は "stdout" を通して)
コンソールに出力されます。 "with" 文が完了すると、前の状態になるので (
メッセージ #1 のように) メッセージ #6 が現れ、(まさにメッセージ #2 の
ように) メッセージ #7 は現れません。

出来上がったスクリプトを実行すると、結果は次のようになります:

   $ python logctx.py
   1. This should appear just once on stderr.
   3. This should appear once on stderr.
   5. This should appear twice - once on stderr and once on stdout.
   5. This should appear twice - once on stderr and once on stdout.
   6. This should appear just once on stderr.

"stderr" を "/dev/null" へパイプした状態でもう一度実行すると、次のよう
になり、これは "stdout" の方に書かれたメッセージだけが現れています:

   $ python logctx.py 2>/dev/null
   5. This should appear twice - once on stderr and once on stdout.

"stdout" を "/dev/null" へパイプした状態でさらにもう一度実行すると、こ
うなります:

   $ python logctx.py >/dev/null
   1. This should appear just once on stderr.
   3. This should appear once on stderr.
   5. This should appear twice - once on stderr and once on stdout.
   6. This should appear just once on stderr.

この場合では、 "stdout" の方に出力されたメッセージ #5 は予想通り現れま
せん。

もちろんここで説明した手法は、例えば一時的にロギングフィルターを取り付
けたりするのに一般化できます。 上のコードは Python 2 だけでなく Python
3 でも動くことに注意してください。
