如何通过 ngx_http_vts_module 实时监控后端节点 QPS 和错误率？

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

ngx_http_vts_module（Nginx+Virtual+Host+Traffic+Status）是一个轻量级、高性能的Nginx状态监控模块，原生支持以JSON或HTML格式暴露虚拟主机流量状态。

启用 vts 模块并配置 upstream 监控

确保你使用的 Nginx 已静态编译或动态加载了 ngx_http_vts_module（注意：非官方模块，需自行编译）。在 http 块中启用状态接口，并为每个 upstream 显式开启统计：

http { vhost_traffic_status_zone; # 必须声明，用于共享内存存储统计 vhost_traffic_status_filter_by_host on; <pre class='brush:php;toolbar:false;'>upstream backend_api { server 10.0.1.10:8080; server 10.0.1.11:8080; server 10.0.1.12:8080; # 启用 per-server 统计（关键！否则只统计 upstream 整体） vhost_traffic_status_filter_by_upstream on; } server { location /status { vhost_traffic_status_display; vhost_traffic_status_display_format json; } }

}

⚠️ 注意：vhost_traffic_status_filter_by_upstream on 必须放在 upstream 块内（或其父作用域），否则各 server 的独立指标不会被分别记录。

从 /status 接口提取各节点 QPS 与错误率

访问 /status 返回的是嵌套 JSON，关键路径如下：

• QPS（每秒请求数）：对每个 upstream server，取 stat.requestCounter 的增量值。vts 不直接提供瞬时 QPS，需客户端按固定间隔（如 1s）轮询两次，计算差值 ÷ 时间差。
• 错误率：用 stat.inBytes（入流量）或 stat.requestCounter 作分母，分子推荐用 stat.responseCounter.5xx（5xx 总数）；更精确可结合 stat.responseCounter.4xx 和业务定义的“错误”状态码（如 400/401/429）。

示例解析逻辑（Python 片段）：

import requests, time url = "http://nginx-host/status" prev_data = None <p>while True: r = requests.get(url) data = r.json() servers = data["upstreamZones"]["backend_api"] # 对应 upstream 名 for s in servers: addr = s["server"] req_now = s["stat"]["requestCounter"] code5xx = s["stat"]["responseCounter"]["5xx"]</p><pre class='brush:php;toolbar:false;'> if prev_data: prev = [x for x in prev_data["upstreamZones"]["backend_api"] if x["server"] == addr][0] qps = (req_now - prev["stat"]["requestCounter"]) / 1.0 err_rate = (code5xx - prev["stat"]["responseCounter"]["5xx"]) / max(qps, 1) if qps > 0 else 0 print(f"{addr}: QPS={qps:.1f}, 5xx_rate={err_rate:.3f}") prev_data = data time.sleep(1)

导出到 Prometheus（推荐生产方案）

vts 本身不兼容 Prometheus 格式，但可用轻量 exporter 桥接：

• 使用开源项目 nginx-vts-exporter：它定期拉取 /status，自动转换为 Prometheus metrics，暴露 /metrics 端点。
• 关键指标已预定义：
  • nginx_vts_upstream_requests_total{upstream="backend_api",server="10.0.1.10:8080"}
  • nginx_vts_upstream_responses_total{code="5xx",upstream="backend_api",server="10.0.1.10:8080"}
• PromQL 计算 QPS：rate(nginx_vts_upstream_requests_total{upstream="backend_api"}[1m])
• 计算 5xx 错误率：rate(nginx_vts_upstream_responses_total{code="5xx",upstream="backend_api"}[1m]) / rate(nginx_vts_upstream_requests_total{upstream="backend_api"}[1m])

注意事项与调优

vts 在高并发下性能优秀，但仍需关注几点：

• 共享内存大小默认仅 1M，若 upstream 节点多或虚拟主机多，需增大：vhost_traffic_status_zone shared:vhost_traffic_status:10m;
• 避免将 /status 暴露到公网，建议加 IP 白名单或 basic auth。
• 如果使用 keepalive 连接，stat.inBytes 和 stat.outBytes 更稳定；而 requestCounter 可能受重试、内部跳转影响，建议结合 access_log + $status 做交叉验证。
• 错误率建议按分钟级滑动窗口计算（如 Prom 的 rate(...[1m])），避免秒级抖动干扰判断。