vts-module 不输出 Prometheus 格式，需通过 vts-exporter 转换；编译 Nginx 必须启用 --add-module=/path/to/nginx-module-vts、--with-http_v2_module 和 --with-http_ssl_module，且需正确定义 upstream 块，否则指标缺失关键维度或全归入 default zone。
直接上结论：vts-module 本身不输出 Prometheus 格式，必须通过 vts-exporter 这个中间服务做协议转换；Nginx 编译时漏掉 --with-http_v2_module 或未启用 upstream 配置，会导致指标缺失关键维度（如 upstream name、status code 分布）。
编译 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 初始化异常） - 有指标但
upstreamlabel 全是default→ 回头确认 Nginx 配置中是否真有命名upstream块，且proxy_pass引用的是该名称 - status code 分布始终为 0 → 确认 Nginx 启用了
log_format且access_log开启（vts 的 responseCodes 统计依赖 access log 解析）
vts 指标是内存实时聚合，不持久化；Nginx reload 会清空计数器。如果发现某 upstream 的 requestCounter 长期为 0，大概率是该 upstream 根本没被任何请求命中过，而不是采集链路故障。
