Get Started to monitor your Django application with Prometheus & Grafana in 10 minutes

This 10-minutes guide will help you easily get started with monitoring a Django application using Prometheus and Grafana. You will be able to display this monitoring dashboard :

Example of a Dashboard that display API Responses Status from a Django App

Prometheus is a monitoring solution that collects metrics from client servers. It is an open-source project started at SoundCloud by ex-Googlers that wanted to monitor a highly dynamical container environment. Since its inception in 2012, many companies and organizations have adopted Prometheus.

Grafana is a web-based multi-source graph interface that is able to display data from Prometheus or other sources. It has very advanced presentation capabilities, especially via configurable dashboards.

Why did I choose to monitor my Django App using Prometheus in a Grafana Dashboard ?

Two months ago, I added a new security rule (web restriction) in my application on the production environment. This web restriction has been tested in the UAT (User Acceptance Test) environment and didn’t provoke any issue. Once deployed, in the production environment, I went to our website and everything seemed correct. But a few hours later, a user was blocked in the website and we noticed that some API endpoints were returning an error “503 Server Unavailable” because of this new web restriction.
At this time, we didn’t use a monitoring solution for our application, and we didn’t see that these endpoints were not responding until a user told us that he was blocked.
When you know that google makes approximately $15.34 million USD revenue per hour you can imagine that 1 minute without detecting a downtime can cost a lot !

How does Prometheus work ?

As a monitoring service, Prometheus servers monitor a particular thing.
That thing could be anything: it could be an entire Linux server, a stand-alone Apache server, a single process, a database service or some other system unit that you want to monitor.
In Prometheus terms, we call the main monitoring service the Prometheus Server and the things that Prometheus monitors are called Targets.

Monitoring an application using Prometheus and Grafana

To monitor your services using Prometheus, your services need to expose a Prometheus endpoint. This endpoint is a route that exposes a list of metrics and the current value of the metrics.

Prometheus includes a collection of client libraries which allow metrics to be published so they can then be collected (or “scraped” using Prometheus’ terminology) by the metrics server.

Prometheus maintains 4 official Prometheus metrics libraries written in Go, Java / Scala, Python, and Ruby.

In the Prometheus UI, you can write queries in the PromQL language to extract metric information.

We use Grafana, the visualization layer, as the 3rd component to visualize metrics stored in the Prometheus time-series database.

Instead of writing PromQL queries directly into the Prometheus server, you use Grafana UI boards to query metrics from Prometheus server and visualize them in the Grafana Dashboard as a whole, as we will see it in action shortly.

Now, let’s get started.

Step 1 : Run your Prometheus and Grafana server

Before running a Prometheus server, you must have Docker installed. I am using Docker images in this tutorial but you can run your server other ways.

A Docker container image is a lightweight, standalone, executable package of software that includes everything needed to run an application: code, runtime, system tools, system libraries and settings. For more information about Docker click here : https://docs.docker.com/engine/docker-overview/

The easiest way to run a Prometheus server is to use the docker image of Prometheus
The image can be pulled from docker hub right here and is maintained by Prometheus community : https://hub.docker.com/r/prom/prometheus/

In order to run a Grafana server, you can use the following image:
grafana/grafana:6.5.2

Then you have to write a docker-compose file that contains the configuration of your two images.

docker-compose.monitoring.yml

version: ‘3.6’
services:
prometheus:
 image: prom/prometheus:v2.14.0
 volumes:
 — ./prometheus/:/etc/prometheus/
 command:
 — ‘ — config.file=/etc/prometheus/prometheus.yml’
 ports:
 — 9090:9090
grafana:
 image: grafana/grafana:6.5.2
 ports:
 — 3060:3000

Step 2: Configure your Prometheus server

In order to run a Prometheus instance you need to create a prometheus.yml file.

I have added this file to the folder : ./prometheus/ that is used in the docker-compose.monitoring.yml file

prometheus.yml

global:
 scrape_interval: 15s
 evaluation_interval: 15s
rule_files:
 # — “first.rules”
 # — “second.rules”
scrape_configs:
 — job_name: monitoring
 static_configs:
 — targets:
    — host.docker.internal

host.docker.internalresolves to the internal IP address used by the host. You can found more information here : https://docs.docker.com/docker-for-windows/networking
This url is used for development purposes. If you need to target a deployed application, in the prometheus.yml file that will be used by your prometheus server in production, you can change host.docker.internal by the url you want to target such as your-prod-application.com

In order to run Prometheus and Grafana server, run this command in your terminal :

$ docker-compose -f docker-compose.monitoring.yml up -d

You should see the following screen in the address when you go to localhost:9090

Prometheus targeting a /metrics endpoint

At this moment, this endpoint /metrics doesn’t exists yet that’s why the target returns a 404 error. We will see in the next step how to create it in our Django application

Step 3: Add metrics to monitor your Django App

The Prometheus community has created many third-party libraries that you can use to get metrics from different stack. (Nodejs, Spring-Boot, Django etc..)

Django-prometheus is an open-source django app that Export Django monitoring metrics for Prometheus.io : https://github.com/korfuri/django-prometheus/

Install django-prometheus in your django project :

pip install django-prometheus

In your settings add the app :

settings.py

BASE_INSTALLED_APPS = [
 ...
 “django_prometheus”,
]
MIDDLEWARE = [
 “django_prometheus.middleware.PrometheusBeforeMiddleware”,
...
 “django_prometheus.middleware.PrometheusAfterMiddleware”,
]

Then add django_prometheus urls to your application endpoints. It will add a new endpoint which is localhost/metrics.

urls.py

url(“”, include(“django_prometheus.urls”)),

Now you should see that your target is “UP” in your prometheus targets : http://localhost:9090/targets

Prometheus targeting a /metrics valid endpoint

Step 4 : Create your Grafana Dashboard

Now that you have an active Prometheus target, you can create an amazing dashboard using Grafana.

Go to your Grafana instance : http://localhost:3060

Then add your Prometheus instance as a Data Source. (As explained in the GIF below)

Go to the Configuration Left Panel and click on Data Sources , then click on Add a Data source and choose a Name and an enter the url of your data source.

Enter the url of your Prometheus instance.
Here, it is http://host.docker.internal:9090 because it is running in a docker container.

Add a Data Source in Grafana

Once it is done, you can now create a new Dashboard :

1. Click the graph title, then click “Edit”.
2. Under the “Metrics” tab, select your Prometheus data source (bottom right).
3. Enter any Prometheus expression into the “Query” field, while using the “Metric” field to lookup metrics via autocompletion.

It is possible to filter these time series further by appending a set of labels to match in curly braces ({}).

Example of a Prometheus Query in PromQL

The Grafana community is very active and offers dashboards for download, many of which are based on Prometheus data. A very fast way to introduce specific screens for standard components.

Conclusion

As seen together, Grafana allows developers to add their metrics through Prometheus Data Source and measure what is valuable to them: http codes, latency per page, application deployments…

In order to do so you have to provide an endpoint that show the metrics you want using a third-party library. Then you need to connect your Prometheus instance to that endpoint using the configuration file: prometheus.yml.

Once this part is done, you have to add a data source to your Grafana Dashboard giving the url of your Prometheus instance.

You should now be able to set a monitoring Dashboard for your Django App using Prometheus and Grafana

Going further

As you may have noticed, we have run our Grafana and Prometheus Server locally. Once you are able to run the Dashboard you want locally, you can be ready to deploy your Prometheus and Grafana docker images using the solution of your choice.

I hope this 10-minutes guide will help you easily getting started with Prometheus and Grafana monitoring a Django App. Here are a few resources if you want to go the extra mile:

Client libraries

Deploying Your First Docker Container | Docker | Katacoda

What is a Container? | Docker

Bibliography

Prometheus — Monitoring system & time series database

Grafana: The open observability platform