django-xbench 0.1.2

Django middleware that measures request time breakdown (total/db/app) and query count using execute_wrapper.

django-xbench

Here's how django-xbench exposes request timing breakdown using the Server-Timing header:

Measure Django request time breakdown (total / db / app) and query count with minimal setup.
Adds Server-Timing and X-Bench-Queries headers and optionally logs per-request metrics.

Goal: make performance debugging “visible” (DB vs app/serialization) without heavyweight APM.

Features

• ✅ Measures total request time and DB time (via connection.execute_wrapper)
• ✅ Calculates app time (= total - db)
• ✅ Counts DB queries
• ✅ Adds response headers:
  • Server-Timing: xbench-total;dur=..., xbench-db;dur=..., xbench-app;dur=...
  • X-Bench-Queries: <int>
• ✅ Optional logging:
  • [XBENCH] GET /path | xbench_total=...ms xbench_db=...ms xbench_app=...ms q=...
• ✅ Tested with pytest + pytest-django

Installation

pip install django-xbench

For local development (recommended):

pip install -e ".[dev]"

Quickstart

1. Add middleware in your settings.py:

MIDDLEWARE = [
    # Recommended: place near the top to approximate end-to-end server time
    # (includes other middleware overhead).
    "django_xbench.middleware.XBenchMiddleware",

    # ... other middleware ...

    # Optional: place near the bottom to focus on view/serializer/template time.
    # (Excludes middleware above XBench; includes anything below it.)
]

2. Run your server and hit any endpoint:

In your project:

python manage.py runserver
curl -I http://127.0.0.1:8000/<your-endpoint>/

In this repo (demo):

python -m examples.manage runserver
curl -I http://127.0.0.1:8000/db-heavy/

You should see headers similar to:

Server-Timing: xbench-total;dur=12.345, xbench-db;dur=1.234, xbench-app;dur=11.111
X-Bench-Queries: 3

Output

Server-Timing

Example:

Server-Timing: xbench-total;dur=52.300, xbench-db;dur=14.100, xbench-app;dur=38.200

• xbench-total: whole request duration
• xbench-db: total DB time measured by wrapper
• xbench-app: max(0, total - db) (serialization/template/python time etc.)

You can inspect this in Chrome DevTools → Network → Timing
(or any browser that supports the Server-Timing spec).

Query count header

X-Bench-Queries: 5

Configuration

You can configure XBench via settings.py or Environment Variables.

settings.py:

XBENCH_LOG_ENABLED = True
XBENCH_LOG_LEVEL = "debug"  # default: "info"

Example (Windows):

set XBENCH_LOG_ENABLED=1
set XBENCH_LOG_LEVEL=debug

Example (macOS/Linux):

export XBENCH_LOG_ENABLED=1
export XBENCH_LOG_LEVEL=debug

Development

Run tests

pytest

Note: this repo includes a bundled examples/ Django project used by pytest-django. In CI, we set PYTHONPATH=examples to ensure examples.config.settings can be imported reliably.

If you want to see logs while testing:

pytest -s

Demo project (bundled)

This repository includes an examples/ Django project for manual testing.

Run it from the repository root:

python -m examples.manage runserver

Try a few endpoints:

curl -I http://127.0.0.1:8000/db-heavy/
curl -I http://127.0.0.1:8000/app-heavy/
curl -I http://127.0.0.1:8000/admin/login/

Compatibility

• Python: 3.9+
• Django: 3.2+ (tested on 5.2)

Roadmap

• DRF serialization time breakdown (view/serializer timing)
• More robust Server-Timing merging (preserve existing metrics)
• Docs: real-world examples (N+1 detection demo endpoints)

Contributing

Issues and PRs are welcome.
If you propose new metrics, please include:

• minimal reproducible example
• tests
• documentation update

License

MIT