django-prometheus

django-prometheus instruments Django applications for Prometheus.io, exporting metrics for HTTP requests and responses, database queries, cache operations, and model changes with minimal setup. It ships as a set of Django middleware classes, database engine and cache backend wrappers, and a model mixin, so existing projects can add monitoring by swapping a few settings.py values rather than rewriting application code.

The library depends on prometheus_client for metric collection and exposes a /metrics Django view (or an optional standalone HTTP thread) for Prometheus to scrape. It supports SQLite, MySQL, and PostgreSQL for database metrics and file-based, memcached, and Redis for cache metrics, and it monitors Django migration state out of the box.

What You Get

• Before/after middleware pair (PrometheusBeforeMiddleware / PrometheusAfterMiddleware) exporting request counts, latency histograms, status codes, and exception counters.
• Drop-in database engine wrappers (django_prometheus.db.backends.*) for SQLite, MySQL, and PostgreSQL that count connections, queries, and errors by vendor.
• Drop-in cache backend wrappers for filebased, memcached, and Redis caches tracking get/hit/miss/fail rates.
• ExportModelOperationsMixin for per-model insert/update/delete counters, plus automatic Django migration-state gauges.
• A /metrics Django view (via django_prometheus.urls) or an optional standalone threaded HTTP exporter for environments where Django can’t serve the endpoint itself.

Common Use Cases

• Adding Prometheus-based SLO dashboards for request latency and error rate to an existing Django service without rewriting views.
• Tracking per-database query volume and error rate across multiple configured Django database aliases.
• Alerting on unapplied Django migrations in production via the exported migration gauges.
• Monitoring cache hit/miss ratios to validate a caching strategy change, such as switching backends or TTLs.

Under The Hood

Architecture django-prometheus is organized by instrumentation domain rather than by Django layer: middleware.py holds a singleton Metrics registry plus the before/after middleware pair that increments counters and histograms at each request phase, db/common.py provides DatabaseWrapperMixin and an ExportingCursorWrapper factory that per-vendor backend modules mix into Django’s real DatabaseWrapper/cursor classes, cache/ follows the same wrapper pattern for cache backends, models.py exposes ExportModelOperationsMixin as a mixin factory keyed by a model label, and migrations.py/exports.py handle migration-state gauges and the /metrics HTTP surface respectively, with conf/__init__.py centralizing settings indirection. The design deliberately keeps every integration point a subclass or mixin over Django’s own classes (DatabaseWrapper, cursor, cache backend, middleware), so adopting a metric means changing an ENGINE/BACKEND string or adding a mixin, not calling into a separate API; the Metrics.register_metric/label_metric override points exist specifically so downstream apps can attach custom labels without forking the library.

Tech Stack The only runtime dependency is prometheus-client>=0.7, kept intentionally minimal; the package supports Django >=4.2,<6.2 (excluding 5.0.x) and Python 3.9 through 3.14, including free-threaded builds. Build tooling is a hybrid setup.py + pyproject.toml (setuptools/wheel backend), tested across a wide tox matrix (py39-py314 x django420/510/520/600/610) with GitHub Actions workflows for CI, pre-release, and release. Linting runs through ruff (targeting py39, with bugbear, comprehensions, isort, pyupgrade, and flake8-2020 rule sets enabled) via a pre-commit tox environment.

Code Quality The project carries two layers of tests: focused unit tests (test_db_wrapper.py, test_django_prometheus.py, test_exports.py, test_testutils.py) and a full end-to-end Django test application (tests/end2end/testapp) that exercises middleware, database wrappers, cache wrappers, migrations, and models against a real Django settings module, run via pytest/coverage across the entire tox version matrix. Exceptions are counted rather than swallowed: ExceptionCounterByType is a context manager that labels and increments a counter on exception, then lets the exception propagate; connection-creation failures are counted and re-raised the same way. Naming consistently follows Prometheus conventions (_total, _seconds, _bytes suffixes); the codebase has no static type hints or mypy checking.

What Makes It Unique The library’s distinguishing technique is that its Django, database, and cache integrations require no application code changes at all — only a settings.py string swap (ENGINE/BACKEND) or, for models, a single mixin — which is a more invasive but more complete integration approach than a middleware-only Prometheus exporter. Combined with automatic Django migration-state gauges, this gives operators visibility into ORM and cache internals that generic HTTP-only instrumentation libraries don’t expose, though the underlying metrics-collection approach itself is standard Prometheus client usage rather than conceptually new.