ngx_http_vts_module是轻量级nginx状态监控模块，支持json/html暴露upstream/server/cache实时指标；需配置vhost_traffic_status_zone及vhost_traffic_status_filter_by_upstream on以启用节点级qps与错误率统计，并可通过nginx-vts-exporter对接prometheus。
ngx_http_vts_module（Nginx Virtual Host Traffic Status）是一个轻量级、高性能的 Nginx 状态监控模块，原生支持以 JSON 或 HTML 方式暴露 upstream、server、cache 等维度的实时指标。它不依赖外部存储或代理，适合在生产环境直接采集后端节点的 QPS 与错误率。
启用 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])），避免秒级抖动干扰判断。
