• from_response_header: a new helper function for adding metric series labels based on HTTP response header values. See the README for more info. Example:

from starlette_exporter import PrometheusMiddleware, from_header, from_response_header

app.add_middleware(
  PrometheusMiddleware,
  labels={
      "cache": from_response_header("X-FastAPI-Cache", allowed_values=("hit", "miss"))
    }
)

Feedback and bug reports welcome - please open an issue.

You can now access the Request object from an exemplars callback. Example:

def exemplars(r: Request):
    return {"trace_id": r.headers.get("x-trace-id", "")}

app.add_middleware(
  PrometheusMiddleware,
  exemplars=exemplars
)

This will allow you to use header values as exemplars. Note that if you want to use OpenTelemetry traces with exemplars, see this example.

Thank you @backbord (#92)!

the skip_paths option now accepts regular expressions. #89 @bunny-therapist

Notice: most usage of skip_paths should be compatible with regex. If your usage is affected by this change, please update to a regular expression or file an issue.

Support for uvicorn v0.26.0's updated root_path behavior (see Kludex/uvicorn#2213). @dolfinus

Changes:

• Fix for handling for root_path (see #75 and #81) @dolfinus
• Minimum Starlette version now 0.35 and dropped support for Python 3.7 #83 @dolfinus

Breaking changes:

• group_paths and filter_unhandled_paths now default to True. See #78 and #79

Add FutureWarnings for group_paths and filter_unhandled_paths indicating that the default values will change next release (see #79 )

Changes for v0.17.0:

• include headers in app scope when matching request path #76 @evstratbg
• callback functions used to populate labels can now be async #70 @YiuRULE

Potentially impactful changes:

• the status code reported for client disconnections will now be 499 instead of 500 #77 @Alexander-N
  • note: some users may notice a new status_code=499 timeseries if a client disconnects before response is written (previously this would be erroneously reported as a 500 status).

v0.16.0

skip_methods option

This releases adds the skip_methods option, which allows you to avoid recording metrics for any requests with the specified methods. Use this if you do not want certain types of requests (e.g. OPTIONS) to appear in your metrics. The argument should be a list of strings corresponding to method names.

Usage:

app.add_middleware(
  PrometheusMiddleware,
  app_name="hello_world",
  skip_methods=['OPTIONS']
)

Credit to @adinsoon for this new feature.

Bug fixes

Fix for Module "starlette_exporter" does not explicitly export attribute "PrometheusMiddleware" (#63) @poofeg

README fixes: fixed references to the handle_metrics function in example (@elatomo ), and fixed the exemplars example (@camerondavison)

This small release updates the type hint for the buckets param from List to Sequence to match the type hint in the Prometheus client library. Credit to @sbrandtb (#59)

Adds exemplar support for the request counter and request latency histograms. This is intended to be used with tracing (e.g. OpenTelemetry).

You must supply your own callback function that returns a trace id to be used as the exemplar. PRs welcome with an example, or a simple OpenTelemetry-based helper function.

Example:

# must use `handle_openmetrics` instead of `handle_metrics` for exemplars to appear in /metrics output.
from starlette_exporter import PrometheusMiddleware, handle_openmetrics

app.add_middleware(
  PrometheusMiddleware,
  exemplars={"trace_id": get_trace_id}  # supply your own callback function
)

app.add_route("/metrics", handle_openmetrics)

Exemplars are only supported by the openmetrics-text exposition format. A new handle_openmetrics handler function is provided (see above example).

For more information, see the Grafana exemplar documentation.

This release adds a labels argument to PrometheusMiddleware that accepts a dict of labels/values that will be added to all metrics.

Each label's value can be either a static value or, optionally, a callback function that takes the Request instance as its argument and returns a string.

Example:

app.add_middleware(
  PrometheusMiddleware,
  labels={
     "service": "api",
     "env": os.getenv("ENV"),
     "my_header": lambda r: r.headers.get("X-My-Header")
    }
)

Reminder: always evaluate the cardinality of sets of labels before using them, and do not use user-supplied values (e.g. untrusted headers) or unconstrained values to populate labels. See this for more information: https://grafana.com/blog/2022/02/15/what-are-cardinality-spikes-and-why-do-they-matter/

Thank you to @intelroman for helping contribute to this feature.

Request and response body sizes

This release adds new optional request and response body size metrics. They will track the size, in bytes, of request and response bodies received and returned by all endpoints. To enable them, use the optional_metrics option:

from starlette_exporter.optional_metrics import response_body_size, request_body_size

app.add_middleware(PrometheusMiddleware, optional_metrics=[response_body_size, request_body_size])

Thank you to @intelroman for contributing this feature.

better support for http.HTTPStatus

There is now an option always_use_int_status to convert http.HTTPStatus codes to integers for the status_code metric label. To ensure no breakage for users already working around this behavior, it defaults to False.

app.add_middleware(PrometheusMiddleware, always_use_int_status=True)

credit to @jgould22 for reporting and fixing this issue.

Adds support for FastAPI's root_path setting, intended for use behind a proxy (for more information about root_path, see the FastAPI docs: https://fastapi.tiangolo.com/advanced/behind-a-proxy/). #39

Thanks to @Bear1110 for reporting the bug!

v0.11.0 adds a new option skip_paths that accepts a list of paths that should be ignored when collecting metrics. This is useful if you don't want to track metrics for health check endpoints or the /metrics endpoint.

Example:

app.add_middleware(PrometheusMiddleware, skip_paths=['/health'])  #  no metrics will be collected for `/health`

Credit to @fdaines for contributing this new feature.

v0.10.0 adds a new default metric requests_in_progress.

This metric is a gauge that keeps track of the number of concurrent requests that your application is processing.

Thanks to @scotgopal for contributing this feature! :tada:

v0.9.0 now supports mounted routes when using group_paths=True and/or filter_unhandled_paths=True. Metrics for these routes will now be properly exported with the correct path labels.

Thanks to @axyjo for the report (#21)!

This update adds support for the uppercase version of the PROMETHEUS_MULTIPROC_DIR env variable, to address a deprecation warning when using the lowercase version. See Prometheus client_python code.

Thanks to @lqhuang. (#20)

v0.8.1 addresses an issue where the end time may not be recorded in some cases. This fix ensures the end time is always recorded before the request duration metric is observed. (#18)

The request duration metric now correctly reports the time between request and response, even if a background task has been kicked off by the request handler. (#16, #17)

If you need a metric that captures the processing time including background tasks, please post an issue and it can be added.

This release grants the option to ignore unhandled paths. Use this option to prevent 404 errors from filling up the metrics. See #14.

From README:

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.

example:

app.add_middleware(PrometheusMiddleware,
                   filter_unhandled_paths=True, group_paths=True)

Thank you to @mwek for contributing this feature (#15).

This release adds a buckets option, which accepts a list of numbers to use as buckets for the histogram. If not set (or set to None), the Prometheus default will be used. (credit to @RyBo)

This release converts the starlette_exporter PrometheusMiddleware to be an ASGI middleware with a __call__ method instead of subclassing BaseHTTPMiddleware (add768e20b27540b04397e621c394f2a1703a691). This fixes an issue that prevents background tasks from being used with the middleware. See https://github.com/encode/starlette/issues/919#issuecomment-672908610 for more information on the BaseHTTPMiddleware issue.

Other improvements:

• added prefix option, which allows developers to change the prefix of the exported metrics (previously, the metrics would always be prefixed starlette_, which remains the default). See issue #3. (b53bb3fcca9087c7ed204bd325d5eb519e5587e9)
• switched to time.perf_counter() instead of time.time() for request times. (381a4bef264efd88a76ea32d3dfadb346696c3dd)

Credit for the improvements in this release goes to @rcoup.

Fixes multiprocess registry (#5 )

The application name can now be specified when creating the middleware:

app.add_middleware(PrometheusMiddleware, app_name="my_app")

This allows filtering metrics by application if you have several FastAPI apps exporting metrics to the same Prometheus service.

Author: @paweldudzinski

This version provides a group_paths option to the PrometheusMiddleware constructor that will cause all metrics to be grouped by their router path.

This means that requests to endpoints with path variables like /api/v1/shop/1234 and /api/v1/shop/75 will appear in the metrics as /api/v1/shop/{item_id}. This might be helpful if you want metrics organized by HTTP path but don't want them broken down by each individual item in a collection.

Initial release of starlette_exporter with request counter and request duration histogram. Both metrics include the HTTP method, path, and status code. Successful requests/errors can be separated by status code.