All notable changes to this project are documented in this file.
The format is based on Keep a Changelog, and adheres to Semantic Versioning.
Nothing.
7.0.0 / 2023-07-15
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, themetrics.default()
closure, and themetrics.latency()
closure now come with the flagshould_exclude_streaming_duration
. The attributemodified_duration_without_streaming
has been added to themetrics.Info
class. Instances ofmetrics.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 toHTTPConnection
. This allows developers to use theget_route_name
function for getting the name of websocket routes as well. Thanks to @pajowu for proposing and implementing this feature in #276.
- BREAKING: Dropped support for Python 3.7 which is has reached end-of-life.
6.1.0 / 2023-07-15
- Added label
method
to metrichttp_request_duration_seconds
from default metrics. Thanks to @alcidesmig for implementing this in #251.
6.0.0 / 2023-03-20
Small release with a small breaking change leading to an increase of the major version according to 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.
Ask or discuss anything quick about the release in the discussion #239.
-
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.
5.11.2 / 2023-03-19
- Fixed
info.response.body
in instrumentation functions being wrongfully empty if response is not streamed. Affects a feature that was introduced with release 5.10.0 few weeks ago. Closed issue #236 and implemented in pull request #237.
5.11.1 / 2023-03-11
- Improved typing hints and enabled stricter rules for MyPy. Thanks to @tomtom103 for implementing this in #231.
5.11.0 / 2023-03-08
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.
- Adjusted the
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.
5.10.0 / 2023-02-26
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
andmetric_subsystem
toinstrument()
method to configure namespace and subsystem for all metric names. Check theREADME.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 proposing this enhancement and implementing it in #153.
-
Environment variable used by
should_respect_env_var
(defaultENABLE_METRICS
) now accepts truthy values like1
andtrue
and not justTrue
. 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 proposing this enhancement and implementing it in #61. Thanks to @Skeen for contributing to the discussion.
- Licensed part of the project under the BSD-3-Clause License. This is due to code being used from a repo licensed under BSD-3-Clause (see the "Added" section). The default ISC License and the BSD-3-Clause License are both permissive. So there should be no user impact.
-
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.
- Deprecated environment variable
prometheus_multiproc_dir
and replaced it withPROMETHEUS_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.
5.9.1 / 2022-08-23
- Corrected documention on how to use package. Instrumentation should happen in
a function decorated with
@app.on_event("startup")
to prevent crashes on startup in certain situations. Done in #168. Thanks to @mdczaplicki and others.
5.9.0 / 2022-08-23
- Added
py.typed
file to package to improve typing annotations. Done in #137. Thanks to @mmaslowskicc for proposing and implementing this.
- Changed license from MIT to ISC, which is just like MIT but shorter.
- Coding style improvements. Replaced a few for loops with list comprehensions.
Defaulting an argument to
None
instead of an empty list. Done in #155. Thanks to @yezz123. - Several improvements to the documentation. Thanks to @jabertuhin, @frodrigo, and @murphp15.
- Removed print statement polluting logs. Done in #157. Thanks to @nikstuckenbrock and others.
5.8.2 / 2022-06-12
- Refactored the middleware to an ASGI implementation. Related to #139. Thanks to @Kludex and @adriangb for the proposal and implementation.
5.8.1 / 2022-05-03
- Fixed a regression that made the required FastAPI version too strict for no reason. Related to #136. Thanks to @graipher for raising this issue.
5.8.0 / 2022-05-01
- BREAKING: Dropped support for Python 3.6 which is has reached end-of-life.
5.7.1 / 2021-01-12
- Updated
prometheus-client
dependency version constraint^0.8.0
that only allows versions in the range[0.8.0, 0.9.0[
. This is not correct and leads to conflicts when you want to install the newest prometheus client library version and this package. Switched to explicit contraints to ensure this does not happen again.
5.7.0 / 2020-12-13
- Added passthrough of Kwargs to FastAPI route that exposes metrics.
5.6.0 / 2020-12-03
- Added parameter
tags
to methodexpose()
. Passthrough to FastAPI to support tagging. Related to #17. Thanks to @chisaipete for proposing this enhancement.
5.5.1 / 2020-11-13
- Fixed error "Duplicate mime type charset=utf-8 on Response Header". Done by
changing the way the content type header is set. Seems like when Starlette's
media_type
parameter is used to provide content type, the charset is appended again automatically even if it already is part ofContent-Type
. Thanks to @flobaader for raising this issue in #16.
5.5.0 / 2020-11-01
- Adjusted docstrings.
5.4.1 / 2020-10-22
- Fixed dependency regression introduced in 5.4.0 by pinning FastAPI dependency
to
fastapi = "0.38.1, <=1.0.0"
instead offastapi = ">=0.38.1, <=1.0.0"
. Thanks to @PaulFlanaganGenscape for raising this issue in #14.
5.4.0 / 2020-10-20
- Added new metric that monitors the number of requests in progress. Can be
configured to have the labels
handler
andmethod
. It can be activated withshould_instrument_requests_inprogress
and configured withinprogress_name
andinprogress_labels
.
5.3.1 / 2020-09-25
- Fixed
expose
method in the instrumentator ignoring theendpoint
argument and always creating the endpoint with on the/metrics
path. Variable was missing. Thanks to @funkybase for raising this issue in #9.
5.3.0 / 2020-09-09
- Added parameter
should_gzip
toexpose
method. It will check forgzip
in theAccepted-Encoding
header and gzip the metrics data. You can expect a reduction of around 90 % in bytes.
5.2.3 / 2020-09-03
- Improved
README.md
.
5.2.2 / 2020-09-03
- Improved
README.md
.
5.2.1 / 2020-08-27
- Fixed lack of error wrapping of a runtime error is raised inside the endpoint.
In addition this instrumentator assumed that
info.response
will always contain theheaders
attribute which is not the case if a runtime error is thrown. Now the metrics check if the response isNone
and that theheaders
attribute actually exists. Tests have been added as well. Thanks to @stepf for raising this issue in #7.
- Adjusted behavior Metrics
response_size
andcombined_size
no longer skip if content length is not found. Now the content length will default no zero bytes.
5.2.0 / 2020-08-22
- Added parameter
should_only_respect_2xx_for_highr
todefault
metrics. Allows you to only put successful requests into the high resolution bucket.
5.1.0 / 2020-08-19
- Added parameters to set namespace and subsystem to all available metrics.
5.0.0 / 2020-08-18
- Added labels
handler
,status
,method
tohttp_requests_total
indefault
. - Added label
handler
tohttp_request_size_bytes
. - Added label
handler
tohttp_response_size_bytes
.
- BREAKING: Renamed instrumentation
full
todefault
. - BREAKING: Renamed
http_in_bytes_total
tohttp_request_size_bytes
. - BREAKING: Renamed
http_out_bytes_total
tohttp_response_size_bytes
. - BREAKING: Renamed
http_highr_request_duration_seconds
tohttp_request_duration_highr_seconds
. - BREAKING: Renamed
http_lowr_request_duration_seconds
tohttp_request_duration_seconds
. - BREAKING: Turned
http_request_size_bytes
andhttp_response_size_bytes
into summaries.
- BREAKING: Removed labels
method
andstatus
fromhttp_request_duration_seconds
.
4.0.0 / 2020-08-16
- Added proper documentation.
- BREAKING: Switched the default fast track metric to a more advanced one.
- BREAKING: Reworked available metrics. Made them more modular while improving code structure.
3.0.0 / 2020-08-15
A lot of breaking changes in this release. Prometheus FastAPI Instrumentator is now more modular than before and there are multiple different metrics one can choose from out of the box or add custom metrics that will be automatically applied to the FastAPI.
If you just use the default instrumentator without setting any parameters, nothing changes. The defaults stay the same.
If you use any of the paramters that were available in the Instrumentator
constructor you have to check if they are still available or not. Some of them
have been moved to the corresponding metric
closure / function.
- BREAKING: Endpoint
/metrics
is not excluded by default anymore. - BREAKING: Rework instrumentator layout.
2.0.1 / 2020-08-14
- Fixed wrong var name in
README.md
.
2.0.0 / 2020-08-14
- Added option to exclude optional
/metrics
endpoint from schema.
- BREAKING: Renamed
should_respect_env_var_existence
toshould_respect_env_var
. - BREAKING: If
should_respect_env_var
isTrue
, the respective env var must betrue
and not just any random value. - BREAKING: Renamed default env var if
should_respect_env_var
fromPROMETHEUS
toENABLE_METRICS
.
1.3.0 / 2020-08-12
- Added option
should_respect_env_var_existence
. This makes it possible to only instrument and expose your FastAPI if a given environment variable is set. Use case: A base FastAPI app that is used by multiple distinct apps. The apps only have to set the variable to be instrumented. Deactivated by default and the default env var isPROMETHEUS
.
1.2.0 / 2020-08-06
- The observed latency values can now be rounded to a certain number of decimals as an opt-in feature. This can improve bytes per sample required in storage solutions like VictoriaMetrics.
1.1.1 / 2020-07-19
Nothing. Dummy release.
1.1.0 / 2020-07-16
- Renamed project from Prometheus FastAPI Exporter to Prometheus FastAPI Instrumentator. Reasoning behind this change: Focus of this project is the instrumentation, not exposition of metrics.
1.0.2 / 2020-07-15
- Updated README.md
1.0.1 / 2020-07-15
- Updated README.md
1.0.0 / 2020-07-15
- Explicit method to expose metrics by adding endpoint to an FastAPI app.
- BREAKING: Switched to semantic versioning. All older versions have been yanked.
- BREAKING: Split instrumentation and exposition into two parts. Why? There
exist many ways to expose metrics. Now this package enables the
instrumentation of FastAPI without enforcing a certain method of exposition.
It is still possible with the new method
expose()
. - BREAKING: Moved pass of FastAPI object from constructor to
instrument()
method.
- BREAKING: Exposition of metrics endpoint from
ìnstrument()
call.