Instrument your FastAPI with Prometheus metrics.
Major release with a single breaking change: Python 3.7 is not supported anymore. Beyond that, three improvements based on various pull requests.
Instrumentator now works without FastAPI. This is possible because every FastAPI app is also a Starlette app (but not the other way around). Or to be more specific: FastAPI uses Starlette for things like routing and middleware this package relies on. The change is backwards compatible, even type checkers like mypy should continue working. Thanks to @mvanderlee for proposing this in #280 and implementing it in #288.
Middleware also records duration without streaming in addition to the already existing total latency (i.e. the time consumed for streaming is not included in the duration value). The differentiation can be valuable as it shows the time to first byte.
This mode is opt-in and can be enabled / used in several ways: The Instrumentator() constructor, the metrics.default() closure, and the metrics.latency() closure now come with the flag should_exclude_streaming_duration. The attribute modified_duration_without_streaming has been added to the metrics.Info class. Instances of metrics.Info are passed to instrumentation functions, where the added value can be used to set metrics.
Thanks to @dosuken123 for proposing this in #291 and implementing it in #290.
Relaxed type of get_route_name() argument to HTTPConnection. This allows developers to use the get_route_name function for getting the name of websocket routes as well. Thanks to @pajowu for proposing and implementing this feature in #276.
method to metric http_request_duration_seconds from default metrics. Thanks to @alcidesmig for implementing this in #251.Small release with a small breaking change leading to a big version change following semantic versioning.
Breaking change only affects users that have custom instrumentations that access info.response.body, a feature introduced with 5.10.0 few weeks ago. See below for more information.
BREAKING: Disabled passing response body to instrumentation functions. Moved behind whitelist that is empty by default. Changes a feature introduced with 5.10.0. Only affects users that have custom instrumentations that access info.response.body.
Opt-in via new parameter body_handlers added to instrumentator constructor. Parameter takes list of pattern strings to match handlers. For old behavior, pass argument [r".*"] to match all handlers:
instrumentator = Instrumentator(body_handlers=[r".*"])
Motivation for change: Collecting body negatively impacts performance of responses with largish body.
Thanks to @bbeattie-phxlabs for raising this issue in #234 and implementing it in #233 / #238.
Minor release containing several fixes and a small enhancement. Fixes are related to multi process mode, a regression introduced with the previous release, and errors that started to occur with current versions of Starlette and FastAPI.
Ask or discuss anything quick about the release in the discussion #221.
add() method to accept an arbitrary number of instrumentation functions as arguments instead of a single one. Non-breaking change. Implemented in pull request #230.Fixed multi process mode in expose() method that handles the /metrics endpoint. Due to reusing the registry assigned to the instrumentator it could lead to duplicated metrics. Now the endpoint follows recommendation from Prometheus client library documentation. Also improved multi process unit tests. Closed issue #228 and #227. Fixed in pull request #229.
Fixed NameError and "Duplicated timeseries..." errors that started to occur with latest versions of Starlette / FastAPI in combination with multiple middlewares. Instrumentation closures are now optional and the instrumentator handles this accordingly. Thanks to @alexted and others for reporting errors. Thanks to @frankie567 for pointing out the change in Starlette. Related to pull request #153 and issue #214. Closed issue #219. Done in pull request #220.
Added missing registry parameter to remaining metrics functions. This enables passing custom registry to other metrics functions than default. Related to pull request #153. Closed issue #219. Done in pull request #220.
First release in several months. Includes new features and fixes from various contributors. Notable changes that might have an impact on existing setups is the automatic instrumentation of mounted apps and the deprecation of the lowercase prometheus_multiproc_dir environment variable.
Ask or discuss anything quick about the release in the discussion #221.
Added smart handling of mounted apps. Previously the URL handler logic did not handle mounted apps and always returned just the prefix in that case. Based on code from elastic/apm-agent-python licensed under the permissive BSD-3-Clause License. Thanks to @LordGaav for proposing this enhancement / fix and implementing it in #208. Related to issues #31 and #121.
Added optional parameters metric_namespace and metric_subsystem to instrument() method to configure namespace and subsystem for all metric names. Check the README.md for more information. Thanks to @phbernardes for proposing this enhancement and implementing it in #193.
Added passthrough of body to info.response. This enables metrics that work based on data in the body. Thanks to everyone who brought this up in #76 and to @HadilD for implementing it in #203.
Allowed passing a custom registry to be used instead of using the default one. This would be useful in particular when testing multiple FastAPI apps (e.g. microservices) in the same tests run. Note that there are issues with the current implementation in certain corner cases. Thanks to @tiangolo for for proposing this enhancement and implementing it in #153.
Environment variable used by should_respect_env_var (default ENABLE_METRICS) now accepts truthy values like 1 and true and not just True. Thanks to @chbndrhnns for proposing this enhancement in #27 and implementing it in #28.
Added support for asynchronous instrumentation functions. The add() method now accepts them in addition to "normal" functions and the instrumentator middleware will await them appropriately. Thanks to @AndreasPB for for proposing this enhancement and implementing it in #61. Thanks to @Skeen for contributing to the discussion.
Fixed status code in metric being "Hxx" when http.HTTPStatus enumeration is used in combination with grouping of status codes. Thanks to @Leem0sh and others for raising the issue in #190. Thanks to @nikstuckenbrock and @blag for fixing it in #192.
Fixed documentation in main README on how to use prometheus-fastapi-instrumentator with current versions of FastAPI. Related to issues #214 and #80. Thanks to @alfaro28 and @harochau.
prometheus_multiproc_dir and replaced it with PROMETHEUS_MULTIPROC_DIR. This matches the behavior of the Prometheus Python client library. This fixes #89 and #50. Thanks to all the people who brought this up. Thanks to @michaelusner for implementing the deprecation in #42 / #217.No bug fixes or new features. Just an important improvement of the documentation.
@app.on_event("startup") to prevent crashes on startup. Thanks to @mdczaplicki and others.This release fixes a small but annoying bug. Beyond that the release includes small internal improvements and bigger changes to CI/CD.
py.typed file to package to improve typing annotations (#137). Thanks to @mmaslowskicc for proposing and implementing this.Refactored the middleware to an ASGI implementation. Thanks to @Kludex and @adriangb. #139.