Django Prometheus

2.4.1 · active · verified Fri Apr 10

django-prometheus is a Python library that provides Prometheus metrics for Django applications. It offers automatic instrumentation for HTTP requests, database queries, and cache operations, as well as features for exposing custom application-level metrics. The library is actively maintained, with version 2.4.1 being the latest release, and regularly updates to support new Django and Python versions.

Warnings

breaking Version 2.4.0 dropped support for Django 3.2 (and Python 3.7), Django 4.0, and Django 4.1. It added support for Django 5.0, 5.1, 5.2 and Python 3.12, 3.13.
Fix: Upgrade your Django and Python versions to supported ones (Django >= 4.2, Python >= 3.9 for 2.4.1) before upgrading django-prometheus.
breaking Version 2.3.0 removed support for Python 3.6 and Django versions older than 3.2.
Fix: Ensure your project runs on Python 3.7+ and Django 3.2+ before upgrading to django-prometheus 2.3.0 or newer.
gotcha The order of `PrometheusBeforeMiddleware` and `PrometheusAfterMiddleware` in your `MIDDLEWARE` setting is crucial. `PrometheusBeforeMiddleware` should be placed very early, and `PrometheusAfterMiddleware` very late, to properly wrap other core Django middlewares for accurate metric collection.
Fix: Always follow the recommended order: `PrometheusBeforeMiddleware` at the start, `PrometheusAfterMiddleware` at the end, with other middlewares in between. Consult the official documentation for the exact order.
gotcha Since version 2.3.0, the `PROMETHEUS_EXPORT_MIGRATIONS` setting defaults to `False`. If you previously relied on metrics for Django migrations, they will no longer be exported unless explicitly enabled.
Fix: Set `PROMETHEUS_EXPORT_MIGRATIONS = True` in your `settings.py` if you wish to continue monitoring Django migrations.
gotcha Prior to version 2.3.0, there was a fix for two latency metrics not correctly using the `PROMETHEUS_LATENCY_BUCKETS` setting. This could lead to inconsistent bucket behavior for custom latency configurations.
Fix: Upgrade to django-prometheus version 2.3.0 or newer to ensure all latency metrics consistently respect the `PROMETHEUS_LATENCY_BUCKETS` setting.

Install

pip install django-prometheus Install stable version

Imports

django_prometheus
```
INSTALLED_APPS = [... 'django_prometheus', ...]
```
Add 'django_prometheus' to your Django project's INSTALLED_APPS.
PrometheusBeforeMiddleware
```
MIDDLEWARE = ['django_prometheus.middleware.PrometheusBeforeMiddleware', ...]
```
Place this middleware early in your MIDDLEWARE list.
PrometheusAfterMiddleware
```
MIDDLEWARE = [... 'django_prometheus.middleware.PrometheusAfterMiddleware']
```
Place this middleware late in your MIDDLEWARE list, after other core Django middlewares.
django_prometheus.urls
```
from django.urls import path, include
urlpatterns = [... path('', include('django_prometheus.urls')), ...]
```
Include 'django_prometheus.urls' to expose the /metrics endpoint in your project's main urls.py.

ExportModelOperationsMixin

from django_prometheus.models import ExportModelOperationsMixin
class MyModel(ExportModelOperationsMixin('mymodel'), models.Model): ...

Used to add creation/deletion/update rate metrics to Django models.

Quickstart

To quickly integrate django-prometheus, add 'django_prometheus' to your `INSTALLED_APPS`. Then, include `PrometheusBeforeMiddleware` and `PrometheusAfterMiddleware` in your `MIDDLEWARE` list, ensuring they wrap other core Django middlewares. Finally, include `django_prometheus.urls` in your project's `urls.py` to expose the metrics endpoint (typically at `/metrics/`).

import os

# settings.py
SECRET_KEY = os.environ.get('DJANGO_SECRET_KEY', 'your-secret-key')
DEBUG = os.environ.get('DJANGO_DEBUG', 'True') == 'True'

INSTALLED_APPS = [
    # ... other Django apps
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'django_prometheus',
]

MIDDLEWARE = [
    'django_prometheus.middleware.PrometheusBeforeMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
    'django_prometheus.middleware.PrometheusAfterMiddleware',
]

# urls.py (in your project's main urls.py)
from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include('django_prometheus.urls')),
    # Your other app URLs
]

# After running the Django dev server, metrics will be available at /metrics/

view raw JSON →