Prometheus metrics exporter for Starlette applications.
Project description
starlette_exporter
Prometheus exporter for Starlette and FastAPI
starlette_exporter collects basic metrics for Starlette and FastAPI based applications:
- starlette_requests_total: a counter representing the total requests
- starlette_request_duration_seconds: a histogram representing the distribution of request response times
- starlette_requests_in_progress: a gauge that keeps track of how many concurrent requests are being processed
Metrics include labels for the HTTP method, the path, and the response status code.
starlette_requests_total{method="GET",path="/",status_code="200"} 1.0
starlette_request_duration_seconds_bucket{le="0.01",method="GET",path="/",status_code="200"} 1.0
Use the HTTP handler handle_metrics
at path /metrics
to expose a metrics endpoint to Prometheus.
Table of Contents
Usage
pip install starlette_exporter
Starlette
from starlette.applications import Starlette
from starlette_exporter import PrometheusMiddleware, handle_metrics
app = Starlette()
app.add_middleware(PrometheusMiddleware)
app.add_route("/metrics", handle_metrics)
...
FastAPI
from fastapi import FastAPI
from starlette_exporter import PrometheusMiddleware, handle_metrics
app = FastAPI()
app.add_middleware(PrometheusMiddleware)
app.add_route("/metrics", handle_metrics)
...
Options
app_name
: Sets the value of the app_name
label for exported metrics (default: starlette
).
prefix
: Sets the prefix of the exported metric names (default: starlette
).
group_paths
: setting this to True
will populate the path label using named parameters (if any) in the router path, e.g. /api/v1/items/{item_id}
. This will group requests together by endpoint (regardless of the value of item_id
). This option may come with a performance hit for larger routers. Default is False
, which will result in separate metrics for different URLs (e.g., /api/v1/items/42
, /api/v1/items/43
, etc.).
filter_unhandled_paths
: setting this to True
will cause the middleware to ignore requests with unhandled paths (in other words, 404 errors). This helps prevent filling up the metrics with 404 errors and/or intentially bad requests. Default is False
.
buckets
: accepts an optional list of numbers to use as histogram buckets. The default value is None
, which will cause the library to fall back on the Prometheus defaults (currently [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]
).
skip_paths
: accepts an optional list of paths that will not collect metrics. The default value is None
, which will cause the library to collect metrics on every requested path. This option is useful to avoid collecting metrics on health check, readiness or liveness probe endpoints.
Example:
app.add_middleware(PrometheusMiddleware, app_name="hello_world", group_paths=True, prefix='myapp', buckets=[0.1, 0.25, 0.5], skip_paths=['/health'])
Custom Metrics
starlette_exporter will export all the prometheus metrics from the process, so custom metrics can be created by using the prometheus_client API.
Example:
from prometheus_client import Counter
from starlette.responses import RedirectResponse
REDIRECT_COUNT = Counter("redirect_total", "Count of redirects", ["redirected_from"])
async def some_view(request):
REDIRECT_COUNT.labels("some_view").inc()
return RedirectResponse(url="https://example.com", status_code=302)
The new metric will now be included in the the /metrics
endpoint output:
...
redirect_total{redirected_from="some_view"} 2.0
...
Multiprocess mode (gunicorn deployments)
Running starlette_exporter in a multiprocess deployment (e.g. with gunicorn) will need the PROMETHEUS_MULTIPROC_DIR
env variable set, as well as extra gunicorn config.
For more information, see the Prometheus Python client documentation.
Developing
git clone https://github.com/stephenhillier/starlette_exporter
cd starlette_exporter
pytest tests
License
Code released under the Apache License, Version 2.0.
Dependencies
https://github.com/prometheus/client_python
https://github.com/encode/starlette
Credits
Starlette - https://github.com/encode/starlette
FastAPI - https://github.com/tiangolo/fastapi
Flask exporter - https://github.com/rycus86/prometheus_flask_exporter
Alternate Starlette exporter - https://github.com/perdy/starlette-prometheus
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for starlette_exporter-0.11.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | e7f76e1e7b8d0539f2d9895769e86b5ea9f452191a580f4e5a79fb8addef212b |
|
MD5 | d04079d8082390b2771fd9c593536365 |
|
BLAKE2b-256 | f0ce51d7e4b8f11009e0f30024c8e97a2b739fd8aeeeec2aa5bbea3eda8c317f |
Hashes for starlette_exporter-0.11.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 57c74134732f995dbc46b3c90d886cf0e6067d216ec6aa511dad35b8e063a2d5 |
|
MD5 | 6e68eb38cd74a5987e0ae47e1aa86ea0 |
|
BLAKE2b-256 | df57d8f775da8d2cd3edd3da15923f800e15963eb6e60a6080a182efea3762c4 |