Prometheus FastAPI 检测器

一个可配置和模块化的FastAPI Prometheus检测器。从PyPI安装prometheus-fastapi-instrumentator。以下是快速入门使用预配置检测器的方法。导入检测器类：

from prometheus_fastapi_instrumentator import Instrumentator

使用默认指标检测你的应用并暴露指标：

Instrumentator().instrument(app).expose(app)

根据你的代码，你可能需要使用以下方式替代：

instrumentator = Instrumentator().instrument(app)

@app.on_event("startup")
async def _startup():
    instrumentator.expose(app)

这样，你的FastAPI就被检测了，指标可以被抓取。默认情况下，你会得到：

计数器 http_requests_total，包含 handler、status 和 method 标签。请求总数。
摘要 http_request_size_bytes，包含 handler 标签。所有传入请求内容长度的总和。
摘要 http_response_size_bytes，包含 handler 标签。所有传出响应内容长度的总和。
直方图 http_request_duration_seconds，包含 handler 和 method 标签。只有少量桶以保持基数较低。
直方图 http_request_duration_highr_seconds，没有任何标签。大量桶（>20）。

此外，还有以下行为：

状态码被分组为 2xx、3xx 等。
没有匹配模板的请求被归类为 none 处理器。

如果这些预设不符合你的需求，你可以做以下几件事：

从metrics中选择一个已有的闭包并传递给检测器实例。参见这里了解如何操作。
创建你自己的检测函数并传递给检测器实例。参见这里了解更多。
完全不使用这个包，只是将源代码作为如何检测你的FastAPI的灵感。

免责声明

不适用于Python中的通用Prometheus检测。请使用Prometheus客户端库进行通用检测。本包也使用了该库。

所有通用中间件和检测代码都会带来性能成本，可能会变得明显。

特性

除了快速入门，这个检测器是高度可配置的，很容易定制和适应你的特定用例。以下是一些你可以选择的选项：

使用正则表达式忽略某些路由。
完全忽略未模板化的路由。
通过环境变量控制检测和暴露。
将延迟四舍五入到特定小数位。
重命名标签和指标。
指标端点可以使用gzip压缩数据。
可选指标来监控进行中的请求数量。

它还具有模块化的指标方法，应该检测所有FastAPI端点。你可以从一组已有的指标中选择，也可以创建自己的指标。每个指标函数本身也可以配置。

高级用法

本章包含Prometheus FastAPI检测器高级用法的示例，展示了它的大多数功能。

创建检测器

我们首先创建一个检测器实例。注意额外导入的metrics。稍后会用到。

from prometheus_fastapi_instrumentator import Instrumentator, metrics

instrumentator = Instrumentator(
    should_group_status_codes=False,
    should_ignore_untemplated=True,
    should_respect_env_var=True,
    should_instrument_requests_inprogress=True,
    excluded_handlers=[".*admin.*", "/metrics"],
    env_var_name="ENABLE_METRICS",
    inprogress_name="inprogress",
    inprogress_labels=True,
)

与快速入门示例不同，现在只有在运行时环境变量ENABLE_METRICS为true时才会进行检测和暴露。这在依赖相同基础FastAPI的大型部署中多个服务中可能会有帮助。

添加指标

假设我们还想检测请求和响应的大小。为此，我们使用add()方法。这个方法只是将一个函数添加到列表中。然后在运行时，每次FastAPI处理请求时，都会调用这个列表中的所有函数，并给它们一个包含有用信息（如请求和响应对象）的单一参数。如果完全不使用add()，则会在后台添加默认指标。这就是快速入门示例中发生的情况。

所有检测函数都作为闭包存储在metrics模块中。

闭包在这里很有用，因为它允许我们配置其中的函数。

instrumentator.add(metrics.latency(buckets=(1, 2, 3,)))

这只是添加了你在快速入门示例中获得的指标，但修改了桶参数。但我们还想记录所有请求和响应的大小。

instrumentator.add(
    metrics.request_size(
        should_include_handler=True,
        should_include_method=False,
        should_include_status=True,
        metric_namespace="a",
        metric_subsystem="b",
    )
).add(
    metrics.response_size(
        should_include_handler=True,
        should_include_method=False,
        should_include_status=True,
        metric_namespace="namespace",
        metric_subsystem="subsystem",
    )
)

你可以向检测器添加任意数量的指标。

创建新指标

如前所述,可以创建自定义函数传递给add()。默认指标也是通过这种方式实现的。

基本思路是,instrumentator 创建一个info对象,其中包含基于 instrumentator 配置的所有必要的检测信息。这包括原始的请求和响应对象,以及修改后的处理程序、分组状态码和持续时间。接下来,调用所有注册的检测函数。它们以info作为唯一参数。

假设我们想要统计某种语言被请求的次数。

from typing import Callable
from prometheus_fastapi_instrumentator.metrics import Info
from prometheus_client import Counter

def http_requested_languages_total() -> Callable[[Info], None]:
    METRIC = Counter(
        "http_requested_languages_total",
        "某种语言被请求的次数。",
        labelnames=("langs",)
    )

    def instrumentation(info: Info) -> None:
        langs = set()
        lang_str = info.request.headers["Accept-Language"]
        for element in lang_str.split(","):
            element = element.split(";")[0].strip().lower()
            langs.add(element)
        for language in langs:
            METRIC.labels(language).inc()

    return instrumentation

函数http_requested_languages_total用于存储在所有检测执行之间的持久元素(例如指标实例本身)。接下来是闭包。这个函数必须遵守所示的接口。它总是会得到一个Info对象,其中包含请求、响应和一些其他修改后的信息。例如(分组的)状态码或处理程序。最后,返回闭包。

重要提示: info中的响应对象可以是响应对象,也可以是None。此外,处理程序中抛出的错误不会被 instrumentator 捕获。我建议在创建自己的指标之前查看文档和/或源代码。

要使用它,我们将闭包传递给 instrumentator 对象。

instrumentator.add(http_requested_languages_total())

执行检测

到目前为止,FastAPI 完全没有被触及。一切都只存储在instrumentator中。要实际在 FastAPI 中注册检测,必须调用instrument()方法。

instrumentator.instrument(app)

请注意,如果在构造 instrumentator 对象时设置了should_respect_env_var,并且没有找到相应的环境变量,这将不会执行任何操作。

指定命名空间和子系统

你可以通过在 instrument 方法中传递参数来指定指标的命名空间和子系统。

from prometheus_fastapi_instrumentator import Instrumentator

@app.on_event("startup")
async def startup():
    Instrumentator().instrument(app, metric_namespace='myproject', metric_subsystem='myservice').expose(app)

然后你的指标名称中将包含命名空间和子系统。

# TYPE myproject_myservice_http_request_duration_highr_seconds histogram
myproject_myservice_http_request_duration_highr_seconds_bucket{le="0.01"} 0.0

暴露端点

要暴露指标的端点,可以按照Prometheus Python Client的说明手动将端点添加到 FastAPI,或者在单独的服务器上提供服务。你也可以使用包含的expose方法。它会将一个端点添加到给定的 FastAPI。通过should_gzip,你可以指示端点在客户端接受 gzip 编码的情况下压缩数据。例如,Prometheus 默认接受 gzip 编码。请注意,网络带宽通常比 CPU 周期更便宜。

instrumentator.expose(app, include_in_schema=False, should_gzip=True)

请注意,如果在构造 instrumentator 对象时设置了should_respect_env_var,并且没有找到相应的环境变量,这将不会执行任何操作。

贡献

请参阅CONTRIBUTING.md。

有关开发指导,请查阅DEVELOPMENT.md。

阅读RELEASE.md了解发布流程的详细信息。

许可

该项目的默认许可证是ISC 许可证。这是一个宽松的许可证,在功能上等同于 BSD 2-Clause 和 MIT 许可证,删除了一些不再必要的语言。请查看LICENSE获取许可证文本。

BSD 3-Clause 许可证用作routing模块的许可证。这是因为它包含来自elastic/apm-agent-python的代码。BSD 3-Clause 是一个类似于 BSD 2-Clause 许可证的宽松许可证,但增加了第三个条款,禁止他人在未经书面同意的情况下使用版权持有人或其贡献者的名称来推广衍生产品。许可证文本包含在模块本身中。