flask-prometheus-metrics 1.0.0
Prometheus Metrics for Flask Web App
License: MIT
Requires Python: >=3.6

## Flask Prometheus Metrics ##

[![Build Status](https://travis-ci.org/pilosus/flask_prometheus_metrics.svg?branch=master)](https://travis-ci.org/pilosus/flask_prometheus_metrics)
[![Test Coverage](https://api.codeclimate.com/v1/badges/6b414e49d4f9302fe460/test_coverage)](https://codeclimate.com/github/pilosus/flask_prometheus_metrics/test_coverage)
[![Maintainability](https://api.codeclimate.com/v1/badges/6b414e49d4f9302fe460/maintainability)](https://codeclimate.com/github/pilosus/flask_prometheus_metrics/maintainability)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/python/black)

Prometheus metrics exporter for Flask web applications.

``flask_prometheus_metrics`` uses official [Prometheus Python Client](https://github.com/prometheus/client_python)
providing basic metrics about process resource usage, app's requests metrics and information.


## Installation ##

```bash
pip install -U flask_prometheus_metrics
```

You will need ``Flask`` to run examples below:

```bash
pip install -U 'flask_prometheus_metrics[flask]'
```

## Usage ##

Run the following minimal example in Python shell:

```python
from flask import Flask
from prometheus_client import make_wsgi_app
from werkzeug.middleware.dispatcher import DispatcherMiddleware
from werkzeug.serving import run_simple
from flask_prometheus_metrics import register_metrics

app = Flask(__name__)

@app.route("/")
def index():
    return "Test"

# provide app's version and deploy environment/config name to set a gauge metric
register_metrics(app, app_version="v0.1.2", app_config="staging")

# Plug metrics WSGI app to your main app with dispatcher
dispatcher = DispatcherMiddleware(app.wsgi_app, {"/metrics": make_wsgi_app()})

run_simple(hostname="localhost", port=5000, application=dispatcher)
```

Then go over ``http://localhost:5000/``, refresh page a few times and check your
app's metrics at ``http://localhost:5000/metrics``.

See also [example.py](https://github.com/pilosus/flask_prometheus_metrics/blob/master/flask_prometheus_metrics/example.py)
for more elaborate example of library usage in real Flask applications.

## Metrics ##

``flask_prometheus_metrics`` exposes the following application metrics:

- ``app_request_latency_seconds`` (histogram) - Application request latency
- ``app_request_count_total`` (counter) - application request count
- ``app_version_info`` (gauge) - application version

Library also provides some metrics about a Python interpreter used and process
resource usage:

- ``python_gc_objects_collected_total`` (counter) - objects collected during gc
- ``python_gc_objects_uncollectable_total`` (counter) -  uncollectable object found during GC
- ``python_gc_collections_total`` (counter) - number of times this generation was collected
- ``python_info`` (gauge) - Python platform information
- ``process_virtual_memory_bytes`` (gauge) - virtual memory size in bytes
- ``process_resident_memory_bytes`` (gauge) - resident memory size in bytes
- ``process_start_time_seconds`` (gauge) - start time of the process since unix epoch in seconds
- ``process_cpu_seconds_total`` (counter) - total user and system CPU time spent in seconds
- ``process_open_fds`` (gauge) - number of open file descriptors
- ``process_max_fds`` (gauge) - maximum number of open file descriptors

## Grafana dashboard ##

The metrics exported by ``flask_prometheus_metrics`` can be scraped by
[Prometheus](https://prometheus.io/) monitoring system and then visualized in
[Grafana](https://grafana.com/).

You can download Grafana dashboard crafted specifically for the ``flask_prometheus_metrics``
default metrics [here](https://github.com/pilosus/prometheus-client-python-app-grafana-dashboard/).

[![Grafana visualisation](https://raw.githubusercontent.com/pilosus/prometheus-client-python-app-grafana-dashboard/master/docs/flask-app-2.png)](https://github.com/pilosus/prometheus-client-python-app-grafana-dashboard/)


## Testing ##

When testing Flask application with ``DispatcherMiddleware`` (see Usage example above)
you may want to use a [little hack](https://github.com/pilosus/flask_prometheus_metrics/blob/master/tests/conftest.py#L22)
in order to make Flask's ``test_client()`` work properly.


## History ##

### v1.0.0 (2019-06-06) ###
* Library is ready for production
* Minor setup.py fixes (#12)


### v0.7.0 (2019-06-06) ###
* README.md adjusted to work both on GitHub and PyPi (#11)


### v0.6.2 (2019-06-06) ###
* Codeclimate integration added


### v0.6.1 (2019-06-06) ###
* Travis CI configuration fixed


### v0.6.0 (2019-06-06) ###
* README and CHANGELOG as long description added


### v0.5.0 (2019-06-06) ###
* CHANGELOG.md added


### v0.4.0 (2019-06-06)  ###
* Import simplified for metrics registration function


### v0.3.1 (2019-06-05) ###
* Minor CI config fix


### v0.3.0 (2019-06-05) ###
* Dependencies versions and safety checks added


### v0.2.1 (2019-06-01) ###
* Update installation example in README


### v0.2.0 (2019-06-01) ###
* README added, some code refactoring


### v0.1.2 (2019-06-01) ###
* Version bumped


### v0.1.1 (2019-06-01) ###
* Package versioning fix


### v0.1.0 (2019-06-01) ###
* MVP