282 lines
9.3 KiB
Plaintext
282 lines
9.3 KiB
Plaintext
Metadata-Version: 2.1
|
|
Name: django-prometheus
|
|
Version: 2.4.1
|
|
Summary: Django middlewares to monitor your application with Prometheus.io.
|
|
Home-page: http://github.com/korfuri/django-prometheus
|
|
Author: Uriel Corfa
|
|
Author-email: uriel@corfa.fr
|
|
License: Apache
|
|
Project-URL: Changelog, https://github.com/korfuri/django-prometheus/blob/master/CHANGELOG.md
|
|
Project-URL: Documentation, https://github.com/korfuri/django-prometheus/blob/master/README.md
|
|
Project-URL: Source, https://github.com/korfuri/django-prometheus
|
|
Project-URL: Tracker, https://github.com/korfuri/django-prometheus/issues
|
|
Keywords: django monitoring prometheus
|
|
Classifier: Development Status :: 5 - Production/Stable
|
|
Classifier: Intended Audience :: Developers
|
|
Classifier: Intended Audience :: Information Technology
|
|
Classifier: Intended Audience :: System Administrators
|
|
Classifier: Programming Language :: Python :: 3
|
|
Classifier: Programming Language :: Python :: 3.9
|
|
Classifier: Programming Language :: Python :: 3.10
|
|
Classifier: Programming Language :: Python :: 3.11
|
|
Classifier: Programming Language :: Python :: 3.12
|
|
Classifier: Programming Language :: Python :: 3.13
|
|
Classifier: Framework :: Django :: 4.2
|
|
Classifier: Framework :: Django :: 5.0
|
|
Classifier: Framework :: Django :: 5.1
|
|
Classifier: Framework :: Django :: 5.2
|
|
Classifier: Topic :: System :: Monitoring
|
|
Classifier: License :: OSI Approved :: Apache Software License
|
|
Description-Content-Type: text/markdown
|
|
License-File: LICENSE
|
|
Requires-Dist: Django<6.0,>=4.2
|
|
Requires-Dist: prometheus-client>=0.7
|
|
|
|
# django-prometheus
|
|
|
|
Export Django monitoring metrics for Prometheus.io
|
|
|
|
[](https://gitter.im/django-prometheus/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
|
|
|
[](http://badge.fury.io/py/django-prometheus)
|
|
[](https://github.com/korfuri/django-prometheus/actions/workflows/ci.yml)
|
|
[](https://coveralls.io/github/korfuri/django-prometheus?branch=master)
|
|
[](https://pypi.python.org/pypi/django-prometheus)
|
|
|
|
|
|
## Features
|
|
|
|
This library provides Prometheus metrics for Django related operations:
|
|
|
|
* Requests & Responses
|
|
* Database access done via [Django ORM](https://docs.djangoproject.com/en/3.2/topics/db/)
|
|
* Cache access done via [Django Cache framework](https://docs.djangoproject.com/en/3.2/topics/cache/)
|
|
|
|
## Usage
|
|
|
|
### Requirements
|
|
|
|
* Django >= 4.2
|
|
* Python 3.9 and above.
|
|
|
|
### Installation
|
|
|
|
Install with:
|
|
|
|
```shell
|
|
pip install django-prometheus
|
|
```
|
|
|
|
Or, if you're using a development version cloned from this repository:
|
|
|
|
```shell
|
|
python path-to-where-you-cloned-django-prometheus/setup.py install
|
|
```
|
|
|
|
This will install [prometheus_client](https://github.com/prometheus/client_python) as a dependency.
|
|
|
|
### Quickstart
|
|
|
|
In your settings.py:
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
urlpatterns = [
|
|
...
|
|
path('', include('django_prometheus.urls')),
|
|
]
|
|
```
|
|
|
|
### Configuration
|
|
|
|
Prometheus uses Histogram based grouping for monitoring latencies. The default
|
|
buckets are:
|
|
|
|
```python
|
|
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/>
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
PROMETHEUS_METRIC_NAMESPACE = "project"
|
|
```
|
|
|
|
This will prefix all metrics with `project_` word like this:
|
|
|
|
```text
|
|
project_django_http_requests_total_by_method_total{method="GET"} 1.0
|
|
```
|
|
|
|
### Monitoring your databases
|
|
|
|
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`.
|
|
|
|
```python
|
|
DATABASES = {
|
|
'default': {
|
|
'ENGINE': 'django_prometheus.db.backends.sqlite3',
|
|
'NAME': os.path.join(BASE_DIR, 'db.sqlite3'),
|
|
},
|
|
}
|
|
```
|
|
|
|
### Monitoring your caches
|
|
|
|
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`.
|
|
|
|
```python
|
|
CACHES = {
|
|
'default': {
|
|
'BACKEND': 'django_prometheus.cache.backends.filebased.FileBasedCache',
|
|
'LOCATION': '/var/tmp/django_cache',
|
|
}
|
|
}
|
|
```
|
|
|
|
### Monitoring your models
|
|
|
|
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:
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
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.
|
|
|
|
### Monitoring and aggregating the metrics
|
|
|
|
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:
|
|
|
|
|
|
|
|
## Adding your own metrics
|
|
|
|
You can add application-level metrics in your code by using
|
|
[prometheus_client](https://github.com/prometheus/client_python)
|
|
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](http://prometheus.io/docs/practices/instrumentation/)
|
|
and [naming](http://prometheus.io/docs/practices/naming/).
|
|
|
|
## Importing Django Prometheus using only local settings
|
|
|
|
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
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
ROOT_URLCONF = "graphite.urls_prometheus_wrapper"
|
|
```
|
|
|
|
## Adding custom labels to middleware (request/response) metrics
|
|
|
|
You can add application specific labels to metrics reported by the django-prometheus middleware.
|
|
This involves extending the classes defined in middleware.py.
|
|
|
|
* Extend the Metrics class and override the `register_metric` method to add the application specific labels.
|
|
* Extend middleware classes, set the metrics_cls class attribute to the the extended metric class and override the label_metric method to attach custom metrics.
|
|
|
|
See implementation example in [the test app](django_prometheus/tests/end2end/testapp/test_middleware_custom_labels.py#L19-L46)
|