Python プログラマは、素早く便利なデバッグツールとして、コード内で print() をよく使います。ロギングフレームワークを使用するのはわずかな手間がかかるだけですが、それよりはるかにエレガントで柔軟です。デバッギングに便利であることに加えて、ロギングは、アプリケーションの状態と健全性に対して、よりよく構造化されたより多くの情報も提供してくれます。
Django は、システムのロギングを実行するために、Python 組み込みの logging モジュールを使用・拡張しています。このモジュールは、Python 自体のドキュメントで詳細に解説されています。このセクションでは、簡単な概要を説明します。
Pythonのロギングは4つの部分で構成されます。
\n\nロガー は、ロギングシステムのエントリーポイントです。各ロガーは処理が記述されたメッセージの名前付けされたバケットです。
\nロガーには ログレベル が設定されています。このログレベルはハンドリングされたログメッセージの深刻さを表しています。Pythonは下記のログレベルを定義しています。
\nDEBUG: デバッグのための低レベルシステム情報
INFO: 一般的なシステム情報
WARNING: 重要度の小さい問題が発生したことを示す情報
ERROR: 大きな問題が発生したことを示す情報
CRITICAL: 重大な問題が発生したことを示す情報
ロガーに記載された各メッセージは ログレコード です。各ログレコードは、特定のメッセージの重要性を表す ログレベル を持ちます。ログレコードには、記録されたイベントを説明するメタデータを含むことができます。これには、スタックトレースやエラーコードと言った詳細を含めることができます。
\nロガーにメッセージが渡されたとき、メッセージのログレベルはロガーのログレベルと比較されます。メッセージのログレベルがロガー自体のログレベルと同等以上の場合、メッセージは次の処理に進みます。それ以外の場合、メッセージは無視されます。
\nロガーによってメッセージの処理が必要だと判断された場合、メッセージは ハンドラ に渡されます。
\nハンドラ は、ロガー上で書くメッセージに何をするかを決定するための原動力です。ここで、メッセージを表示する、ファイルに書き込む、ネットワークソケットに送信する、といった特定のロギング動作を記述します。
\nロガーと同様に、ハンドラもログレベルを持ちます。ログレコードのログレベルがハンドラのレベルに満たない場合、ハンドラはメッセージを無視します。
\nロガーには複数のハンドラを設定でき、また各ハンドラは異なるログレベルを持つことができます。この方法により、メッセージの重要性に応じて通知方法を変えることができます。たとえば、ERROR と CRITICAL メッセージを呼び出しサービスに転送するハンドラを設定する一方で、後で分析するために (ERROR や CRITICAL も含む) すべてのメッセージをファイルに記録する 2 つめのハンドラを設定できます。
フィルタ は、どのログレコードがロガーからハンドラへ渡されるかについて、追加的なコントロールを提供します。
\nデフォルトでは、ログレベル要件を満たしたすべてのログメッセージが処理されます。しかし、フィルタを使用することで、ロギングのプロセスに追加的な要件を設定できます。たとえば、特定のソースからの ERROR のみを処理するようにフィルタを設定することができます。
フィルタは、処理前にログレコードを修正するためにも使えます。たとえば、特定の条件を満たした場合に ERROR ログレコードを WARNING レコードに格下げさせるようなフィルタを設定できます。
フィルタは、ロガーもしくはハンドラに対して設定できます; 複数のフィルタを使って複数のフィルタ動作を連鎖させることも可能です。
\n最終的には、ログレコードはテキストとして表現される必要があります。 フォーマッタ はこのテキストの書式を定義します。フォーマッタは、通常は Python の文字列フォーマットで、LogRecord 属性 を含みます; しかし、特定の書式設定を行うような独自のフォーマッタを記述することもできます。
\nロギングシステムは潜在的にセンシティブな情報を取り扱うことになります。たとえば、ログレコードにはウェブリクエストやスタックトレースに関する情報が含まれることがありますが、ロガーで収集されたデータの一部にはセキュリティへの影響もあるかもしれません。あなたは次のことを理解しておく必要があります。
\nどの情報を収集するか
最終的にその情報はどこに保存されることになるか
その情報の転送はどのように行われるか
その情報にアクセスする可能性があるのは誰か
センシティブな情報の収集をコントロールするために、特定のセンシティブな情報をエラーレポートからフィルタリングするように明示的に指定できます。その方法については エラーレポートをフィルタリングする を参照してください。
\nAdminEmailHandlerLink to this heading#組み込みの AdminEmailHandler はセキュリティの文脈で言及に値します。もし include_html オプションが有効なら、送信するメールには、スタックの各レベルのローカル変数の名前と値、そして Django の設定値（言い換えれば、 DEBUG が True のときに Web ページで公開されるのと同じレベルの詳細）が完全なトレースバックとして含まれます。
通常、このような潜在的にセンシティブな情報を電子メールで送信するのは良くないとされています。その代わりに、詳細なログを送信できる多くのサードパーティ・サービスを利用することで、完全なトレースバックによる豊富な情報、通知先や情報へのアクセス権の明確な管理など、複数の利点が得られます。
\nPython のロギングライブラリは、実用的なインターフェースから設定ファイルまで、ロギング設定のテクニックを提供しています。デフォルトでは、Django は dictConfig フォーマット を使用します。
\nロギングを設定するためには、LOGGING を使用してロギング設定の辞書を定義します。この設定には、ロギングセットアップで使いたいロガー、ハンドラ、フィルタ、フォーマッタを記述し、それらのコンポーネントで使用したいログレベルとその他のプロパティを記述します。
デフォルトでは、LOGGING 設定は、以下のスキームを使って Django のデフォルトロギング設定 に統合されています。
LOGGING の disable_existing_loggers キーの値を True にすると、全てのデフォルトの設定が無効になります（キーが存在しない場合は dictConfig のデフォルトになります）。このため、 'disable_existing_loggers': True を使う場合は注意してください。 True を設定する必要は殆どないでしょう。 disable_existing_loggers を False に設定して、デフォルトのロガーの一部、または全てを定義しなおすこともできます。あるいは、 LOGGING_CONFIG を None に設定して、 ロギングの設定を自分で行うこと も出来ます。
ロギングは、一般的な Django の setup() 関数の一部として設定されます。したがって、ロガーが常にプロジェクトコード内で使用準備ができていることが保証されています。
dictConfig フォーマット に関する完全なドキュメントが、ロギング設定ディクショナリの最高の教材です。とはいえ、どんなことが可能なのか知ってもらうため、以下にいくつかの例を示します。
\n最初に、全てのログメッセージをコンソールに出力するための最低限の設定がこちらです。
\nsettings.pyimport os\n\nLOGGING = {\n "version": 1,\n "disable_existing_loggers": False,\n "handlers": {\n "console": {\n "class": "logging.StreamHandler",\n },\n },\n "root": {\n "handlers": ["console"],\n "level": "WARNING",\n },\n}\nこの設定では、 root という名前の親のロガーがあり、 WARNING レベル以上のメッセージを受け取ったら、 console ハンドラに送るようになっています。 level を INFO または DEBUG にすると、より詳細なメッセージも表示されるようになります。この設定は開発中に役に立ちます。
次に、より詳細なロギングを追加します。次の例は、ロギングシステムが django という名前のロガーからより多くのメッセージを出力するようにする方法を示しています。
\nsettings.pyimport os\n\nLOGGING = {\n "version": 1,\n "disable_existing_loggers": False,\n "handlers": {\n "console": {\n "class": "logging.StreamHandler",\n },\n },\n "root": {\n "handlers": ["console"],\n "level": "WARNING",\n },\n "loggers": {\n "django": {\n "handlers": ["console"],\n "level": os.getenv("DJANGO_LOG_LEVEL", "INFO"),\n "propagate": False,\n },\n },\n}\nデフォルトでは、この設定は、INFO 以上のメッセージを django ロガーからコンソールに送信します。このレベルは、デフォルト設定ではログレコードを表示するのが DEBUG=True のときだけであること以外、Django のデフォルトのロギング設定と同じです。Django はそのような INFO レベルのログはそこまで多くログ出力しません。しかし、この設定では、環境変数 DJANGO_LOG_LEVEL=DEBUG を設定することで、Django のすべての debug ログを表示できます。これにはすべてのデータベースクエリが含まれるため、非常に冗長です。
必ずしもコンソールに出力する必要はありません。django という名前のロガーをファイルに書き込むには、次のように設定します。
\nsettings.pyLOGGING = {\n "version": 1,\n "disable_existing_loggers": False,\n "handlers": {\n "file": {\n "level": "DEBUG",\n "class": "logging.FileHandler",\n "filename": "/path/to/django/debug.log",\n },\n },\n "loggers": {\n "django": {\n "handlers": ["file"],\n "level": "DEBUG",\n "propagate": True,\n },\n },\n}\nこの例を使用するときは、'filename' のパスを Django アプリケーションを実行しているユーザーが書き込み可能な場所に変更してください。
最後に、かなり複雑なロギングの設定の例です。
\nsettings.pyLOGGING = {\n "version": 1,\n "disable_existing_loggers": False,\n "formatters": {\n "verbose": {\n "format": "{levelname} {asctime} {module} {process:d} {thread:d} {message}",\n "style": "{",\n },\n "simple": {\n "format": "{levelname} {message}",\n "style": "{",\n },\n },\n "filters": {\n "special": {\n "()": "project.logging.SpecialFilter",\n "foo": "bar",\n },\n "require_debug_true": {\n "()": "django.utils.log.RequireDebugTrue",\n },\n },\n "handlers": {\n "console": {\n "level": "INFO",\n "filters": ["require_debug_true"],\n "class": "logging.StreamHandler",\n "formatter": "simple",\n },\n "mail_admins": {\n "level": "ERROR",\n "class": "django.utils.log.AdminEmailHandler",\n "filters": ["special"],\n },\n },\n "loggers": {\n "django": {\n "handlers": ["console"],\n "propagate": True,\n },\n "django.request": {\n "handlers": ["mail_admins"],\n "level": "ERROR",\n "propagate": False,\n },\n "myproject.custom": {\n "handlers": ["console", "mail_admins"],\n "level": "INFO",\n "filters": ["special"],\n },\n },\n}\nこのロギング設定は、以下のことを行います:
\n設定が「dictConfig バージョン 1」形式であることを明示します。 現在、これが唯一の dictConfig 形式のバージョンです。
2 つのフォーマッタを定義します:
\nsimple は、ログレベル名 (例: DEBUG) とログメッセージを出力します。
この format 文字列は標準の Python 文字列フォーマットで、各ログ行で出力される詳細を定義します。出力可能な詳細の全リストは Formatter Objects で確認できます。
verbose は、ログレベルの名称とログメッセージに加えて、時刻、プロセス、スレッド、ログメッセージを生成したモジュールを出力します。
2 つのフィルタを定義します:
\nproject.logging.SpecialFilter は、エイリアス special を使っています。もしこのフィルタが追加の引数を必要とする場合、フィルタ設定の辞書に追加のキーとして提供できます。今回の場合、SpecialFilter をインスタンス化するときに、引数 foo に bar の値が与えられます。
django.utils.log.RequireDebugTrue は、DEBUG が True のときにレコードの処理を進めます。
2 つのハンドラを定義します:
\nconsole は、すべての INFO 以上のメッセージを sys.stderr に表示 (print) する StreamHandler クラスです。このハンドラは simple 出力フォーマットを使用します。
mail_admins は、ERROR (またはそれより上) のすべてのメッセージをサイトの ADMINS にメール送信する AdminEmailHandler クラスです。このハンドラは special フィルタを使用します。
3 つのロガーを設定します:
\ndjango は、すべてのメッセージを console ハンドラに渡します。
django.request は、すべての ERROR メッセージを mail_admins ハンドラに渡します。加えて、このロガーはメッセージを親に 伝えない よう設定されています。これは、django.request 内に記述されたログメッセージは django ロガーで処理されないことを意味します。
myproject.custom は INFO もしくはそれ以上のすべてのメッセージを渡し、special フィルタを 2 つのハンドラに引き渡します -- console と mail_admins です。これは、INFO 以上のレベルのメッセージがコンソールで表示され、さらに ERROR と CRITICAL のメッセージはメールでも出力されることを意味します。
ロガーの設定に Python の dictConfig フォーマットを使用したくない場合は、あなた自身の設定スキームを定義できます。
\nLOGGING_CONFIG 設定は、Django のロガーを設定するために使われる呼び出し可能関数を定義します。デフォルトでは、Python の logging.config.dictConfig() 関数を指します。しかし、異なる設定処理を使いたい場合は、他の引数を1つ取る任意の呼び出し可能関数を使用できます。LOGGING のコンテンツは、ロギング設定時に引数の値として提供されます。
ロギングを全く設定したくない (あるいは、自分のやり方でロギング手動で設定したい) なら、 LOGGING_CONFIG を None に設定することもできます。これにより、Django のデフォルトのロギング設定 を無効化できます。
LOGGING_CONFIG を None に設定すると、自動でロギングの設定が行われなくなるだけです。ロギング自体が使えなくなるわけではありません。自動でのロギング設定を無効化しても、Django はロギングのメソッドを呼び、もしログ設定がされていれば、そこに出力されます。
Django の自動でのロギング設定を無効化し、手動で設定する場合はこのようにします。
\nsettings.pyLOGGING_CONFIG = None\n\nimport logging.config\n\nlogging.config.dictConfig(...)\nデフォルトの設定処理は、設定が完全にロードされた後にのみ LOGGING_CONFIG を呼ばないことに注意してください。対照的に、設定ファイル内で手動で設定するロギングは、ロギング設定を直ちにロードします。そのため、ロギング設定は、必ずロギングが依存しているすべての設定の 後に 書く必要があります。