Hướng dẫn cấu hình và sử dụng Django Debug Toolbar

1. Giới thiệu về Debug Toolbar

Django Debug Toolbar là một thư viện hữu ích giúp lập trình viên theo dõi và phân tích thông tin debug của request/response trong quá trình phát triển ứng dụng Django. Thư viện này cung cấp một bảng điều khiển với nhiều panel hiển thị các thông tin chi tiết như thời gian xử lý, câu lệnh SQL, thông tin request, v.v.

Tài liệu chính thức: https://django-debug-toolbar.readthedocs.io/en/latest/

2. Cài đặt và cấu hình

2.1. Cài đặt package

Sử dụng pip để cài đặt thư viện:

pip install django-debug-toolbar==1.11

Lưu ý: Bài viết này sử dụng phiên bản 1.11.

2.2. Cấu hình trong settings.py

Trước tiên, bạn cần đảm bảo django.contrib.staticfiles đã được cài đặt và kích hoạt:

INSTALLED_APPS = [
    # ...
    'django.contrib.staticfiles',
    # ...
    'debug_toolbar',
]

STATIC_URL = '/static/'

2.3. Cấu hình URL routing

Thêm đoạn code sau vào cuối file urls.py chính của dự án:

from django.conf import settings

if settings.DEBUG:
    import debug_toolbar
    urlpatterns = [
        path('__debug__/', include(debug_toolbar.urls)),
    ] + urlpatterns

Giải thích:

  • Sử dụng đường dẫn __debug__ để tránh xung đột với các URL khác trong ứng dụng.
  • Không nên đặt code này trong file urls.py của sub-app vì sẽ gây ra lỗi NoReverseMatch 'djdt' is not a registered namespace.

2.4. Kích hoạt Middleware

Debug Toolbar hoạt động thông qua middleware. Thêm dòng sau vào MIDDLEWARE trong settings.py:

MIDDLEWARE = [
    # ...
    'debug_toolbar.middleware.DebugToolbarMiddleware',
    # ...
]

Mẹo: Nên đặt middleware này càng sớm càng tốt, nhưng phải sau các middleware xử lý encoding và response content (ví dụ: GZipMiddleware).

2.5. Cấu hình Internal IP

Debug Toolbar chỉ cho phép các IP cụ thể truy cập. Thêm cấu hình sau vào settings.py:

INTERNAL_IPS = [
    '127.0.0.1',
]

2.6. Kiểm tra hoạt động

Sau khi hoàn tất cấu hình, truy cập bất kỳ trang nào trong ứng dụng. Bạn sẽ thấy một biểu tượng DJDT nhỏ ở góc phải màn hình.

Lưu ý: Trang không có thẻ <body> sẽ không hiển thị toolbar. Ví dụ:

def my_view(request):
    return HttpResponse('Chào mừng bạn đến với khóa học')

3. Các Panel chức năng

Debug Toolbar cung cấp các panel sau:

  • Versions: Hiển thị phiên bản Django đang sử dụng.
  • Timer: Đo thời gian tải trang.
  • Settings: Hiển thị các cấu hình Django.
  • Headers: Thông tin request header và response header.
  • Request: Thông tin request hiện tại (view function, Cookie, Session...).
  • SQL: Hiển thị các câu lệnh SQL đã thực thi.
  • StaticFiles: Danh sách file tĩnh được tải.
  • Templates: Thông tin về template đã sử dụng.
  • Cache: Thông tin cache.
  • Signals: Thông tin signal.
  • Logging: Thông tin log.
  • Redirects: Thông tin chuyển hướng.

4. Tùy chỉnh Panel

Mặc định, Debug Toolbar sử dụng tất cả các panel ở trên. Cấu hình mặc định được lưu trong debug_toolbar.settings.CONFIG_DEFAULTS và debug_toolbar.settings.PANELS_DEFAULTS.

Để tùy chỉnh danh sách panel, thêm cấu hình sau vào settings.py:

DEBUG_TOOLBAR_PANELS = [
    "debug_toolbar.panels.timer.TimerPanel",
    "debug_toolbar.panels.headers.HeadersPanel",
    "debug_toolbar.panels.request.RequestPanel",
    "debug_toolbar.panels.templates.TemplatesPanel",
]

Ví dụ trên chỉ kích hoạt 4 panel: Timer, Headers, Request và Templates. Bạn có thể thêm panel tùy chỉnh, xóa panel mặc định hoặc thay đổi thứ tự hiển thị.

5. Tùy chỉnh Toolbar

Sử dụng cấu hình DEBUG_TOOLBAR_CONFIG trong settings.py để tùy chỉnh hành vi của toolbar. Cấu hình này được chia làm hai phần: tùy chỉnh toolbar và tùy chỉnh panel.

DEBUG_TOOLBAR_CONFIG = {
    # Tùy chỉnh Toolbar
    "DISABLE_PANELS": {"debug_toolbar.panels.redirects.RedirectsPanel"},
    "INSERT_BEFORE": "</body>",
    "RENDER_PANELS": None,
    "RESULTS_CACHE_SIZE": 10,
    "ROOT_TAG_EXTRA_ATTRS": "",
    "SHOW_COLLAPSED": False,
    "SHOW_TOOLBAR_CALLBACK": "debug_toolbar.middleware.show_toolbar",
    # Tùy chỉnh Panel
    "EXTRA_SIGNALS": [],
    "ENABLE_STACKTRACES": True,
    "HIDE_IN_STACKTRACES": (
        "socketserver",
        "threading",
        "wsgiref",
        "debug_toolbar",
        "django.db",
        "django.core.handlers",
        "django.core.servers",
        "django.utils.decorators",
        "django.utils.deprecation",
        "django.utils.functional",
    ),
    "PROFILER_MAX_DEPTH": 10,
    "SHOW_TEMPLATE_CONTEXT": True,
    "SKIP_TEMPLATE_PREFIXES": ("django/forms/widgets/", "admin/widgets/"),
    "SQL_WARNING_THRESHOLD": 500,  # milliseconds
}

Tùy chỉnh Toolbar

  • DISABLE_PANELS (mặc định: {'debug_toolbar.panels.redirects.RedirectsPanel'}): Danh sách các panel bị vô hiệu hóa nhưng vẫn hiển thị.
  • INSERT_BEFORE (mặc định: '</body>'): Vị trí chèn toolbar vào HTML.
  • RENDER_PANELS (mặc định: None): Nếu False, nội dung panel được giữ trong bộ nhớ server và tải theo yêu cầu. Nếu True, panel được render ngay trong trang (chậm hơn nhưng phù hợp với multi-process server). Mặc định None cho phép toolbar tự động chọn.
  • RESULTS_CACHE_SIZE (mặc định: 10): Số lượng kết quả cache được lưu trong bộ nhớ.
  • ROOT_TAG_EXTRA_ATTRS (mặc định: ''): Thêm thuộc tính vào thẻ div gốc để tránh xung đột với client framework (ví dụ: 'ng-non-bindable' cho Angular.js).
  • SHOW_COLLAPSED (mặc định: False): Nếu True, toolbar sẽ thu gọn mặc định.
  • SHOW_TOOLBAR_CALLBACK (mặc định: 'debug_toolbar.middleware.show_toolbar'): Hàm xác định khi nào toolbar hiển thị. Mặc định kiểm tra DEBUG=True và IP trong INTERNAL_IPS:
def show_toolbar(request):
    if request.META.get("REMOTE_ADDR", None) not in settings.INTERNAL_IPS:
        return False
    return bool(settings.DEBUG)

Tùy chỉnh Panel

  • EXTRA_SIGNALS (mặc định: []): Danh sách signal tùy chỉnh cho panel Signals.
  • ENABLE_STACKTRACES (mặc định: True): Hiển thị stack trace cho SQL và cache. Bật tính năng này sẽ tăng CPU sử dụng.
  • HIDE_IN_STACKTRACES (mặc định: ('socketserver', 'threading', 'wsgiref', 'debug_toolbar', 'django')): Loại bỏ các stack trace không cần thiết.
  • PROFILER_MAX_DEPTH (mặc định: 10): Độ sâu tối đa của profiler.
  • SHOW_TEMPLATE_CONTEXT (mặc định: True): Hiển thị context của template trong panel Templates. Tắt nếu context quá lớn hoặc chứa lazy data structures.
  • SKIP_TEMPLATE_PREFIXES (mặc định: ('django/forms/widgets/', 'admin/widgets/')): Bỏ qua template có prefix không cần thiết để tránh HTML quá lớn.
  • SQL_WARNING_THRESHOLD (mặc định: 500): Đánh dấu các câu lệnh SQL có thời gian thực thi vượt quá ngưỡng (milliseconds).

Thẻ: Django Debug Toolbar python Web Development debugging

Đăng vào ngày 23 tháng 7 lúc 09:14

Thẻ Phổ Biến

©2026 Thành phố Cuồng loạn