Exemplar support

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.

Custom labels

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.

Optional body size metrics, support for HTTPStatus

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.

Support for FastAPI root_path setting

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!

New option: skip_paths

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.

New metric: requests in progress

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! 🎉

Improved support for mounted routes

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)!

Support for uppercase PROMETHEUS_MULTIPROC_DIR

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)

Fix for duration metric - end time not recorded

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)

Fix for request durations with background tasks

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.