--- title: "ロギング" version: 5.0 locale: ja source: https://docs.djangoproject.com/ja/5.0/ref/logging/ canonical: https://djangodocs.dev/ja/5.0/ref/logging/ --- # ロギング > **See also** > > - [ロギングの設定と利用](/ja/5.0/howto/logging/#logging-how-to) > - [Django のロギングの概要](/ja/5.0/topics/logging/#logging-explanation) Django の logging モジュールは Python の 組み込み [`logging`](https://docs.python.org/3/library/logging.html#module-logging) モジュールを継承しています。 Logging は、一般的なDjangoの [`django.setup()`](/ja/5.0/ref/applications/#django.setup) 関数の一部として設定されているため、明示的に無効にされない限り常に利用可能です。 ## Django のデフォルトのロギング設定 デフォルトでは、Django は Python の [logging.config.dictConfig フォーマット](https://docs.python.org/3/library/logging.config.html#logging-config-dictschema) を使用します。 ### デフォルトのログ記録条件 デフォルトのログ記録条件の完全なセットは以下の通りです: [`DEBUG`](/ja/5.0/ref/settings/#std-setting-DEBUG) が `True` のとき: - `django` ロガーは、`django` ヒエラルキー (`django.server` を除く) において、`INFO` レベル以上のメッセージをコンソールに送信します。 [`DEBUG`](/ja/5.0/ref/settings/#std-setting-DEBUG) が `False` のとき: - `django` ロガーは、`django` ヒエラルキー (`django.server` を除く) において、`ERROR` ないし `CRITICAL` レベルを [`AdminEmailHandler`](#django.utils.log.AdminEmailHandler) に送信します。 [`DEBUG`](/ja/5.0/ref/settings/#std-setting-DEBUG) の値にかかわらず: - [django.server](#django-server-logger) ロガーは `INFO` レベル以上のメッセージをコンソールに送信します。 [django.server](#django-server-logger) を除く全てのロガーは、ルートの `django` ロガーまで、親に対してログを伝播させます。`console` と `mail_admins` ハンドラは、上述の動作を提供するためにルートロガーにアタッチされます。 Pythonのデフォルトは、レベル `WARNING` 以上のレコードをコンソールに送ります。 ### デフォルトのロギング定義 Django のデフォルトのロギング設定は、Python のデフォルトを継承しています。これは `django.utils.log.DEFAULT_LOGGING` として利用可能で、 [django/utils/log.py](https://github.com/django/django/blob/stable/5.0.x/django/utils/log.py) で定義されています。 ``` { "version": 1, "disable_existing_loggers": False, "filters": { "require_debug_false": { "()": "django.utils.log.RequireDebugFalse", }, "require_debug_true": { "()": "django.utils.log.RequireDebugTrue", }, }, "formatters": { "django.server": { "()": "django.utils.log.ServerFormatter", "format": "[{server_time}] {message}", "style": "{", } }, "handlers": { "console": { "level": "INFO", "filters": ["require_debug_true"], "class": "logging.StreamHandler", }, "django.server": { "level": "INFO", "class": "logging.StreamHandler", "formatter": "django.server", }, "mail_admins": { "level": "ERROR", "filters": ["require_debug_false"], "class": "django.utils.log.AdminEmailHandler", }, }, "loggers": { "django": { "handlers": ["console", "mail_admins"], "level": "INFO", }, "django.server": { "handlers": ["django.server"], "level": "INFO", "propagate": False, }, }, } ``` このデフォルトのロギング設定を補完または置換する方法については、[ロギングを設定する](/ja/5.0/topics/logging/#configuring-logging) を参照してください。 ## Django のロギング拡張 Djangoは、Web サーバー環境でのロギングの特別な要件を処理するための多数のユーティリティを提供しています。 ### ロガー Djangoはいくつかの組み込みロガーを提供しています。 #### `django` `django` [名前付きロガー階層](/ja/5.0/howto/logging/#naming-loggers-hierarchy) のメッセージの親ロガーです。 Djangoは、この名前を使用してメッセージを投稿しません。代わりに、以下のロガーのいずれかを使用します。 #### `django.request` リクエストに関するログをハンドリングします。5XXレスポンスは `ERROR` メッセージとして送られ、 4XXレスポンスは `WARNING` メッセージとして送られます。 `django.security` ロガーに出力されたメッセージは、 `django.request` ロガーには送られません。 このロガーに送られるメッセージには、以下のようなコンテキストが含まれます。 - `status_code`: リクエストに対するレスポンスのHTTPレスポンスコード。 - `request`: ログのメッセージに対応するリクエストのオブジェクト。 #### `django.server` [`runserver`](/ja/5.0/ref/django-admin/#django-admin-runserver) コマンドによって立ち上がったサーバーが受け取ったリクエストに関するログメッセージ。HTTP の 5XX レスポンスは `ERROR` メッセージとして送られ、 4XX レスポンスは `WARNING` メッセージとして送られ、その他は `INFO` メッセージとして送られます。 このロガーに送られるメッセージには、以下のようなコンテキストが含まれます。 - `status_code`: リクエストに対するレスポンスのHTTPレスポンスコード。 - `request`: ログメッセージを生成したリクエストオブジェクト ([`socket.socket`](https://docs.python.org/3/library/socket.html#socket.socket)) 。 #### `django.template` テンプレートのレンダリングに関するログメッセージ。 - コンテキストに変数が無い場合は DEBUG メッセージとして送られる。 #### `django.db.backends` コードとデータベースの間でのやりとりに関するメッセージ。たとえば、アプリケーションから実行全ての SQL は `DEBUG` レベルでメッセージが送られます。 このロガーに送られるメッセージには、以下のようなコンテキストが含まれます。 - `duration`: SQLを実行するのにかかった時間。 - `sql`: 実行されたSQL文。 - `params`: SQLの呼び出しに使ったパラメータ。 - `alias`: SQL 呼び出しで使用されるデータベースのエイリアス。 パフォーマンスの観点から、 SQL ログは、ログレベルやハンドラに関わらず、 `settings.DEBUG` に True が設定されているときのみ有効になります。 このログには、フレームワークレベルの初期化(例: `SET TIMEZONE`) は含まれていません。すべてのデータベースクエリを表示したい場合は、データムベースでクエリログを有効にしてください。 > **Changed in Django 4.2** > > トランザクション管理クエリ(`BEGIN`, `COMMIT`, `ROLLBACK`)のログ記録のサポートが追加されました。 #### `django.utils.autoreload` Django 開発サーバー実行中の自動コードリロードに関連するログメッセージです。このロガーは、ソースコードファイルの変更を検出した際に `INFO` メッセージを生成し、ファイルシステムの検査やイベント購読プロセス中に `WARNING` メッセージを生成することがあります。 #### `django.contrib.auth` > **New in Django 4.2.16** Log messages related to [django.contrib.auth](/ja/5.0/ref/contrib/auth/), particularly `ERROR` messages are generated when a [`PasswordResetForm`](/ja/5.0/topics/auth/default/#django.contrib.auth.forms.PasswordResetForm) is successfully submitted but the password reset email cannot be delivered due to a mail sending exception. #### `django.contrib.gis` [GeoDjango](/ja/5.0/ref/contrib/gis/) に関連するログメッセージは、外部の地理空間ライブラリ（GEOS、GDALなど）の読み込み時や、エラーを報告する時点で様々な場所に記録されます。各 `ERROR` ログレコードには、発生した例外と関連するコンテキストデータが含まれます。 #### `django.dispatch` このロガーは [シグナル](/ja/5.0/ref/signals/) において使用されており、特に [`Signal`](/ja/5.0/topics/signals/#django.dispatch.Signal) クラス内で、接続されたレシーバへのシグナルのディスパッチ時に問題が発生した場合に報告するために使用されます。`ERROR` ログレコードには捕捉された例外が `exc_info` として含まれ、以下の追加コンテキストが加えられます。 - `receiver`: レシーバの名前。 - `err`: レシーバを呼び出した時に発生した例外。 #### `django.security.*` セキュリティログは、 [`SuspiciousOperation`](/ja/5.0/ref/exceptions/#django.core.exceptions.SuspiciousOperation) および他のセキュリティ関連のエラーが発生した際にメッセージを受け取ります。セキュリティエラーの各サブタイプごとにサブロガーがあり、すべての `SuspiciousOperation` が含まれます。ログイベントのレベルは、例外が処理される場所によって異なります。ほとんどの発生は警告としてログされますが、WSGIハンドラーに到達した `SuspiciousOperation` はエラーとしてログされます。たとえば、クライアントからのリクエストに含まれるHTTP `Host` ヘッダーが [`ALLOWED_HOSTS`](/ja/5.0/ref/settings/#std-setting-ALLOWED_HOSTS) と一致しない場合、Djangoは400のレスポンスを返し、`django.security.DisallowedHost` ロガーにエラーメッセージがログされます。 これらのログイベントはデフォルトで `django` ロガーに到達し、`DEBUG=False` のときにはエラーイベントを管理者にメールします。`SuspiciousOperation` によって400レスポンスを引き起こすリクエストは `django.request` ロガーには記録されず、`django.security` ロガーにのみ記録されます。 特定のタイプの `SuspiciousOperation` を無視するには、以下の例に従って、その特定のロガーをオーバーライドできます: ``` LOGGING = { # ... "handlers": { "null": { "class": "logging.NullHandler", }, }, "loggers": { "django.security.DisallowedHost": { "handlers": ["null"], "propagate": False, }, }, # ... } ``` `SuspiciousOperation` に基づかない他の `django.security` ロガーには、以下があります: - `django.security.csrf`: [CSRF の失敗](/ja/5.0/howto/csrf/#csrf-rejected-requests) に関するもの。 #### `django.db.backends.schema` スキーマの変更中に実行されるSQLクエリを、 [マイグレーションフレームワーク](/ja/5.0/topics/migrations/) によってログ記録します。ただし、 [`RunPython`](/ja/5.0/ref/migration-operations/#django.db.migrations.operations.RunPython) によって実行されるクエリはログされません。このロガーへのメッセージには、 `params` と `sql` が追加のコンテキストとして含まれます（ただし、 `django.db.backends` とは異なり、実行時間は含まれません）。これらの値の意味については、 [django.db.backends](#django-db-logger) で説明されている内容と同じです。 ### ハンドラ Django は、 [`Pythonのモジュールによって提供されるもの`](https://docs.python.org/3/library/logging.handlers.html#module-logging.handlers) に加えて、1つのログハンドラを提供しています。 #### `class AdminEmailHandler(include_html=False, email_backend=None, reporter_class=None)` このハンドラは、受け取ったログメッセージごとにサイトの [`ADMINS`](/ja/5.0/ref/settings/#std-setting-ADMINS) に電子メールを送信します。 ログレコードに `request` 属性が含まれている場合、リクエストの詳細がメールに含まれます。クライアントの IP アドレスが [`INTERNAL_IPS`](/ja/5.0/ref/settings/#std-setting-INTERNAL_IPS) 設定にある場合、メールの件名に "internal IP" というフレーズが含まれます。そうでない場合は "EXTERNAL IP" が含まれます。 ログレコードにスタックトレース情報が含まれている場合、そのスタックトレースは電子メールに含まれます。 `AdminEmailHandler` の `include_html` 引数は、 [`DEBUG`](/ja/5.0/ref/settings/#std-setting-DEBUG) が `True` の場合に生成されるデバッグウェブページの内容を含む HTML 添付ファイルを traceback メールに含めるかどうかを制御するために使用されます。この値を設定するには、`django.utils.log.AdminEmailHandler` のハンドラ定義に含めます。以下のようになります: ``` "handlers": { "mail_admins": { "level": "ERROR", "class": "django.utils.log.AdminEmailHandler", "include_html": True, }, } ``` `AdminEmailHandler` を使用する際は、 [ログのセキュリティ上の注意点](/ja/5.0/topics/logging/#logging-security-implications) に注意してください。 `AdminEmailHandler` の `email_backend` 引数を設定することで、ハンドラーが使用している [メールバックエンド](/ja/5.0/topics/email/#topic-email-backends) を以下のように上書きできます: ``` "handlers": { "mail_admins": { "level": "ERROR", "class": "django.utils.log.AdminEmailHandler", "email_backend": "django.core.mail.backends.filebased.EmailBackend", }, } ``` デフォルトでは、 [`EMAIL_BACKEND`](/ja/5.0/ref/settings/#std-setting-EMAIL_BACKEND) で指定されたメールバックエンドのインスタンスが使用されます。 `AdminEmailHandler` の `reporter_class` 引数では、メール本文で送信されるトレースバックテキストをカスタマイズするために `django.views.debug.ExceptionReporter` サブクラスを提供できます。使用したいクラスへの文字列インポートパスをこのように指定します: ``` "handlers": { "mail_admins": { "level": "ERROR", "class": "django.utils.log.AdminEmailHandler", "include_html": True, "reporter_class": "somepackage.error_reporter.CustomErrorReporter", }, } ``` #### `send_mail(subject, message, *args, **kwargs)` 管理ユーザーにメールを送信します。この動作をカスタマイズするためには、 [`AdminEmailHandler`](#django.utils.log.AdminEmailHandler) クラスをサブクラス化して、このメソッドをオーバーライドできます。 ### フィルタ Djangoは、Pythonのロギングモジュールによって提供されるフィルタに加えて、いくつかのログフィルタを提供しています。 #### `class CallbackFilter(callback)` このフィルタは、(1 つの引数、ログを行うレコード) を受け入れるコールバック関数を受け入れ、フィルタを通過する各レコードに対してその関数をコールします。コールバックが False を返す場合、そのレコードの処理は進みません。 例えば、管理者メールから（ユーザーがアップロードをキャンセルした時に発生する） [`UnreadablePostError`](/ja/5.0/ref/exceptions/#django.http.UnreadablePostError) をフィルタリングするために、フィルタ関数を作成します。 ``` from django.http import UnreadablePostError def skip_unreadable_post(record): if record.exc_info: exc_type, exc_value = record.exc_info[:2] if isinstance(exc_value, UnreadablePostError): return False return True ``` 次に、ログ設定にそれを追加します: ``` LOGGING = { # ... "filters": { "skip_unreadable_posts": { "()": "django.utils.log.CallbackFilter", "callback": skip_unreadable_post, }, }, "handlers": { "mail_admins": { "level": "ERROR", "filters": ["skip_unreadable_posts"], "class": "django.utils.log.AdminEmailHandler", }, }, # ... } ``` #### `class RequireDebugFalse` このフィルタは、`settings.DEBUG` が False の時のみ、レコードを通過させます。 このフィルタは、デフォルトの [`LOGGING`](/ja/5.0/ref/settings/#std-setting-LOGGING) 設定で以下のように使用され、 [`DEBUG`](/ja/5.0/ref/settings/#std-setting-DEBUG) が `False` のときのみ [`AdminEmailHandler`](#django.utils.log.AdminEmailHandler) がエラーメールを管理者に送信するようにします: ``` LOGGING = { # ... "filters": { "require_debug_false": { "()": "django.utils.log.RequireDebugFalse", }, }, "handlers": { "mail_admins": { "level": "ERROR", "filters": ["require_debug_false"], "class": "django.utils.log.AdminEmailHandler", }, }, # ... } ``` #### `class RequireDebugTrue` このフィルタは [`RequireDebugFalse`](#django.utils.log.RequireDebugFalse) に似ていますが、[`DEBUG`](/ja/5.0/ref/settings/#std-setting-DEBUG) が `True` の場合にのみレコードが渡されます。