debug_toolbar.core.panels

Built-in panels for the async debug toolbar.

class debug_toolbar.core.panels.AlertsPanel(toolbar)

Panel displaying proactive alerts for potential issues.

Detects and warns about: - Security issues (CSRF, insecure cookies, missing headers) - Performance problems (slow queries, large responses) - Database issues (N+1 queries) - Configuration problems (debug mode in production)

CATEGORY_CONFIGURATION: ClassVar[str] = 'configuration'

CATEGORY_DATABASE: ClassVar[str] = 'database'

CATEGORY_PERFORMANCE: ClassVar[str] = 'performance'

CATEGORY_SECURITY: ClassVar[str] = 'security'

N_PLUS_ONE_CRITICAL_THRESHOLD: ClassVar[int] = 10

N_PLUS_ONE_THRESHOLD: ClassVar[int] = 3

QUERY_TIME_CRITICAL_MS: ClassVar[float] = 500.0

QUERY_TIME_WARNING_MS: ClassVar[float] = 100.0

RESPONSE_SIZE_CRITICAL_BYTES: ClassVar[int] = 5242880

RESPONSE_SIZE_WARNING_BYTES: ClassVar[int] = 1048576

SEVERITY_CRITICAL: ClassVar[str] = 'critical'

SEVERITY_INFO: ClassVar[str] = 'info'

SEVERITY_WARNING: ClassVar[str] = 'warning'

async generate_stats(context)

Generate alert statistics from context metadata.

Return type:

dict[str, Any]

get_nav_subtitle()

Get the navigation subtitle showing alert count and severity.

Return type:

str

has_content: ClassVar[bool] = True

nav_title: ClassVar[str] = 'Alerts'

panel_id: ClassVar[str] = 'AlertsPanel'

template: ClassVar[str] = 'panels/alerts.html'

title: ClassVar[str] = 'Alerts'

class debug_toolbar.core.panels.AsyncProfilerPanel(toolbar)

Panel for profiling async task execution and event loop behavior.

Tracks: - Async task creation and completion via task factory hooks - Blocking calls that stall the event loop - Event loop lag monitoring - Timeline visualization of concurrent execution

Configure via toolbar config:

async_profiler_backend: “taskfactory” | “yappi” | “auto” (default: “auto”) async_blocking_threshold_ms: float (default: 100.0) async_enable_blocking_detection: bool (default: True) async_enable_event_loop_monitoring: bool (default: True) async_capture_task_stacks: bool (default: True) async_max_stack_depth: int (default: 10)

__init__(toolbar)

Initialize the async profiler panel.

Parameters:

toolbar (DebugToolbar) – The parent DebugToolbar instance.

generate_server_timing(context)

Generate Server-Timing header data for async profiling overhead.

Parameters:

context (RequestContext) – The current request context.

Return type:

dict[str, float]

Returns:

Dictionary mapping metric names to durations in seconds.

async generate_stats(context)

Generate async profiling statistics.

Parameters:

context (RequestContext) – The current request context.

Return type:

dict[str, Any]

Returns:

Dictionary of async profiling statistics.

get_nav_subtitle()

Get the navigation subtitle showing task count or warnings.

Return type:

str

Returns:

Formatted subtitle string.

has_content: ClassVar[bool] = True

nav_title: ClassVar[str] = 'Async'

panel_id: ClassVar[str] = 'AsyncProfilerPanel'

async process_request(context)

Start async profiling at request start.

Parameters:

context (RequestContext) – The current request context.

Return type:

None

async process_response(context)

Stop async profiling at response completion.

Parameters:

context (RequestContext) – The current request context.

Return type:

None

template: ClassVar[str] = 'panels/async_profiler.html'

title: ClassVar[str] = 'Async'

class debug_toolbar.core.panels.CachePanel(toolbar)

Panel displaying cache operations during the request.

Tracks: - Cache operations (GET, SET, DELETE, etc.) - Hit/miss status - Operation duration - Backend type (Redis, memcached) - Aggregate statistics

__init__(toolbar)

Initialize the panel.

Parameters:

toolbar (DebugToolbar) – The parent DebugToolbar instance.

generate_server_timing(context)

Generate Server-Timing data for cache operations.

Return type:

dict[str, float]

async generate_stats(context)

Generate cache statistics.

Return type:

dict[str, Any]

get_nav_subtitle()

Get the navigation subtitle showing cache stats.

Return type:

str

has_content: ClassVar[bool] = True

nav_title: ClassVar[str] = 'Cache'

panel_id: ClassVar[str] = 'CachePanel'

async process_request(context)

Start tracking cache operations.

Return type:

None

async process_response(context)

Stop tracking cache operations.

Return type:

None

template: ClassVar[str] = 'panels/cache.html'

title: ClassVar[str] = 'Cache'

class debug_toolbar.core.panels.HeadersPanel(toolbar)

Panel displaying detailed HTTP header analysis.

Analyzes both request and response headers, providing: - Categorization by type (authentication, content, caching, CORS, security, custom) - Authorization header parsing and analysis - Cookie inspection and counting - Cache-Control directive parsing - Security header detection and validation - CORS header analysis

AUTHENTICATION_HEADERS = frozenset({'authorization', 'proxy-authenticate', 'proxy-authorization', 'www-authenticate'})

CACHING_HEADERS = frozenset({'age', 'cache-control', 'etag', 'expires', 'if-match', 'if-modified-since', 'if-none-match', 'if-unmodified-since', 'last-modified', 'pragma', 'vary'})

CONTENT_HEADERS = frozenset({'accept', 'accept-charset', 'accept-encoding', 'accept-language', 'content-disposition', 'content-encoding', 'content-language', 'content-length', 'content-location', 'content-md5', 'content-range', 'content-type'})

CORS_HEADERS = frozenset({'access-control-allow-credentials', 'access-control-allow-headers', 'access-control-allow-methods', 'access-control-allow-origin', 'access-control-expose-headers', 'access-control-max-age', 'access-control-request-headers', 'access-control-request-method', 'origin'})

RECOMMENDED_SECURITY_HEADERS = frozenset({'content-security-policy', 'strict-transport-security', 'x-content-type-options', 'x-frame-options'})

SECURITY_HEADERS = frozenset({'content-security-policy', 'content-security-policy-report-only', 'cross-origin-embedder-policy', 'cross-origin-opener-policy', 'cross-origin-resource-policy', 'permissions-policy', 'referrer-policy', 'strict-transport-security', 'x-content-type-options', 'x-frame-options', 'x-xss-protection'})

async generate_stats(context)

Generate header statistics from context metadata.

Return type:

dict[str, Any]

get_nav_subtitle()

Get the navigation subtitle.

Return type:

str

has_content: ClassVar[bool] = True

nav_title: ClassVar[str] = 'Headers'

panel_id: ClassVar[str] = 'HeadersPanel'

template: ClassVar[str] = 'panels/headers.html'

title: ClassVar[str] = 'Headers'

class debug_toolbar.core.panels.LoggingPanel(toolbar)

Panel displaying log records captured during the request.

Shows: - Log level - Logger name - Message - Source location - Exception info (if present)

__init__(toolbar)

Initialize the panel.

Parameters:

toolbar (DebugToolbar) – The parent DebugToolbar instance.

async generate_stats(context)

Generate logging statistics.

Return type:

dict[str, Any]

get_nav_subtitle()

Get the navigation subtitle showing log count.

Return type:

str

has_content: ClassVar[bool] = True

nav_title: ClassVar[str] = 'Logs'

panel_id: ClassVar[str] = 'LoggingPanel'

async process_request(context)

Start capturing logs.

Return type:

None

async process_response(context)

Stop capturing logs.

Return type:

None

template: ClassVar[str] = 'panels/logging.html'

title: ClassVar[str] = 'Logging'

class debug_toolbar.core.panels.MemoryPanel(toolbar)

Panel for profiling memory allocations during request processing.

Supports multiple profiling backends: - tracemalloc: Standard library profiler (default, always available) - memray: Bloomberg’s profiler with C extension tracking (Linux/macOS only)

The panel automatically selects the best available backend based on platform and installed dependencies, with an option to override via config.

Features:

• Before/after memory snapshots

• Memory delta tracking

• Peak memory monitoring

• Top allocations by file and line

• Multi-backend support with automatic selection

Configure via toolbar config:

memory_backend: “tracemalloc” | “memray” | “auto” (default: “auto”)

__init__(toolbar)

Initialize the memory panel with appropriate backend.

Parameters:

toolbar (DebugToolbar) – The parent DebugToolbar instance.

generate_server_timing(context)

Generate Server-Timing header data for memory profiling overhead.

Parameters:

context (RequestContext) – The current request context.

Return type:

dict[str, float]

Returns:

Dictionary mapping metric names to durations in seconds.

async generate_stats(context)

Generate memory profiling statistics.

Parameters:

context (RequestContext) – The current request context.

Return type:

dict[str, Any]

Returns:

Dictionary of memory statistics.

get_nav_subtitle()

Get the navigation subtitle showing memory delta.

Return type:

str

Returns:

Formatted memory delta string (e.g., “+2.3 MB” or “-500 KB”).

has_content: ClassVar[bool] = True

nav_title: ClassVar[str] = 'Memory'

panel_id: ClassVar[str] = 'MemoryPanel'

async process_request(context)

Start memory profiling at request start.

Parameters:

context (RequestContext) – The current request context.

Return type:

None

async process_response(context)

Stop memory profiling at response completion.

Parameters:

context (RequestContext) – The current request context.

Return type:

None

template: ClassVar[str] = 'panels/memory.html'

title: ClassVar[str] = 'Memory'

class debug_toolbar.core.panels.ProfilingPanel(toolbar)

Panel for profiling request performance.

Supports two profiling backends: - cProfile: Standard library profiler (default) - pyinstrument: Optional third-party profiler (more readable output)

The profiler tracks function calls, execution time, and generates detailed statistics about performance hotspots.

Configure via toolbar config:

profiler_backend: “cprofile” | “pyinstrument” (default: “cprofile”) profiler_top_functions: int (default: 50) profiler_sort_by: str (default: “cumulative”) enable_flamegraph: bool (default: True)

__init__(toolbar)

Initialize the panel.

Parameters:

toolbar (DebugToolbar) – The parent DebugToolbar instance.

generate_server_timing(context)

Generate Server-Timing data for profiling overhead.

Return type:

dict[str, float]

async generate_stats(context)

Generate profiling statistics.

Return type:

dict[str, Any]

get_nav_subtitle()

Get the navigation subtitle showing backend.

Return type:

str

has_content: ClassVar[bool] = True

nav_title: ClassVar[str] = 'Profile'

panel_id: ClassVar[str] = 'ProfilingPanel'

async process_request(context)

Start profiling at request start.

Return type:

None

async process_response(context)

Stop profiling at response completion.

Return type:

None

template: ClassVar[str] = 'panels/profiling.html'

title: ClassVar[str] = 'Profiling'

class debug_toolbar.core.panels.RequestPanel(toolbar)

Panel displaying request details.

Shows: - HTTP method and path - Query parameters - Headers - Cookies - Request body (if available)

async generate_stats(context)

Generate request statistics from context metadata.

Return type:

dict[str, Any]

get_nav_subtitle()

Get the navigation subtitle.

Return type:

str

has_content: ClassVar[bool] = True

nav_title: ClassVar[str] = 'Request'

panel_id: ClassVar[str] = 'RequestPanel'

template: ClassVar[str] = 'panels/request.html'

title: ClassVar[str] = 'Request'

class debug_toolbar.core.panels.ResponsePanel(toolbar)

Panel displaying response details.

Shows: - Status code - Response headers - Content type - Content length

async generate_stats(context)

Generate response statistics from context metadata.

Return type:

dict[str, Any]

get_nav_subtitle()

Get the navigation subtitle.

Return type:

str

has_content: ClassVar[bool] = True

nav_title: ClassVar[str] = 'Response'

panel_id: ClassVar[str] = 'ResponsePanel'

template: ClassVar[str] = 'panels/response.html'

title: ClassVar[str] = 'Response'

class debug_toolbar.core.panels.SettingsPanel(toolbar, *, custom_settings=None, show_env=True, sensitive_keys=None)

Panel displaying application configuration and environment settings.

Shows: - Debug toolbar configuration - Environment variables (with sensitive values redacted) - Python runtime settings - Custom application settings

Parameters:

• toolbar (Any) – The parent DebugToolbar instance.

• custom_settings (dict[str, Any] | None) – Optional custom settings to display.

• show_env (bool) – Whether to show environment variables.

• sensitive_keys (Sequence[str] | None) – Additional keys to redact beyond default patterns.

DEFAULT_SENSITIVE_PATTERNS: ClassVar[tuple[str, ...]] = ('PASSWORD', 'SECRET', 'KEY', 'TOKEN', 'API_KEY', 'AUTH', 'CREDENTIAL', 'PRIVATE')

MAX_PATH_ITEMS: ClassVar[int] = 10

REDACTED_VALUE: ClassVar[str] = '**********'

__init__(toolbar, *, custom_settings=None, show_env=True, sensitive_keys=None)

Initialize the settings panel.

Parameters:

• toolbar (Any) – The parent DebugToolbar instance.

• custom_settings (dict[str, Any] | None) – Optional custom settings to display.

• show_env (bool) – Whether to show environment variables.

• sensitive_keys (Sequence[str] | None) – Additional keys to redact beyond default patterns.

async generate_stats(context)

Generate settings statistics.

Parameters:

context (RequestContext) – The current request context.

Return type:

dict[str, Any]

Returns:

Dictionary containing all settings data.

get_nav_subtitle()

Get the navigation subtitle.

Return type:

str

Returns:

The number of configuration sections.

has_content: ClassVar[bool] = True

nav_title: ClassVar[str] = 'Settings'

panel_id: ClassVar[str] = 'SettingsPanel'

template: ClassVar[str] = 'panels/settings.html'

title: ClassVar[str] = 'Settings'

class debug_toolbar.core.panels.TemplatesPanel(toolbar)

Panel for tracking template rendering performance.

Monitors template renders across multiple engines (Jinja2, Mako) and collects: - Template names - Render times - Template engines used - Context variable names (when available)

The panel patches template engine render methods during the request to capture timing data transparently.

__init__(toolbar)

Initialize the panel.

Parameters:

toolbar (DebugToolbar) – The parent DebugToolbar instance.

generate_server_timing(context)

Generate Server-Timing header data for template rendering.

Return type:

dict[str, float]

Returns:

Dictionary mapping metric names to durations in seconds.

async generate_stats(context)

Generate template rendering statistics.

Returns:

• renders: List of render events with timing data

• total_renders: Total number of templates rendered

• total_time: Cumulative render time in seconds

• engines_used: List of template engines used

Return type:

Dictionary containing

get_nav_subtitle()

Get navigation subtitle showing render count and time.

Return type:

str

has_content: ClassVar[bool] = True

nav_title: ClassVar[str] = 'Templates'

panel_id: ClassVar[str] = 'TemplatesPanel'

async process_request(context)

Install template rendering hooks.

Patches Jinja2 and Mako template engines to track renders.

Return type:

None

async process_response(context)

Remove template rendering hooks.

Clears the active tracker to stop recording renders.

Return type:

None

template: ClassVar[str] = 'panels/templates.html'

title: ClassVar[str] = 'Templates'

class debug_toolbar.core.panels.TimerPanel(toolbar)

Panel displaying request timing information.

Tracks: - Total request duration - Time spent in various phases - CPU time (user and system)

__init__(toolbar)

Initialize the panel.

Parameters:

toolbar (Any) – The parent DebugToolbar instance.

generate_server_timing(context)

Generate Server-Timing data.

Return type:

dict[str, float]

async generate_stats(context)

Generate timing statistics.

Return type:

dict[str, Any]

get_nav_subtitle()

Get the navigation subtitle showing time.

Return type:

str

has_content: ClassVar[bool] = True

nav_title: ClassVar[str] = 'Time'

panel_id: ClassVar[str] = 'TimerPanel'

async process_request(context)

Record the start time.

Return type:

None

template: ClassVar[str] = 'panels/timer.html'

title: ClassVar[str] = 'Time'

class debug_toolbar.core.panels.VersionsPanel(toolbar)

Panel displaying Python and package version information.

Shows: - Python version - Platform information - Installed packages

async generate_stats(context)

Generate version statistics.

Return type:

dict[str, Any]

get_nav_subtitle()

Get the navigation subtitle showing Python version.

Return type:

str

has_content: ClassVar[bool] = True

nav_title: ClassVar[str] = 'Versions'

panel_id: ClassVar[str] = 'VersionsPanel'

template: ClassVar[str] = 'panels/versions.html'

title: ClassVar[str] = 'Versions'

class debug_toolbar.core.panels.WebSocketPanel(toolbar)

Panel for displaying WebSocket connection and message information.

classmethod broadcast_message(connection_id, message)

Broadcast a message event to live subscribers.

Parameters:

• connection_id (str) – The connection ID the message belongs to.

• message (WebSocketMessage) – The WebSocket message that was sent/received.

Return type:

None

classmethod broadcast_state_change(connection_id, state, close_code=None)

Broadcast a connection state change to live subscribers.

Parameters:

• connection_id (str) – The connection ID.

• state (str) – New connection state.

• close_code (int | None) – WebSocket close code if applicable.

Return type:

None

async generate_stats(context)

Generate WebSocket statistics.

Parameters:

context (RequestContext) – The current request context.

Return type:

dict[str, Any]

Returns:

Dictionary containing WebSocket statistics.

classmethod get_connection(connection_id)

Get a tracked connection by ID.

Parameters:

connection_id (str) – The connection ID to look up.

Return type:

WebSocketConnection | None

Returns:

The connection if found, None otherwise.

classmethod get_current_stats()

Get current WebSocket statistics without a context.

This is used for live updates via WebSocket.

Return type:

dict[str, Any]

Returns:

Dictionary containing current WebSocket statistics.

get_nav_subtitle()

Get the navigation subtitle showing active connection count.

Return type:

str

Returns:

Subtitle string showing active connection count, or empty string.

has_content: ClassVar[bool] = True

nav_title: ClassVar[str] = 'WebSocket'

panel_id: ClassVar[str] = 'WebSocketPanel'

classmethod subscribe()

Subscribe to live WebSocket panel updates.

Return type:

Queue[str]

Returns:

An asyncio.Queue that will receive JSON-encoded event messages.

template: ClassVar[str] = 'panels/websocket.html'

title: ClassVar[str] = 'WebSocket'

classmethod track_connection(connection, ttl=3600, max_connections=50)

Track a new WebSocket connection.

Parameters:

• connection (WebSocketConnection) – The connection to track.

• ttl (int) – Time-to-live in seconds for disconnected connections. Defaults to 3600.

• max_connections (int) – Maximum connections to track. Oldest are dropped when exceeded.

Return type:

None

classmethod unsubscribe(queue)

Unsubscribe from live updates.

Parameters:

queue (Queue[str]) – The queue to remove from subscribers.

Return type:

None

classmethod untrack_connection(connection_id)

Remove a connection from tracking.

Parameters:

connection_id (str) – The ID of the connection to remove.

Return type:

None