与 Nginx 的原生 Prometheus 集成

# Categorica 来源：https://categorica.io/blog/2026.10.16_nginx-stats-prometheus/ ## NGINX 原生集成 Prometheus 今天，我们正式开源了自行开发的 NGINX Prometheus 统计信息导出模块 (https://github.com/Categorica/nginx-stats-prometheus)\！ ## 简介 长期以来，NGINX 一直是反向代理服务器的事实标准选择。在 Categorica，我们也使用 NGINX 来实现这一用途，同时提供更传统的 Web 内容服务。同样，我们依靠 Prometheus 收集统计信息，并使用 Grafana 汇总和展示运行中的部署的统计信息。 ## 指标收集 目前，使用 NGINX 收集统计信息和指标，实际上只有一个选择：NGINX Prometheus Exporter (https://github.com/nginx/nginx-prometheus-exporter)，这是一个功能齐全的 Prometheus 导出器。在配置我们自己的指标收集系统时，总有一点让人觉得不太对劲：为什么指标端点本身还要运行自己的 Web 服务器？在实践中，这并不是什么大问题。虽然可以将它部署为 systemd 服务\(因此只是一个普通的二进制程序\)，但更常见的做法是通过 Docker 的边车容器部署 NGINX Prometheus Exporter；这增加了一层让人觉得没有必要的复杂性。不过，这*确实*意味着指标收集本身逃脱了指标收集的监测，颇有“谁来监督监督者”的意味。简而言之，这种理念上的不满终究没能抵挡住我们晚间和周末的空闲时间，于是诞生的 NGINX 插件很快就成了我们首选的统计信息收集机制。今天，我们决定将它分享出来。 ## 使用方法 你需要熟悉命令行，对 GNU 的“configure、make、make install”这一套流程有基本了解也会有所帮助，但这并非硬性要求。建议从源码构建 NGINX，以确保所需功能已编译进去\(因为你的包管理器提供的 NGINX 可能与我们预期的有所不同\)，不过，这同样不是必需的。 ### 前置条件 1. 即使你不从源码构建 NGINX，也需要 NGINX 源码来编译该模块。随附的`Makefile`可以替你完成这一步。 2. 如果你不从源码构建 NGINX，那么已安装的 NGINX 必须是在启用`\-\-with\-compat`和`\-\-with\-http\_stub\_status\_module`选项的情况下编译的。 3. 一个 C99 编译器\(例如 Clang\)。 4. PCRE、OpenSSL 和 zlib 的库及头文件。此外，以下步骤假定你在类 Unix 环境中进行构建。 ### 构建 NGINX 如果你已经安装了合适版本的 NGINX，请跳过此步骤。在终端中执行 `` cd path-to-nginx-source; # 构建插件时，我们会使用 NGINX 源码的路径。 export NGINX_SRC=`pwd`; ./configure --with-compat --with-http_stub_status_module; make -j; sudo make install; `` 这将构建并安装 NGINX，通常使用`/usr/local`作为安装前缀。有关构建 NGINX 的更多信息，可以参阅其文档 (https://nginx.org/en/docs/configure.html)。 ### 构建插件 如果你已经安装了合适版本的 NGINX，随附的`Makefile`将确定其版本\(通过调用`nginx \-v`\)，并下载构建插件所需的对应 NGINX 源码。如果你不希望执行这些操作，可以使用环境变量 \-`NGINX\_SRC`\- 设置 NGINX 源码的路径，这样就会跳过版本检查和源码下载。之后，通过以下命令构建插件 `` make module sudo make install `` 这将构建插件，并将其安装到适当的插件位置。更多信息可参阅我们 GitHub 仓库中的 README\.md (https://github.com/Categorica/nginx-stats-prometheus/blob/main/README.md)。 ### 使用插件运行 NGINX 插件构建完成后，需要进行一些配置，以指定提供统计信息的路由。 `` load_module modules/ngx_http_stats_prom_module.so; http { # 可选：设置共享内存大小（默认为 1m） # prometheus_metrics_shm_size 2m; server { # 此处可使用标准 NGINX server 指令 listen 9100; location /metrics { prometheus_metrics; } } } `` 此配置会在`http://hostname:9100/metrics`上导出可供 Prometheus 采集的统计信息。假设 nginx 实例在本地运行，你应该能够通过 curl 查询指标端点： `` curl http://localhost:9100/metrics `` 示例响应如下： `` # HELP nginx_up nginx 进程是否正在运行 # TYPE nginx_up gauge nginx_up 1 # HELP nginx_process_pid 工作进程（提供指标服务）的 PID # TYPE nginx_process_pid gauge nginx_process_pid 2985885 # HELP nginx_http_requests_total HTTP 请求总数 # TYPE nginx_http_requests_total counter nginx_http_requests_total 434488 # HELP nginx_http_responses_total 按状态码类别划分的 HTTP 响应 # TYPE nginx_http_responses_total counter nginx_http_responses_total{status="1xx"} 0 nginx_http_responses_total{status="2xx"} 42598 nginx_http_responses_total{status="3xx"} 771 nginx_http_responses_total{status="4xx"} 77 nginx_http_responses_total{status="5xx"} 1 # 等等。 `` ## 导出的统计信息 运行后，你应该能够通过配置中指定的路由查看 NGINX 的指标。启动后，可用的指标如下：指标类型标签`nginx\_up`gauge`nginx\_process\_pid`gauge`nginx\_http\_requests\_total`counter`nginx\_http\_responses\_total`counter`status`\(`1xx`–`5xx`\)`nginx\_http\_requests\_by\_method\_total`counter`method`\(`GET`,`HEAD`,`POST`,`PUT`,`DELETE`,`OPTIONS`,`PATCH`,`other`\)`nginx\_http\_request\_bytes\_total`counter`nginx\_http\_response\_bytes\_total`counter`nginx\_http\_version\_total`counter`version`\(`1\.0`,`1\.1`,`2\.0`,`3\.0`\)`nginx\_http\_request\_duration\_seconds`histogram\(0\.005, 0\.01, 0\.025, 0\.05, 0\.1, 0\.25, 0\.5, 1, 2\.5, 5, 10\)`nginx\_connections\_active`gauge`nginx\_connections\_reading`gauge`nginx\_connections\_writing`gauge`nginx\_connections\_waiting`gauge`nginx\_connections\_accepted\_total`counter`nginx\_connections\_handled\_total`counter这些指标在进程启动后立即可用，并从进程启动时开始计量。此外，对于`nginx\.conf`文件中定义的每个`server`或`upstream`指令，还会提供基本指标。这些指标会在相应前缀收到第一个请求后出现。指标类型标签`\_requests\_total`counter`server`/`upstream``\_response\_total`counter`server`/`upstream`,`status`\(`1xx`–`5xx`\)`\_request\_bytes\_total`counter`server`/`upstream``\_response\_bytes\_total`counter`server`/`upstream`需要注意的是，最多支持 512 个`server`或`upstream`指令。长度超过 255 个字符的前缀会被忽略。最后，默认仅为统计信息分配 1 MB 内存。如果内存耗尽，将直接跳过统计信息收集，不会发出提示。可以通过 NGINX 配置中的`prometheus\_metrics\_shm\_size`对此进行调整。 ## 局限性 `nginx\-stats\-prometheus`无法直接替代`nginx\-prometheus\-exporter`。主要区别如下：1. 收集的统计信息明显更少。 2. 插件与构建时所用的 NGINX 版本绑定。更新 NGINX 通常需要重新构建插件。 3. 实际环境验证明显不足。显然，我们的统计信息收集方案在成熟度和使用范围上都逊色得多。 ## 许可证与贡献 我们决定以 MIT 许可证发布`nginx\-stats\-prometheus`。我们欢迎拉取请求，欢迎提交。我们只要求提交给我们之前，补丁集至少经过人工审查。我们目前不为`nginx\-stats\-prometheus`提供支持，也无法保证能帮助解决使用过程中可能出现的任何问题。 ## 结语 如果你希望在不使用容器化的情况下运行 NGINX、想要简化部署配置，或者只是更喜欢通过插件收集统计信息的方式，不妨试试`nginx\-stats\-prometheus`\！