ngx_http_vts_module是替代stub_status的开源Nginx模块，提供按server、upstream、后端节点维度的细粒度实时流量统计，支持JSON/HTML输出及Prometheus集成。
ngx_http_vts_module（Nginx Virtual Host Traffic Status module）是一个开源的 Nginx 第三方模块，用于替代原生的 stub_status，提供更丰富、更细粒度的实时流量与连接状态数据。它不依赖 Lua 或外部服务，直接嵌入 Nginx 工作进程，以高效 JSON 和 HTML 格式暴露指标，特别适合监控集成（如 Prometheus + Grafana）、多虚拟主机流量分析和运维排障。
核心能力：比 stub_status 多了什么？
原生 stub_status 仅返回全局连接数（accepts、handled、requests）和当前活跃连接状态（reading/writing/waiting），且无法区分 server 或 upstream。vts 模块则按以下维度分层统计：
- 按 server_name 维度：每个虚拟主机独立统计请求量、响应码分布（2xx/3xx/4xx/5xx）、流量（in/out）、处理时间（avg、max）等
- 按 upstream（后端集群）维度：记录每个 upstream 的活跃连接、请求计数、失败次数、健康检查状态、权重与当前状态（up/down/unavail）
- 按 upstream server（单个后端节点）维度：细化到每个 IP:port 的连接数、请求计数、响应时间、失败原因（timeout、refused、unreachable）
-
支持动态过滤与聚合：可通过 URI 参数（如
?filter=example.com）筛选特定虚拟主机；支持按正则匹配分组
安装与启用方式
该模块需在编译 Nginx 时静态或动态加载，不支持运行时 hot reload 启用。推荐使用动态模块方式，便于版本升级维护：
- 下载对应 Nginx 版本的 vts 源码，解压至模块目录
- 重新编译 Nginx：
./configure --add-dynamic-module=/path/to/nginx-module-vts，执行make && make install - 在
nginx.conf的http块中添加：load_module modules/ngx_http_vts_module.so;
并配置状态接口位置，例如：
location /status {
vhost_traffic_status on;
vhost_traffic_status_display on;
vhost_traffic_status_display_format html;
}
重启 Nginx 后访问 /status 即可看到可视化页面；访问 /status/format/json 获取结构化数据。
关键配置项说明
vts 提供多个精细控制参数，影响数据精度与性能开销：
-
vhost_traffic_status：主开关，必须开启才能采集数据（默认 off） -
vhost_traffic_status_zone：定义共享内存区域大小（如vhost_traffic_status_zone size=1m;），建议按虚拟主机数 × 2KB 预估，不足会导致统计丢失 -
vhost_traffic_status_filter_by_host：设为on可使server_name统计严格匹配 Host 请求头（避免泛域名或 IP 直连导致的归类混乱） -
vhost_traffic_status_filter_by_set_key：支持按自定义变量（如 $upstream_addr、$sent_http_x_app_id）分组统计，适合灰度或租户隔离场景 -
vhost_traffic_status_limit：限制单个 upstream 或 server 最大并发连接数统计上限，防内存溢出
对接监控系统的实用技巧
vts 输出的 JSON 接口天然适配 Prometheus。只需部署 vts-exporter（轻量 Go 程序），即可将 JSON 转为 Prometheus metrics：
- Exporter 默认拉取
http://localhost/status/format/json，自动展开嵌套结构（如server.example.com.request.count） - 常用告警指标示例：
•nginx_vts_server_request_total{server=~".+"}持续为 0 → 服务未被访问或配置未生效
•nginx_vts_upstream_server_in_bytes_total{upstream="api_backend",server="10.0.1.5:8080"}突降 → 后端节点异常下线
•nginx_vts_server_response_code_total{code=~"5..",server="admin.example.com"}激增 → 应用层报错 - 注意：vts 不采集 request time 百分位（p95/p99），如需高阶延迟分析，建议配合 access_log + logrotate + Loki/ELK 或 OpenTelemetry
