如何通过Nginx与vts-module实现Prometheus格式网关实时监控指标导出？

本文共计998个文字，预计阅读时间需要4分钟。

直接上结论：

编译 Nginx 时必须启用 vts-module 和必要模块

vts-module 是第三方模块，不内置，且依赖明确的 HTTP 模块支持。缺任意一项，/status/format/json 接口要么 404，要么返回空或无 upstream 数据。

• 必须显式添加：--add-module=/path/to/nginx-module-vts
• 必须启用：--with-http_v2_module（否则 vts 的 upstream 统计不生效）
• 必须启用：--with-http_ssl_module（若后端 upstream 用 HTTPS，vts 才能识别 scheme 和 port）
• 避免使用太旧的 Nginx 版本（建议 ≥ 1.18），vts-module 对 1.21+ 兼容性更稳

验证是否生效：启动后请求 curl http://localhost/status/format/json，响应中应含 "upstreamZones" 字段，且每个 upstream name 下有 "requestCounter"、"inBytes"、"responseCodes" 等嵌套结构。

nginx.conf 中 upstream 和 vts 配置要严格对应

vts-module 的指标粒度完全取决于 Nginx 配置里是否定义了 upstream 块——它不会自动从 proxy_pass http://host:port 解析出逻辑 upstream 名。没配 upstream，所有流量就归到 default zone，无法区分后端服务。

• 错误写法：proxy_pass http://10.0.1.100:8080;（无 upstream，vts 只记为 "default"）
• 正确写法：

  upstream api_backend { server 10.0.1.100:8080; server 10.0.1.101:8080; } server { location /api/ { proxy_pass http://api_backend; } }

• 若用变量动态 upstream（如 proxy_pass http://$backend），vts 无法聚合，一律计入 "default" zone

注意：upstream 名称会直接成为 Prometheus label 中的 upstream 值，建议全小写+下划线，避免特殊字符。

vts-exporter 是唯一可行的 Prometheus 指标导出方式

Nginx + vts-module 只提供 JSON 接口，Prometheus 抓取必须是文本格式（text/plain; version=0.0.4）。没有官方 exporter，社区通用方案是 vts-exporter（Go 编写，轻量）。

• 下载预编译二进制：vts-exporter-0.12.0-linux-amd64（注意匹配系统架构）
• 启动命令示例：./vts-exporter --nginx.scrape-uri=http://localhost/status/format/json --web.listen-address=:9913
• 关键参数：--nginx.scrape-uri 必须指向 Nginx 的 vts JSON 接口，不能是 HTML 或 XML 格式地址
• 抓取间隔由 Prometheus 配置控制，vts-exporter 自身不缓存，每次请求都实时调用 Nginx 接口

验证：访问 http://localhost:9913/metrics，应看到类似 nginx_vts_upstream_requests_total{upstream="api_backend",code="200"} 的指标行，且数值与 /status/format/json 中对应字段一致。

Prometheus 配置和常见数据断点排查

即使 exporter 正常，Prometheus 也可能拉不到数据，多数因 target 状态为 DOWN 或指标无值。重点查三处：

• target 页面显示 context deadline exceeded → 检查 vts-exporter 是否能通 Nginx（curl -I http://localhost/status/format/json）
• target 显示 UP，但指标为空 → 检查 Nginx 日志是否有 no resolver defined（vts 在解析 upstream host 时失败，导致 zone 初始化异常）
• 有指标但 upstream label 全是 default → 回头确认 Nginx 配置中是否真有命名 upstream 块，且 proxy_pass 引用的是该名称
• status code 分布始终为 0 → 确认 Nginx 启用了 log_format 且 access_log 开启（vts 的 responseCodes 统计依赖 access log 解析）

vts 指标是内存实时聚合，不持久化；Nginx reload 会清空计数器。如果发现某 upstream 的 requestCounter 长期为 0，大概率是该 upstream 根本没被任何请求命中过，而不是采集链路故障。