{"id":3818,"library":"starlette-exporter","title":"Prometheus Metrics Exporter for Starlette","description":"starlette-exporter is a Python library that provides Prometheus metrics for Starlette applications, enabling easy monitoring of request rates, durations, and response statuses. It integrates as a middleware, automatically exposing a `/metrics` endpoint. The current version is 0.23.0, and it follows a regular release cadence with new features and improvements.","status":"active","version":"0.23.0","language":"en","source_language":"en","source_url":"https://github.com/stephenhillier/starlette_exporter","tags":["starlette","prometheus","metrics","monitoring","middleware","fastapi"],"install":[{"cmd":"pip install starlette-exporter","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for the Starlette application framework.","package":"starlette","optional":false},{"reason":"Core library for Prometheus client functionality.","package":"prometheus_client","optional":false}],"imports":[{"symbol":"PrometheusMiddleware","correct":"from starlette_exporter import PrometheusMiddleware"},{"note":"Used to expose the /metrics endpoint in your Starlette routes.","symbol":"handle_metrics","correct":"from starlette_exporter import handle_metrics"},{"note":"Helper for adding metric series labels from request headers.","symbol":"from_header","correct":"from starlette_exporter import from_header"},{"note":"Helper for adding metric series labels from response headers (added in v0.22.0).","symbol":"from_response_header","correct":"from starlette_exporter import from_response_header"}],"quickstart":{"code":"from starlette.applications import Starlette\nfrom starlette.responses import PlainTextResponse\nfrom starlette.routing import Route\nfrom starlette_exporter import PrometheusMiddleware, handle_metrics\nimport uvicorn\n\nasync def homepage(request):\n    return PlainTextResponse(\"Hello, world!\")\n\nasync def user_page(request):\n    username = request.path_params.get(\"username\")\n    return PlainTextResponse(f\"Hello, {username}!\")\n\nroutes = [\n    Route(\"/\", homepage),\n    Route(\"/users/{username}\", user_page),\n    Route(\"/metrics\", handle_metrics) # Expose the metrics endpoint\n]\n\napp = Starlette(routes=routes)\napp.add_middleware(\n    PrometheusMiddleware,\n    app_name=\"my_starlette_app\",\n    group_paths=True, # Recommended for clean metrics paths\n    # labels={\"environment\": \"staging\"}, # Example custom labels\n    # group_unhandled_paths=True # New in v0.23.0 to group 404s under '__unknown__'\n)\n\n# To run this application:\n# 1. Save the code as `main.py`\n# 2. Install dependencies: `pip install uvicorn starlette starlette-exporter prometheus_client`\n# 3. Run: `uvicorn main:app --reload`\n# Then, access metrics at http://127.0.0.1:8000/metrics\n# And application routes at http://127.0.0.1:8000/ or http://127.0.0.1:8000/users/alice","lang":"python","description":"This quickstart demonstrates how to set up `starlette-exporter` with a basic Starlette application. It defines two simple routes and exposes a `/metrics` endpoint using `handle_metrics`. The `PrometheusMiddleware` is added to the application, configuring it to group paths for cleaner metrics. To run, save the code, install dependencies, and execute with uvicorn."},"warnings":[{"fix":"If your application relied on the previous behavior without explicitly setting these options, you must now explicitly set `group_paths=False` or `filter_unhandled_paths=False` in the `PrometheusMiddleware` constructor to revert to the old defaults.","message":"The default values for `group_paths` and `filter_unhandled_paths` changed from `False` to `True`.","severity":"breaking","affected_versions":">=0.18.0"},{"fix":"Ensure your project uses Starlette 0.35.0 or newer and Python 3.8 or newer. Upgrade your environment and dependencies accordingly.","message":"Minimum supported Starlette version increased to 0.35, and Python 3.7 support was dropped.","severity":"breaking","affected_versions":">=0.18.0"},{"fix":"Review existing `skip_paths` configurations. If you intended exact string matches, ensure they are properly escaped (e.g., `['/my/path/']` might need `['/my/path/?']` if `?` was previously treated as a literal but is now a regex special character).","message":"The `skip_paths` option now accepts regular expressions, which can subtly change behavior if existing exact path strings were coincidentally valid regex patterns.","severity":"gotcha","affected_versions":">=0.20.0"},{"fix":"Update any monitoring alerts or dashboards that specifically look for `500` status codes for client disconnections to include `499`.","message":"Client disconnections (before a response is sent) are now reported with status code `499` instead of `500`.","severity":"gotcha","affected_versions":">=0.17.0"},{"fix":"To get metrics for requests against unhandled paths, set `group_unhandled_paths=True` in the `PrometheusMiddleware` constructor. This option overrides `filter_unhandled_paths`.","message":"Unhandled paths (404s) can now be grouped under a special `__unknown__` label, but this feature requires explicit enablement.","severity":"gotcha","affected_versions":">=0.23.0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}