django-silk

Silk is a live profiling and inspection tool for the Django framework. It intercepts and stores HTTP requests and database queries, providing a user interface to inspect them.

Key capabilities include:

• HTTP Inspection: View query parameters, headers, bodies, and execution time for requests and responses.
• SQL Inspection: Monitor database queries, including the number of queries and time taken.
• Code Profiling: Profile arbitrary code blocks using a Python context manager or decorator to track execution time and database queries. This can be injected dynamically at runtime.
• Production Readiness: Supports authentication and authorization for use in production environments.

To develop Silk locally using the provided project sample:

1. Install dependencies for the sample project from the project/ directory.
2. Install Silk in editable mode from the repository root.
3. Set required environment variables (DB_ENGINE and DB_NAME).
4. Run migrations and start the server from the project/ directory.

# 1. Install project dependencies
cd project
pip install -r requirements.txt

# 2. Install silk in editable mode
cd ..
pip install -e .

# 3. Set environment variables
export DB_ENGINE=sqlite3
export DB_NAME=db.sqlite3

# 4. Run migrations and server
cd project
python manage.py migrate
python manage.py runserver

To integrate Silk into your Django project, add 'silk' to INSTALLED_APPS, include 'silk.middleware.SilkyMiddleware' in your MIDDLEWARE list, and ensure 'django.template.context_processors.request' is present in your TEMPLATES context processors.

Middleware Order Warnings:

• The order of middleware is sensitive. Ensure middleware preceding SilkyMiddleware does not bypass or return a response without calling get_response.
• If using django.middleware.gzip.GZipMiddleware, place it before silk.middleware.SilkyMiddleware to avoid encoding errors.

MIDDLEWARE = [
    ...
    'silk.middleware.SilkyMiddleware',
    ...
]

TEMPLATES = [{
    ...
    'OPTIONS': {
        'context_processors': [
            ...
            'django.template.context_processors.request',
        ],
    },
}]

INSTALLED_APPS = (
    ...
    'silk'
)

Silk can generate Python snippets to help you reproduce requests. To enable autopep8 formatting for these snippets, install Silk with the formatting extra.

pip install django-silk[formatting]

Before installing Silk, ensure your environment meets the following version requirements:

• Django: 4.2, 5.1, 5.2, 6.0
• Python: 3.10, 3.11, 3.12, 3.13, 3.14

To access the Silk UI, add the silk URLs to your project's urlpatterns in urls.py. After configuration, run migrations and collect static files to complete the setup.

# In urls.py
urlpatterns += [path('silk/', include('silk.urls', namespace='silk'))]

# Run migrations and collect static files
python manage.py migrate
python manage.py collectstatic

You can install Django Silk using methods other than the standard pip install:

• From a release tarball: Download a release from GitHub and install it using pip.
• Directly from GitHub: Install the latest version directly from the repository (note: this version is not guaranteed to be working).

By default, the Silk UI at /silk/ is public. To restrict access using your Django authentication backend, configure SILKY_AUTHENTICATION and SILKY_AUTHORISATION in settings.py.

If SILKY_AUTHORISATION is enabled, Silk defaults to allowing only users with is_staff=True. You can provide a custom callable (function or lambda) to SILKY_PERMISSIONS to define specific access logic.

# Enable authentication and authorization
SILKY_AUTHENTICATION = True  # User must login
SILKY_AUTHORISATION = True  # User must have permissions

# Custom authorization logic
def my_custom_perms(user):
    return user.is_allowed_to_use_silk

SILKY_PERMISSIONS = my_custom_perms

# Or using a lambda
SILKY_PERMISSIONS = lambda user: user.is_superuser

To generate binary .prof files for use with tools like snakeviz, enable SILKY_PYTHON_PROFILER_BINARY.

You can specify a custom storage class for these files or a specific directory path. If SILKY_PYTHON_PROFILER_RESULT_PATH is not set, MEDIA_ROOT is used as the default.

SILKY_PYTHON_PROFILER = True
SILKY_PYTHON_PROFILER_BINARY = True

# For Django >= 4.2 and Django-Silk >= 5.1.0:
STORAGES = {
    'SILKY_STORAGE': {
        'BACKEND': 'path.to.StorageClass',
    },
}

# For Django < 4.2 or Django-Silk < 5.1.0
SILKY_STORAGE_CLASS = 'path.to.StorageClass'

# Specify the directory (must exist)
SILKY_PYTHON_PROFILER_RESULT_PATH = '/path/to/profiles/'

# Include request path stub in filename to identify endpoints
SILKY_PYTHON_PROFILER_EXTENDED_FILE_NAME = True