Skip to content

Profiling

Overview

The dev_tool supports request profiling through pyinstrument, integrated as a Django Debug Toolbar panel. When enabled, each HTTP request is profiled and saved as an HTML report that can be viewed directly from the toolbar. This is useful for identifying performance bottlenecks in views, queries, and template rendering.

Prerequisites

  • DEBUG must be True
  • PROFILING_ENABLED must be set to True in your development.env
  • The django_spire.profiling app and middleware must be configured in your Django settings (see below)

Configuration

development.env

Add the following environment variables to your development.env file:

PROFILING_ENABLED=True
PROFILING_DIR=.profile
PROFILING_MAX_FILES=10
PROFILE_THRESHOLD=0
Variable Description Default
PROFILING_ENABLED Enables or disables profiling. False
PROFILING_DIR Directory where profile HTML reports are saved. Relative paths are resolved from BASE_DIR. .profile
PROFILING_MAX_FILES Maximum number of profile files to keep. Older files are removed automatically (circular buffer). 10
PROFILE_THRESHOLD Minimum request duration in milliseconds before a profile is saved. Set to 0 to profile all requests. 0

Django Settings

The development settings file (system/development/settings.py) automatically configures profiling when PROFILING_ENABLED=True is set. This adds:

  • django_spire.profiling to INSTALLED_APPS
  • django_spire.profiling.ProfilingMiddleware to MIDDLEWARE
  • The ProfilingPanel to DEBUG_TOOLBAR_PANELS

No manual changes to your Django settings are required.

How It Works

The ProfilingMiddleware intercepts each request and uses pyinstrument to record a detailed execution profile. Static files, debug toolbar requests, and other non-application paths are automatically ignored. After a request completes, the profile is saved as an HTML file in the configured PROFILING_DIR if the request duration meets or exceeds the PROFILE_THRESHOLD.

The Profiles panel in the Django Debug Toolbar displays all saved profiles with the following information:

Column Description
Method The HTTP method (GET, POST, etc.)
Path The request path
Duration How long the request took
Time When the profile was recorded
Size File size of the HTML report
View Opens the full pyinstrument HTML report in a new tab
Delete Removes the profile file

The circular buffer automatically removes older profiles when the number of files exceeds PROFILING_MAX_FILES, keeping only the most recent ones.

Ignored Paths

The profiling middleware skips requests matching common non-application paths, including static files, media files, admin pages, debug toolbar endpoints, and API documentation routes. It also skips requests for common static file extensions such as .js, .css, .png, .jpg, .svg, .woff, and .woff2.