DOCSEARCHbyAlgolia
Submit Docs

django-debug-toolbar

repository·main·Indexed 27 days ago

https://github.com/django-commons/django-debug-toolbar

A configurable set of panels for Django applications that display real-time debug information about requests, database queries, and performance metrics. Version 0.1.0 includes features such as the debugsqlshell management command for SQL query timing, customizable storage classes (MemoryStore, DatabaseStore, CacheStore), and detailed configuration options for SQL, Profiling, and Templates panels.

Tokens
8.2K
Snippets
20
Records
56
Agent score
91%

What's inside django-debug-toolbar

  1. Overview of Django Debug Toolbar

    main
    The Django Debug Toolbar is a configurable set of panels that display various debug information about the current request/response. When panels are clicked, they display more detailed information about their content. It supports built-in panels as well as third-party community panels.

  2. Use built-in Django Debug Toolbar panels

    main

    The Django Debug Toolbar includes several built-in panels to inspect request data, SQL queries, templates, and more. These are enabled by default.

    Available Built-in Panels:

    • HistoryPanel: Shows request history and allows switching to past snapshots.
      • Note: Disabled if RENDER_PANELS is True or if running with multiple processes.
    • VersionsPanel: Shows versions of Python, Django, and installed apps.
    • TimerPanel: Displays the request timer.
    • SettingsPanel: Lists settings from settings.py.
    • HeadersPanel: Shows HTTP request/response headers and WSGI environment values.
    • RequestPanel: Displays GET, POST, cookie, and session variables.
    • SQLPanel: Shows SQL queries, execution time, and links to EXPLAIN queries.
    • StaticFilesPanel: Shows used static files and their locations.
    • TemplatesPanel: Shows templates used, context, and template paths.
    • AlertsPanel: Shows alerts (e.g., forms missing enctype="multipart/form-data" when containing file inputs).
    • CachePanel: Shows cache queries (incompatible with Django's per-site caching).
    • SignalsPanel: Lists signals and receivers.
    • CommunityPanel: Provides links to the Django Debug Toolbar community.
    • ProfilingPanel: Provides profiling information for request processing.
      • Note: Inactive by default. For Python 3.12+, use python -m manage runserver --nothreading. Concurrent requests are not supported.

  3. Understand the Django Debug Toolbar architecture

    main

    The Django Debug Toolbar is built around three core components that manage integration, orchestration, and data collection:

    • debug_toolbar.middleware.DebugToolbarMiddleware: The primary integration point. It decides if a request should be instrumented, selects which panels to use, and injects the toolbar's HTML, JavaScript, and headers into the response.
    • debug_toolbar.toolbar.DebugToolbar: The orchestrator. It manages the execution flow across all enabled panels but remains decoupled from the user's specific Django project logic.
    • debug_toolbar.panels: The data collectors. Most complex logic resides here. Panels collect metrics either by inspecting the request/response or via monkey-patching (e.g., TemplatesPanel). Some panels, like SQLPanel, include dedicated views (e.g., debug_toolbar.panels.sql.views) to handle user interactions and display additional data.

  4. Set up a development environment

    main

    To work on the Django Debug Toolbar, clone the repository and install the necessary development and documentation dependencies. If you have fetch.fsckObjects enabled in your git config, you must deactivate it for this clone to avoid errors with old objects.

    1. Clone the repository (with the specific config if needed):
    2. Install development and documentation groups using pip.
    3. Run the example application to verify the setup.

  5. Manually set up the example project

    main

    If you prefer to run setup steps individually from the root directory of the repository, use the following commands:

    1. Create the database: python example/manage.py migrate
    2. Create a superuser: python example/manage.py createsuperuser
    3. Run the development server: python example/manage.py runserver
    $ python example/manage.py migrate
$ python example/manage.py createsuperuser
$ python example/manage.py runserver

  7. Configure Django prerequisites for Debug Toolbar

    main

    Ensure your Django project meets these three requirements:

    1. Static Files: 'django.contrib.staticfiles' must be in INSTALLED_APPS and STATIC_URL must be configured.
    2. Templates: Your TEMPLATES setting must use the DjangoTemplates backend with APP_DIRS set to True.
    3. Browser: Use a modern browser that meets Baseline Widely Available standards.
    INSTALLED_APPS = [
    # ...
    "django.contrib.staticfiles",
    # ...
]

STATIC_URL = "static/"

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "APP_DIRS": True,
        # ...
    }
]

  11. Use the debugsqlshell command to inspect database queries

    main
    The debugsqlshell command starts an interactive Python shell similar to Django's built-in shell. The key difference is that every Django ORM call that results in a database query will automatically print the formatted SQL statement directly to the shell output. This is useful for debugging N+1 problems and verifying that select_related or prefetch_related are working as expected.

  12. Configure database permissions for Tox testing

    main

    If you are running tests via tox against databases other than SQLite, you must manually create the user and database with appropriate permissions.

    # For PostgreSQL
psql> CREATE USER debug_toolbar WITH PASSWORD 'debug_toolbar';
psql> ALTER USER debug_toolbar CREATEDB;
psql> CREATE DATABASE debug_toolbar;
psql> GRANT ALL PRIVILEGES ON DATABASE debug_toolbar to debug_toolbar;

# For MySQL/MariaDB
mysql> CREATE DATABASE debug_toolbar;
mysql> CREATE USER 'debug_toolbar'@'localhost' IDENTIFIED BY 'debug_toolbar';
mysql> GRANT ALL PRIVILEGES ON debug_toolbar.* TO 'debug_toolbar'@'localhost';
mysql> GRANT ALL PRIVILEGES ON test_debug_toolbar.* TO 'debug_toolbar'@'localhost';