Registry /
observability / prometheus-flask-exporter
Install & Compatibility
Where this runs
tested against v0.23.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.562s · 23.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.3s · import 0.518s · 24MB
22MB installed
● package 22MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PrometheusMetrics
✓ from prometheus_flask_exporter import PrometheusMetrics
Flask
✓ from flask import Flask
request
✓ from flask import request
Required for custom label functions that inspect the request object.
Initializes a Flask application with Prometheus metrics. Default HTTP request metrics (duration, total, exceptions) are exposed on the '/metrics' endpoint. Custom metrics like 'in_progress' gauge can be added to specific routes using decorators. To view metrics, run the app and navigate to '/metrics' after making some requests.
from flask import Flask, request
from prometheus_flask_exporter import PrometheusMetrics
import os
app = Flask(__name__)
metrics = PrometheusMetrics(app)
# Optional: Add static info about the app
metrics.info('app_info', 'Application info', version='1.0.0')
@app.route('/')
def main():
return 'Hello World!'
@app.route('/long-running')
@metrics.gauge('in_progress', 'Long running requests in progress')
def long_running():
import time
time.sleep(2)
return 'Done!'
# Run the app directly or using a WSGI server like Gunicorn
if __name__ == '__main__':
# Example: Access http://localhost:5000/ and http://localhost:5000/metrics
app.run(host='0.0.0.0', port=5000)
Debug
Known issues
deprecatedThe `group_by_endpoint` argument in `PrometheusMetrics` is deprecated.fixUse the `group_by` argument instead, which offers more flexible grouping options. For example, `PrometheusMetrics(app, group_by='endpoint')`.
affects: <= 0.3.x
deprecatedThe `static_labels` argument in `PrometheusMetrics` is deprecated.fixUse the `default_labels` argument instead, which supports both static and dynamic label values.
affects: <= 0.14.x
gotchaRunning Flask with `debug=True` (live-reloading) might not reflect metrics for the latest code unless the `DEBUG_METRICS` environment variable is set. Additionally, `PrometheusMetrics.start_http_server()` is not expected to work reliably in this debug scenario.fixFor accurate metrics during development with live-reloading, set the `DEBUG_METRICS` environment variable. For production, disable debug mode and use a WSGI server.
affects: All versions >= 0.5.1
gotchaCarefully manage metric label cardinality to avoid 'cardinality explosion', which can lead to excessive memory usage and Prometheus server crashes.fixAvoid using high-cardinality values (e.g., user IDs, full dynamic URL paths) as labels. Aggregate or generalize label values (e.g., `/user/{id}` instead of `/user/123`). affects: All versions
breakingPast versions experienced issues due to breaking changes in the underlying `prometheus_client` library's `exposition` module (`choose_encoder`).fixAlways pin the `prometheus_client` dependency to a known compatible version in your `requirements.txt` or `pyproject.toml` to prevent unexpected breakage during upgrades. Ensure `prometheus-flask-exporter` is also kept updated to versions that explicitly support newer `prometheus_client` releases.
affects: Around `prometheus_client` 0.14.0, specifically `prometheus-flask-exporter` versions that had unversioned `prometheus_client` dependencies.
gotchaReports of memory leaks have been observed in specific pull-based Prometheus configurations when custom decorators for latency measurement are used.fixMonitor memory usage closely in production. If a leak is suspected, review custom metric decorators, ensure proper resource cleanup, and consult `prometheus_flask_exporter` or `prometheus_client` issue trackers.
affects: Undetermined; reported in some production setups.
Errors
Common errors & fixes
404 Not Found (on /metrics endpoint)
The `/metrics` endpoint is not automatically registered or is not accessible due to configuration issues, such as running Flask in debug mode or incorrect initialization.
fixEnsure `PrometheusMetrics` is correctly initialized with your Flask app and that Flask's debug mode is set to `False` in production or use the `DEBUG_METRICS` environment variable for development. You don't need to manually create a `/metrics` route.
The group_by_endpoint argument is deprecated since 0.4.0, please use the new group_by argument.
You are using an outdated argument `group_by_endpoint` which has been replaced by `group_by` in newer versions of the library.
fixReplace `group_by_endpoint=True` with `group_by='endpoint'` or provide a custom function to the `group_by` argument. Similarly, replace `static_labels` with `default_labels`.
Metrics not showing up or 404 on /metrics with Flask debug=True
When Flask's `debug=True` is enabled, changes are live-reloaded, which prevents metrics from being accurately collected or exposed on the `/metrics` endpoint.
fixRun your Flask application with `debug=False` for proper metrics collection. Alternatively, for development, set the `DEBUG_METRICS` environment variable to get metrics for the latest reloaded code.
TypeError: labels needs to be a dictionary of {labelname: callable}
When defining custom metrics with labels, the `labels` argument must be a dictionary where keys are label names and values are callables (functions) that return the label's value, not static values directly.
fixProvide a callable function for each label value in the `labels` dictionary, for example: `labels={'status': lambda r: r.status_code}`. Upgrade
Version history
0.23.2latest on PyPI · released Mar 11, 2025
Audit
Dependencies
FlaskrequiredCore web framework being extended.
prometheus_clientrequiredUnderlying Prometheus client library for metric exposition.