ngx_http_vts_module 是轻量高效Nginx第三方状态模块，替代stub_status，支持server/upstream/location多维实时统计，通过HTTP暴露JSON/HTML指标，无需外部依赖，易于集成Prometheus、Grafana等监控平台。
ngx_http_vts_module 是一个轻量、高效且兼容性良好的 Nginx 第三方状态模块，可替代传统的 stub_status，并提供按 server、upstream、location 等维度的实时请求统计。它不依赖外部存储或 Agent，直接通过 HTTP 接口暴露 JSON 或 HTML 格式指标，非常适合构建低侵入、高可用的流量监控体系。
核心指标采集与维度拆解
该模块默认暴露以下关键维度的实时数据：
- Server 维度：每个 server_name 的总请求数、成功/失败响应数、流量（in/out）、连接数等
- Upstream 维度：后端集群中每个 upstream 的活跃连接、请求计数、响应时间（需配合 nginx-plus 或自定义 patch）、健康状态
- Location 维度：每个 location 块的独立访问频次、返回码分布（如 2xx/4xx/5xx）、带宽消耗
- Filter 支持：可通过 vhost_traffic_status_filter_by_set_key 指令按自定义 key（如 uid、app_id、api_version）做动态分组聚合
快速集成与安全暴露监控端点
在 nginx.conf 中启用模块后，建议通过独立 server 块暴露监控接口，并限制访问来源：
server {
listen 127.0.0.1:8080;
server_name status.local;
<pre class="brush:php;toolbar:false;">location /status {
vhost_traffic_status_display;
vhost_traffic_status_display_format html;
}
location /status/format/json {
vhost_traffic_status_display;
vhost_traffic_status_display_format json;
}
# 仅允许内网监控系统拉取
allow 192.168.10.0/24;
deny all;}
若需更高安全性，可添加 basic_auth 或对接 API 网关鉴权；JSON 接口更适配 Prometheus、Telegraf 等采集器。
对接主流监控平台的关键配置
要将指标纳入可观测体系，需注意格式适配和采集频率控制：
- Prometheus：使用 nginx-vts-exporter（Go 编写）作为中间层，自动转换 JSON 为 Prometheus metrics 格式；注意设置 scrape_interval ≤ 15s，避免高频请求冲击 Nginx
- Grafana：推荐使用官方模板 ID 10229（Nginx VTS Dashboard），支持 server/upstream 切换、错误率热力图、Top N location 排行榜
- ELK/Splunk：通过 Logstash http_poller 插件定时 GET /status/format/json，提取字段如 “server.example.com.request_counter”、“upstream.backend1.in_bytes” 并打标写入
进阶用法：动态标签与业务指标注入
利用 vhost_traffic_status_filter_by_set_key，可将业务上下文注入指标路径，实现语义化监控：
location /api/v1/user {
vhost_traffic_status_filter_by_set_key $arg_appid appid;
vhost_traffic_status_filter_by_set_key $http_x_client_type client_type;
proxy_pass http://user_backend;
}此时指标路径变为 /status/format/json/appid=web/client_type=mobile，便于按应用、终端类型下钻分析。注意 key 值需符合 URL 安全规范，建议预处理过滤非法字符。
