概要
Django Debug Toolbarで確認できる代表的な表示パネルと、DEBUG_TOOLBAR_PANELSによるカスタマイズ方法を整理する。
Toolbarの各パネルは、バージョン、処理時間、SQL、テンプレート、キャッシュ、ログなど、画面表示時の内部情報を確認する入口になる。
どのパネルで何を見られるかを知っておくと、原因調査の流れを作りやすい。
掲載画像はDjango 2.0.2を利用していた当時の画面であり、現行版とはパネル名や構成が異なる。
画像は画面の見方をつかむための旧版例として使用し、現行版との差分もあわせて説明する。
この記事の構成
- 対象環境と利用上の注意
本文記載時の環境と現在そのまま利用できない箇所を確認。 - 作業時の注意点
設定変更やコマンド実行前に確認しておきたい注意点を整理。 - 表示パネルの概要説明
各パネルで確認できるリクエスト、SQL、テンプレートなどの情報を整理。 - 現行版での主な違い
現行版での主な違いを対比し、それぞれの特徴を整理。 - 表示パネルのカスタマイズ
表示するパネルを設定で追加・削除・並べ替える方法を確認。
対象環境と利用上の注意
- 本文記載時の環境
掲載画像はDjango 2.0.2と当時のDjango Debug Toolbarを利用した旧環境。
現行版との差分は本文で分けて説明する。 - 確認時期
2026年8月にDjango Debug Toolbarの公式資料と照合。
掲載画像と同じ操作を現行版で再実行していない。 - 現在そのまま利用できない箇所
既定パネル、パネル名、表示項目、設定クラスは版によって変わる。
画像どおりの表示を前提にせず、利用中の版の公式パネル一覧と設定方法を確認する。
作業時の注意点
- パネルの見方
全パネルを見るより、調査目的に合わせて見る場所を決める。 - Timerの解釈
サーバー処理とブラウザ側の表示時間を混同しない。 - SQLの多さ
クエリ数だけでなく、同じSQLが繰り返されていないかを見る。 - Redirects
有効化するとリダイレクト動作が変わるため、調査時だけ使う。 - 公開環境での利用
設定値やSQLなどの内部情報を表示するため、外部公開された本番環境では有効にしない。
実施内容
表示パネルの概要説明
以下は、掲載画像を取得した旧バージョンで表示されていたパネルについての説明である。
現行版の構成は後述の「現行版での主な違い」で補足する。
-
Versions
Python、Django、インストール済みアプリなど、調査対象のバージョン情報を確認。依存ライブラリ固有の不具合を調べるときは、まずここで実行環境を特定する。
-
Timer（掲載画像では「時刻」）
リクエスト処理のCPU時間と経過時間を確認。
掲載画像ではブラウザ側のタイミングも別欄に表示されている。
- Resource usage > User CPU time
Pythonプロセスがユーザーモードで実際にCPUを使用した時間。 - Resource usage > System CPU time
OSカーネルがシステムコールなどの処理にCPUを使用した時間。 - Resource usage > Total CPU time
User CPU timeとSystem CPU timeの合計。 - Resource usage > Elapsed time
処理開始から終了までに経過した実時間。I/O待ちなども含むため、通常はTotal CPU timeと一致しない。ブラウザの描画時間そのものを表す値ではない。 - Resource usage > Context switches
voluntaryはI/O待ちなどで処理が自発的にCPUを譲った回数、involuntaryはOSのスケジューラによって実行が切り替えられた回数。
- Resource usage > User CPU time
-
Settings
settings.pyの設定値を一覧で確認できる。
-
Headers
HTTPのリクエストヘッダー情報、レスポンスヘッダー情報、WSGI環境情報を確認できる。
-
Request
ViewやCookie、Sessionなどのリクエスト情報を確認できる。
-
SQL
画面が表示されるまでに実行されたSQL文、各クエリの実行時間、類似・重複クエリ、スタックトレースなどを確認できる。
-
Static Files
画面を表示する際に読み込んだStaticファイルを確認できる。
-
Templates
画面を表示する際に使用されたテンプレート、継承関係、コンテキストを確認できる。
想定外のテンプレートが選ばれた場合や、変数が渡っていない場合の切り分けに使う。
-
Cache
リクエスト中に行われたキャッシュ操作や処理時間を確認。
キャッシュが期待どおり使われているか、同じキーへ不要なアクセスがないかを調べる入口になる。
-
Signals
Djangoのシグナルと登録済みレシーバーを一覧で確認。
意図したレシーバーが登録されているかを調べる際に役立つ。
-
Logging
当時の組み込みLoggingパネルでは、Pythonのloggingモジュールで出力したログを確認できた。
現行版の組み込みパネル一覧には含まれていないため、現在の環境では通常のログ出力や対応する外部ツールを利用。
-
Intercept redirects
有効にするとリダイレクト前に中間ページを表示し、その時点のデバッグ情報を確認できる。
ただし、現行版では非推奨で、リダイレクトされたリクエストの情報はHistoryパネルから確認する方法が推奨されている。
現行版での主な違い
掲載画像の旧版と比べ、現行版の組み込みパネルにはHistory、Alerts、Communityなどが追加されている。
一方、旧版のLoggingパネルは現行版の組み込み一覧には含まれない。
- History
過去のリクエストを選び、その時点のToolbar情報を確認。
リダイレクト前後の調査にも利用できる。 - Alerts
ファイル入力を含むフォームでenctype="multipart/form-data"が不足している場合など、既知の問題を通知する。 - Redirects
現行版にも含まれるが既定では無効で、バージョン6.0から非推奨となっている。 - Profiling
リクエスト処理中の関数呼び出しを確認するパネル。
現行版では構成に含まれるが既定では無効である。
表示パネルのカスタマイズ
表示するパネルは、settings.pyのDEBUG_TOOLBAR_PANELSで変更できる。
現行版の既定値は次の構成で、並び替え、削除、追加が可能である。
ただし、既定値をそのままコピーすると将来の改善を取り込めなくなるため、変更が必要な場合だけ設定する。
-
DEBUG_TOOLBAR_PANELS = [ 'debug_toolbar.panels.history.HistoryPanel', 'debug_toolbar.panels.versions.VersionsPanel', 'debug_toolbar.panels.timer.TimerPanel', 'debug_toolbar.panels.settings.SettingsPanel', 'debug_toolbar.panels.headers.HeadersPanel', 'debug_toolbar.panels.request.RequestPanel', 'debug_toolbar.panels.sql.SQLPanel', 'debug_toolbar.panels.staticfiles.StaticFilesPanel', 'debug_toolbar.panels.templates.TemplatesPanel', 'debug_toolbar.panels.alerts.AlertsPanel', 'debug_toolbar.panels.cache.CachePanel', 'debug_toolbar.panels.signals.SignalsPanel', 'debug_toolbar.panels.community.CommunityPanel', 'debug_toolbar.panels.redirects.RedirectsPanel', 'debug_toolbar.panels.profiling.ProfilingPanel', ] -
プロファイリング情報の確認例
Profilingパネルを有効にすると、関数ごとの呼び出し回数や処理時間を確認できる。
Python 3.12以降では、公式ドキュメントに記載された実行条件もあわせて確認。
-
その他のパネルについて
公式ドキュメントにはサードパーティ製のパネルも掲載されているが、Django Debug Toolbar本体による正式サポートの対象外である。
導入前に、対応バージョンや更新状況を確認。
まとめ
- Django Debug Toolbarの各パネルは、Django画面表示の内部状態を確認するための入口になる。
- SQL、Templates、Timerなどは、性能調査や表示不具合の確認で特に役立つ。
DEBUG_TOOLBAR_PANELSを使うと、必要なパネルだけに絞って調査しやすくできる。- パネル構成はバージョンによって変わるため、旧版の画面例と利用中の公式ドキュメントを照合する。