litestar-debug-toolbar 0.3.1

Async-native debug toolbar for Python ASGI frameworks with optional Litestar integration

debug-toolbar

Async-native debug toolbar for Python ASGI frameworks with first-class Litestar support.

---

Documentation: https://jacobcoffee.github.io/debug-toolbar

Source Code: https://github.com/JacobCoffee/debug-toolbar

---

Screenshots

More Screenshots

Full-Width Top Position

SQL Queries with EXPLAIN

EXPLAIN Query Plan Modal

Light Theme

Request History

Events Panel (Lifecycle Hooks)

N+1 Query Detection

Alerts Panel (Proactive Issue Detection)

MCP Integration (Claude Code)

Memory Panel

SQL Panel with Query Analysis

Profiling Panel

WebSocket Panel (Live Updates)

Features

• Async-Native: Built from the ground up for async/await patterns
• Framework-Agnostic Core: Core package works with any ASGI framework
• Litestar Integration: First-class plugin support for Litestar applications
• Pluggable Panels: Easy to add, remove, or customize debug panels
• Minimal Overhead: Negligible performance impact when disabled
• Type-Safe: Full type annotations with strict type checking
• Dark/Light Themes: Toggle between dark and light themes
• Flexible Positioning: Place toolbar on any edge (left, right, top, bottom)
• SQL Query Analysis: EXPLAIN query plans for PostgreSQL, SQLite, MySQL, MariaDB
• N+1 Detection: Automatic detection of N+1 query patterns with fix suggestions
• Flame Graphs: Interactive profiling visualization in speedscope format
• Memory Profiling: Multi-backend support (tracemalloc, memray)
• Proactive Alerts: Automatic detection of security, performance, and database issues
• MCP Integration: AI assistant integration for automated debugging with Claude Code
• WebSocket Debugging: Real-time connection tracking with live updates and message inspection

Installation

# Core package only
pip install debug-toolbar

# With Litestar integration
pip install debug-toolbar[litestar]

# With Advanced-Alchemy SQLAlchemy panel
pip install debug-toolbar[advanced-alchemy]

# All extras
pip install debug-toolbar[all]

Or with uv:

uv add debug-toolbar[litestar]

Quick Start

Litestar

from litestar import Litestar, get
from debug_toolbar.litestar import DebugToolbarPlugin, LitestarDebugToolbarConfig

@get("/")
async def index() -> dict[str, str]:
    return {"message": "Hello, World!"}

config = LitestarDebugToolbarConfig(enabled=True)
app = Litestar(
    route_handlers=[index],
    plugins=[DebugToolbarPlugin(config)],
)

With SQLAlchemy (Advanced-Alchemy)

from litestar import Litestar
from advanced_alchemy.extensions.litestar import SQLAlchemyPlugin, SQLAlchemyAsyncConfig
from debug_toolbar.litestar import DebugToolbarPlugin, LitestarDebugToolbarConfig

db_config = SQLAlchemyAsyncConfig(connection_string="sqlite+aiosqlite:///app.db")
toolbar_config = LitestarDebugToolbarConfig(
    enabled=True,
    extra_panels=["debug_toolbar.extras.advanced_alchemy.SQLAlchemyPanel"],
)

app = Litestar(
    plugins=[
        SQLAlchemyPlugin(config=db_config),
        DebugToolbarPlugin(toolbar_config),
    ],
)

Generic ASGI

from debug_toolbar import DebugToolbar, DebugToolbarConfig

config = DebugToolbarConfig(enabled=True)
toolbar = DebugToolbar(config)

# Wrap your ASGI app
app = toolbar.wrap(your_asgi_app)

Built-in Panels

Panel	Description
Timer	Request timing and CPU time
Request	HTTP method, path, headers, cookies
Response	Status code, response headers
Logging	Log records captured during request
Versions	Python and package versions
Headers	Categorized headers with security analysis
Settings	Application configuration viewer
Templates	Jinja2/Mako render tracking
Profiling	cProfile/pyinstrument with flame graphs
Alerts	Proactive security/performance issue detection
Memory	Memory profiling (tracemalloc/memray)
Cache	Redis/memcached operation tracking
Routes	Application routes (Litestar-specific)
Events	Lifecycle hooks and exception handlers (Litestar-specific)
WebSocket	Real-time connection tracking, message inspection, live updates
SQLAlchemy	Query tracking with N+1 detection (requires advanced-alchemy extra)

Configuration

from debug_toolbar.litestar import LitestarDebugToolbarConfig

config = LitestarDebugToolbarConfig(
    enabled=True,
    exclude_paths=["/_debug_toolbar", "/static", "/health"],
    max_request_history=50,
    intercept_redirects=False,
    show_toolbar_callback=lambda request: request.app.debug,
    extra_panels=["myapp.panels.CustomPanel"],
    exclude_panels=["VersionsPanel"],
)

Creating Custom Panels

from typing import Any, ClassVar
from debug_toolbar.core import Panel, RequestContext

class MyCustomPanel(Panel):
    panel_id: ClassVar[str] = "MyCustomPanel"
    title: ClassVar[str] = "My Panel"
    template: ClassVar[str] = "panels/my_panel.html"
    has_content: ClassVar[bool] = True

    async def generate_stats(self, context: RequestContext) -> dict[str, Any]:
        return {"custom_data": "Your debug information here"}

Development

# Clone the repository
git clone https://github.com/JacobCoffee/debug-toolbar.git
cd debug-toolbar

# Install dependencies
make dev

# Run tests
make test

# Run all CI checks
make ci

Package Structure

debug_toolbar/
├── core/           # Framework-agnostic core
│   ├── panels/     # Built-in panels
│   │   ├── timer.py, request.py, response.py  # Default panels
│   │   ├── headers.py, settings.py            # Optional panels
│   │   ├── profiling.py, memory/, alerts.py   # Advanced panels
│   │   ├── templates.py, cache.py             # Integration panels
│   │   └── websocket.py                       # WebSocket debugging
│   ├── config.py   # DebugToolbarConfig
│   ├── context.py  # RequestContext (contextvars-based)
│   ├── panel.py    # Panel base class
│   ├── storage.py  # LRU request history storage
│   └── toolbar.py  # DebugToolbar manager
├── litestar/       # Litestar integration
│   ├── panels/     # Litestar-specific panels (routes, events)
│   ├── config.py   # LitestarDebugToolbarConfig
│   ├── middleware.py
│   └── plugin.py   # DebugToolbarPlugin
└── extras/         # Optional integrations
    └── advanced_alchemy/  # SQLAlchemy panel with N+1 detection

Versioning

This project uses Semantic Versioning.

• Major versions introduce breaking changes
• Major versions support currently supported Litestar versions
• See the Litestar Versioning Policy for details

Contributing

Contributions are welcome! Please see CONTRIBUTING.rst for guidelines.

License

MIT License - see LICENSE for details.

Acknowledgements

Inspired by:

• django-debug-toolbar
• flask-debugtoolbar
• fastapi-debug-toolbar