Pingora Prometheus 监控接入指南为 Pingora 服务搭建 HTTP 指标端点【免费下载链接】pingoraA library for building fast, reliable and evolvable network services.项目地址: https://gitcode.com/GitHub_Trending/pi/pingora导读本文介绍如何通过pingora-prometheuscrate 为基于 Pingora 构建的网络服务反向代理、网关、自定义应用快速接入 Prometheus 监控体系。文中将依次说明依赖引入、指标服务注册、静态指标定义与代码埋点四个步骤并结合仓库内真实源码与示例如pingora-proxy/examples/gateway.rs、pingora/examples/server.rs展开底层原理讲解读完即可在自有 Pingora 服务上搭建可被 Prometheus 抓取的/metrics端点。pingora-prometheus是 Pingora 工作区见根目录 Cargo.toml 的members列表中的一个独立 crate其定位正如 crate 文档所描述为 Pingora 服务提供一个 Prometheus 指标 HTTP 抓取服务A Prometheus metrics HTTP server for pingora services。它本身不负责业务埋点而是将业务侧通过prometheuscrate 收集到的静态指标统一以 HTTP 端点形式对外暴露供 Prometheus Server 周期性抓取。第一步添加依赖在项目的Cargo.toml中为pingora-prometheus添加依赖pingora-prometheus 0.8.0当前仓库中该 crate 的版本为0.8.0见 pingora-prometheus/Cargo.toml其依赖关系如下pingora-core0.8.0默认特性关闭提供Service、add_tcp等服务注册机制prometheus0.14负责指标的类型定义、注册与编码async-trait、http来自工作区共享依赖用于实现ServeHttptrait 与构建 HTTP 响应。需要注意的是pingora-prometheus依赖pingora-core并开启了default-features false这意味着它的 HTTP 服务能力来自pingora-core中的HttpServer/Service而不引入多余的默认特性。第二步搭建 Prometheus 指标端点最简单的方式是在Server上注册一个由prometheus_http_service()便捷函数创建的 HTTP 服务并将其绑定到独立的监听地址let mut prometheus_service_http pingora_prometheus::prometheus_http_service(); prometheus_service_http.add_tcp(0.0.0.0:1234); my_server.add_service(prometheus_service_http); my_server.run_forever();该便捷函数在源码 pingora-prometheus/src/lib.rs 中的实现等价于pub fn prometheus_http_service() - ServicePrometheusServer { Service::new( Prometheus metric HTTP.to_string(), new_prometheus_server(), ) }底层原理PrometheusHttpApp 与 PrometheusServer从源码结构看pingora-prometheus由三层组成PrometheusHttpApp见 lib.rs实现了ServeHttptrait 的 HTTP 应用。其response()方法核心逻辑为创建TextEncoder文本编码器即 Prometheus 标准的text/plain; version0.0.4暴露格式调用prometheus::gather()从全局注册表中收集所有已注册指标将指标编码进响应体并显式设置Content-Type与Content-Length头返回 HTTP 200。一个值得注意的实现细节是该应用当前对所有请求路径都返回指标数据而非严格限定/metrics。源码中留有注释// TODO: consider restricting to /metrics and returning 404 for other paths说明这是有意为之的设计它通常绑定在独立监听端口上Prometheus 抓取任意路径均可拿到指标。若你打算与其他路由共享同一监听器需自行留意这一行为。PrometheusServer见 lib.rsHttpServerPrometheusHttpApp的类型别名为PrometheusHttpApp提供完整的 HTTP 服务能力连接接受、会话管理、模块化响应处理链等。new_prometheus_server()见 lib.rs创建PrometheusServer并挂载 gzip 压缩模块压缩级别为 7。这有助于在大批量指标抓取时降低带宽消耗pub fn new_prometheus_server() - PrometheusServer { let mut server PrometheusServer::new_app(PrometheusHttpApp); // enable gzip level 7 compression server.add_module(ResponseCompressionBuilder::enable(7)); server }gzip 压缩模块来自pingora_core::modules::http::compression::ResponseCompressionBuilderenable(7)表示启用压缩并将压缩级别设为 70 为不压缩9 为最高压缩。Prometheus 抓取器通常声明Accept-Encoding: gzip因此该配置在真实抓取场景下会生效。手动组装的方式如果你希望更细粒度地控制服务名或扩展行为也可以不借助便捷函数而是显式构造Serviceuse pingora_core::services::listening::Service; use pingora_prometheus::new_prometheus_server; let mut prometheus_service Service::new( Prometheus HTTP.to_string(), new_prometheus_server(), ); prometheus_service.add_tcp(127.0.0.1:6150); server.add_service(prometheus_service);监听地址的选择建议在仓库示例 pingora/examples/server.rs 中指标服务被绑定在127.0.0.1:6150在 pingora-proxy/examples/gateway.rs 与 docs/user_guide/modify_filter.md 的示例中则绑定在127.0.0.1:6192。生产实践中建议优先绑定127.0.0.1或内网地址仅在指标端口与业务端口之间建立网络隔离避免暴露在公网确保该端口只对 Prometheus 抓取器所在网络开放防止任意路径抓取指标造成信息泄露。第三步定义静态指标pingora-prometheus最简单的使用方式是配合prometheuscrate 的静态指标static metrics机制——即在模块加载时通过Lazy一次性注册全局指标。这样无需手动传递指标实例指标会自动出现在指标端点中。例如定义一个计数器类型的静态指标static MY_COUNTER: LazyIntGauge Lazy::new(|| { register_int_gauge!(my_counter, my counter).unwrap() });这里使用了once_cell或std::sync::LazyLock的Lazy保证指标只在首次访问时初始化一次register_int_gauge!宏则完成两件事将指标定义名称 帮助文本写入prometheuscrate 的全局注册表返回一个IntGauge实例后续可通过MY_COUNTER.set(...)等操作更新取值。用重导出的 prometheus 避免版本错配一个关键的实践细节pingora-prometheus在 lib.rs 中重导出了prometheuscratepub use prometheus;并明确建议业务代码使用这个重导出路径来注册指标use pingora_prometheus::prometheus::{self, register_int_counter, IntCounter}; use once_cell::sync::Lazy; static REQUESTS: LazyIntCounter Lazy::new(|| { register_int_counter!(requests_total, Total requests).unwrap() });原因在于PrometheusHttpApp抓取的是prometheus::gather()对应的全局注册表。如果业务代码直接依赖另一个版本的prometheuscrate两个版本各自维护独立的全局注册表就会导致业务注册的指标在抓取端口中“静默消失”。统一通过pingora_prometheus::prometheus重导出引用即可保证注册表一致。仓库中的真实示例也遵循了这一模式。例如 pingora/examples/app/echo.rs 使用register_int_counter!注册请求计数器pingora-proxy/examples/gateway.rs 则在MyGateway结构中持有prometheus::IntCounter并在构造函数中完成注册。第四步在业务代码中埋点静态指标定义完成后即可在业务逻辑中更新指标取值。以 pingora-proxy/examples/gateway.rs 为例它在ProxyHttp的logging阶段该阶段对每个请求都会执行无论成功与否对请求计数器自增pub struct MyGateway { req_metric: prometheus::IntCounter, } #[async_trait] impl ProxyHttp for MyGateway { // ... async fn logging( self, session: mut Session, _e: Optionpingora_core::Error, ctx: mut Self::CTX, ) { let response_code session .response_written() .map_or(0, |resp| resp.status.as_u16()); // access log info!( {} response code: {response_code}, self.request_summary(session, ctx) ); self.req_metric.inc(); } }在main()中指标服务与代理服务一并注册进同一个Serverfn main() { env_logger::init(); let opt Opt::parse_args(); let mut my_server Server::new(Some(opt)).unwrap(); my_server.bootstrap(); let mut my_proxy pingora_proxy::http_proxy_service( my_server.configuration, MyGateway { req_metric: register_int_counter!(req_counter, Number of requests).unwrap(), }, ); my_proxy.add_tcp(0.0.0.0:6191); my_server.add_service(my_proxy); let mut prometheus_service_http pingora_prometheus::prometheus_http_service(); prometheus_service_http.add_tcp(127.0.0.1:6192); my_server.add_service(prometheus_service_http); my_server.run_forever(); }该示例还给出了便于本地验证的命令见 gateway.rs 文件头注释# 运行示例需在 pingora-proxy crate 目录下 RUST_LOGINFO cargo run --example gateway # 发起代理请求 curl 127.0.0.1:6191 -H Host: one.one.one.one # 抓取指标 curl 127.0.0.1:6192/对curl 127.0.0.1:6192/的响应即 Prometheus 文本格式的指标集合其中应包含req_counter若支持 gzip抓取时会以 gzip 压缩返回。在过滤器/日志场景中的组合使用如果你使用 Pingora 的过滤器filter机制而非完整代理参考 docs/user_guide/modify_filter.md 的示例思路完全一致在过滤器链的logging阶段对指标自增同时独立启动一个 Prometheus 指标 HTTP 服务用于被抓取let mut prometheus_service_http pingora_prometheus::prometheus_http_service(); prometheus_service_http.add_tcp(127.0.0.1:6192); my_server.add_service(prometheus_service_http);指标抓取验证服务启动后可以用以下方式验证指标端点是否工作正常# 直接查看原始指标输出 curl -s http://127.0.0.1:1234/ | head -50 # 观察请求计数随请求量增长 curl -s http://127.0.0.1:1234/ | grep req_counter随后在 Prometheus Server 的prometheus.yml中配置抓取目标scrape_configs: - job_name: pingora static_configs: - targets: [127.0.0.1:1234]Prometheus 会按默认抓取间隔周期性地请求该端点。由于pingora-prometheus已内置 gzip 压缩级别 7对大规模指标集的抓取传输开销可以得到有效控制。核心 API 一览符号作用源码位置pingora_prometheus::prometheus_http_service()便捷函数返回已配置好的ServicePrometheusServer可直接add_tcp后注册lib.rspingora_prometheus::new_prometheus_server()创建启用 gzip级别 7压缩的PrometheusServerlib.rspingora_prometheus::PrometheusServerHttpServerPrometheusHttpApp的类型别名lib.rspingora_prometheus::PrometheusHttpApp实现ServeHttp的应用负责编码并返回所有静态指标lib.rspingora_prometheus::prometheus重导出的prometheuscrate确保全局注册表一致lib.rs小结接入 Pingora 的 Prometheus 监控只需四步在Cargo.toml添加pingora-prometheus依赖、用prometheus_http_service()创建并注册指标服务、用静态指标宏定义业务指标、在代理/过滤器/日志等处理阶段更新指标取值。底层实现上PrometheusHttpApp通过prometheus::gather()汇总全局注册表并以文本格式暴露配合内置 gzip 压缩足以支撑生产环境的监控抓取需求。更进一步pingora-core的配置文档见 docs/user_guide/conf.md还提供了runtime_metrics_poll_time_histogram等与运行时指标相关的配置项需--cfg tokio_unstable编译可与本文的指标端点结合为服务运行时性能提供更细粒度的观测数据。【免费下载链接】pingoraA library for building fast, reliable and evolvable network services.项目地址: https://gitcode.com/GitHub_Trending/pi/pingora创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考