Export Django monitoring metrics for Prometheus.io
This library provides Prometheus metrics for Django related operations:
Install with:
pip install django-prometheus
Or, if you're using a development version cloned from this repository:
python path-to-where-you-cloned-django-prometheus/setup.py install
This will install prometheus_client as a dependency.
In your settings.py:
INSTALLED_APPS = [
...
'django_prometheus',
...
]
MIDDLEWARE = [
'django_prometheus.middleware.PrometheusBeforeMiddleware',
# All your other middlewares go here, including the default
# middlewares like SessionMiddleware, CommonMiddleware,
# CsrfViewmiddleware, SecurityMiddleware, etc.
'django_prometheus.middleware.PrometheusAfterMiddleware',
]
In your urls.py:
urlpatterns = [
...
path('', include('django_prometheus.urls')),
]
Prometheus uses Histogram based grouping for monitoring latencies. The default buckets are:
PROMETHEUS_LATENCY_BUCKETS = (0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1.0, 2.5, 5.0, 7.5, 10.0, 25.0, 50.0, 75.0, float("inf"),)
You can define custom buckets for latency, adding more buckets decreases performance but increases accuracy: https://prometheus.io/docs/practices/histograms/
PROMETHEUS_LATENCY_BUCKETS = (.1, .2, .5, .6, .8, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.5, 9.0, 12.0, 15.0, 20.0, 30.0, float("inf"))
You can have a custom namespace for your metrics:
PROMETHEUS_METRIC_NAMESPACE = "project"
This will prefix all metrics with project_
word like this:
project_django_http_requests_total_by_method_total{method="GET"} 1.0
SQLite, MySQL, and PostgreSQL databases can be monitored. Just
replace the ENGINE
property of your database, replacing
django.db.backends
with django_prometheus.db.backends
.
DATABASES = {
'default': {
'ENGINE': 'django_prometheus.db.backends.sqlite3',
'NAME': os.path.join(BASE_DIR, 'db.sqlite3'),
},
}
Filebased, memcached, redis caches can be monitored. Just replace
the cache backend to use the one provided by django_prometheus
django.core.cache.backends
with django_prometheus.cache.backends
.
CACHES = {
'default': {
'BACKEND': 'django_prometheus.cache.backends.filebased.FileBasedCache',
'LOCATION': '/var/tmp/django_cache',
}
}
You may want to monitor the creation/deletion/update rate for your model. This can be done by adding a mixin to them. This is safe to do on existing models (it does not require a migration).
If your model is:
class Dog(models.Model):
name = models.CharField(max_length=100, unique=True)
breed = models.CharField(max_length=100, blank=True, null=True)
age = models.PositiveIntegerField(blank=True, null=True)
Just add the ExportModelOperationsMixin
as such:
from django_prometheus.models import ExportModelOperationsMixin
class Dog(ExportModelOperationsMixin('dog'), models.Model):
name = models.CharField(max_length=100, unique=True)
breed = models.CharField(max_length=100, blank=True, null=True)
age = models.PositiveIntegerField(blank=True, null=True)
This will export 3 metrics, django_model_inserts_total{model="dog"}
,
django_model_updates_total{model="dog"}
and
django_model_deletes_total{model="dog"}
.
Note that the exported metrics are counters of creations, modifications and deletions done in the current process. They are not gauges of the number of objects in the model.
Starting with Django 1.7, migrations are also monitored. Two gauges
are exported, django_migrations_applied_by_connection
and
django_migrations_unapplied_by_connection
. You may want to alert if
there are unapplied migrations.
If you want to disable the Django migration metrics, set the
PROMETHEUS_EXPORT_MIGRATIONS
setting to False.
Prometheus is quite easy to set up. An example prometheus.conf to
scrape 127.0.0.1:8001
can be found in examples/prometheus
.
Here's an example of a PromDash displaying some of the metrics collected by django-prometheus:
You can add application-level metrics in your code by using prometheus_client directly. The exporter is global and will pick up your metrics.
To add metrics to the Django internals, the easiest way is to extend django-prometheus' classes. Please consider contributing your metrics, pull requests are welcome. Make sure to read the Prometheus best practices on instrumentation and naming.
If you wish to use Django Prometheus but are not able to change the code base, it's possible to have all the default metrics by modifying only the settings.
First step is to inject prometheus' middlewares and to add django_prometheus in INSTALLED_APPS
MIDDLEWARE = \
['django_prometheus.middleware.PrometheusBeforeMiddleware'] + \
MIDDLEWARE + \
['django_prometheus.middleware.PrometheusAfterMiddleware']
INSTALLED_APPS += ['django_prometheus']
Second step is to create the /metrics end point, for that we need another file (called urls_prometheus_wrapper.py in this example) that will wraps the apps URLs and add one on top:
from django.urls import include, path
urlpatterns = []
urlpatterns.append(path('prometheus/', include('django_prometheus.urls')))
urlpatterns.append(path('', include('myapp.urls')))
This file will add a "/prometheus/metrics" end point to the URLs of django that will export the metrics (replace myapp by your project name).
Then we inject the wrapper in settings:
ROOT_URLCONF = "graphite.urls_prometheus_wrapper"
You can add application specific labels to metrics reported by the django-prometheus middleware. This involves extending the classes defined in middleware.py.
register_metric
method to add the application specific labels.See implementation example in the test app