如何通过实战演示，将Nginx与nginx-module-vts模块结合，导出符合Prometheus格式的监控数据指标？

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

由于 `nginx-module-vts` 默认未启用，Prometheus 格式输出需要显式配置 `vhost_traffic_status_format prometheus。该指令必须出现在 `http` 块中。如果仅在 `server` 块中添加或漏写 `format` 参数，Nginx 启动不会报错，但 `/status/format/prometheus` 路径不会注册，导致 404 错误。

实操建议：

• 确认 Nginx 编译时已加载模块：nginx -V 2>&1 | grep -o nginx-module-vts，无输出说明未编译进内核
• 在 http 块顶部（早于任何 server）添加：

  vhost_traffic_status_zone;

  vhost_traffic_status_format prometheus;

• vhost_traffic_status_zone 必须存在，否则整个状态模块不生效，连基础 /status 都 404

如何让 /status/format/prometheus 正确返回指标且不暴露敏感信息

该路径默认返回所有虚拟主机+上游+缓存的全量指标，但 Prometheus 抓取时通常只需核心请求量、状态码、响应时间等，且不应暴露域名、后端地址等敏感字段。直接开放原生输出有风险。

实操建议：

• 用 location 显式声明路径，并限制访问来源：

  location /status/format/prometheus {<br> vhost_traffic_status_display; # 必须开启显示<br> vhost_traffic_status_display_format prometheus;<br> allow 127.0.0.1;<br> allow 10.0.0.0/8; # Prometheus 所在网段<br> deny all;<br>}

• 避免在 server 块中重复写 vhost_traffic_status_display_format，它只在 location 级生效，且仅对当前 location 生效
• 若不需要 upstream 指标，可在 http 块中加：

  vhost_traffic_status_filter_by_host off;，减少指标膨胀

nginx-module-vts 输出的 Prometheus 指标命名和含义是否可靠

指标名如 nginx_vts_server_requests_total、nginx_vts_server_request_seconds_total 看似规范，但要注意：它们不是按 Prometheus 官方语义设计的——_total 后缀虽存在，但部分计数器（如按状态码分组的）实际是瞬时值，不是严格单调递增的 Counter；而 _seconds_total 是 Histogram 类型，但桶（bucket）边界固定且不可配，无法满足高精度 P99 分析需求。

实操建议：

• 抓取频率建议 ≥15s，因模块内部采样为秒级聚合，太频繁会导致重复值或突刺
• 关键指标优先用：nginx_vts_server_requests_total{host="example.com",code="200"}，注意 host label 来自 server_name，若用泛域名或 IP 访问，label 值可能为空或不可预期
• 不要依赖 nginx_vts_upstream_requests_total 做服务健康判断——它不包含连接超时、502/503 等 upstream 错误的细分，这类错误被归入 server 级别的 code="5xx"

与官方 nginx-prometheus-exporter 对比，什么时候该换掉 vts

当你需要精确到 upstream 实例粒度的连接数、重试次数、慢请求阈值告警，或要求指标符合 OpenMetrics 规范（如带 exemplar、正确类型标注），nginx-module-vts 就力不从心了。它的优势在于零额外进程、低延迟，劣势是指标维度固化、不可扩展。

实操建议：

• 小流量、静态配置、仅需大盘看板 → 继续用 vts，省资源
• 已接入 Service Mesh 或有精细化 SLO 追踪需求 → 切换 nginx-prometheus-exporter，它通过 stub_status + 自定义解析，能暴露 nginx_upstream_keepalive、nginx_upstream_zombie_requests 等 vts 完全没有的指标
• 迁移时注意：vts 的 host label 对应 exporter 的 server label，但 exporter 默认不打 host，需在 nginx.conf 中用 log_format 注入 $host 字段供其解析

模块本身不维护指标语义一致性，上线后务必用 curl http://localhost/status/format/prometheus 手动检查 label 是否为空、数值是否随请求增长——这是最容易被跳过的验证步骤。