Nginx vts采集

nginx-module-vts 可以暴露比 stub_status 更丰富的 Nginx 运行指标，适合需要按 vhost、upstream、状态码等维度观察流量和请求质量的场景。本文说明如何添加 vts 模块、配置 /vts_status 状态页，并用 Categraf input.prometheus 插件采集 Prometheus 格式指标。

因为 Nginx 开启模块或添加模块通常都需要重新编译，本文流程建议先在测试环境验证。示例基于 CentOS 7.2、Nginx 1.20.2 和 /etc/nginx/third-modules/ 模块目录，生产环境请按实际路径调整。

核心要点

vts 通过第三方模块 nginx-module-vts 提供更完整的 Nginx 指标视图。
Nginx 主配置中需要启用 vhost_traffic_status_zone，并按需配置 vhost_traffic_status_filter。
/vts_status/format/prometheus 可以直接输出 Prometheus 格式指标，因此可使用 Categraf input.prometheus 采集。
如果只需要基础连接指标，stub_status 更轻；如果需要更完整的 vhost 和 upstream 指标，vts 更合适。

测试环境

操作系统: CentOS 7.2

安装依赖

这些依赖是我这个环境下的, 你可以根据自己的环境安装对应的依赖。

yum install -y patch
yum install -y gd gd-devel
yum install -y libxslt-devel
yum install perl-ExtUtils-Embed

第三方依赖

下载第三方依赖，并解压到目录/etc/nginx/third-modules/下。

https://github.com/vozlt/nginx-module-vts

下载nginx源码

wget http://nginx.org/download/nginx-1.20.2.tar.gz
tar zxvf nginx1.20.2.tar.gz
cd nginx-1.20.2

编译nginx

感谢@Jeff的细心整理。

./configure \
--with-ld-opt="-Wl,-rpath,/usr/local/lib" \
--prefix=/usr/share/nginx \
--sbin-path=/usr/sbin/nginx \
--modules-path=/usr/lib64/nginx/modules \
--conf-path=/etc/nginx/nginx.conf \
--error-log-path=/var/log/nginx/error.log \
--http-log-path=/var/log/nginx/access.log \
--http-client-body-temp-path=/var/lib/nginx/tmp/client_body \
--http-proxy-temp-path=/var/lib/nginx/tmp/proxy \
--http-fastcgi-temp-path=/var/lib/nginx/tmp/fastcgi \
--http-uwsgi-temp-path=/var/lib/nginx/tmp/uwsgi \
--http-scgi-temp-path=/var/lib/nginx/tmp/scgi \
--pid-path=/var/run/nginx.pid \
--lock-path=/run/lock/subsys/nginx \
--user=nginx \
--group=nginx \
--with-compat \
--with-threads \
--with-http_addition_module \
--with-http_auth_request_module \
--with-http_dav_module \
--with-http_flv_module \
--with-http_gunzip_module \
--with-http_gzip_static_module \
--with-http_mp4_module \
--with-http_random_index_module \
--with-http_realip_module \
--with-http_secure_link_module \
--with-http_slice_module \
--with-http_ssl_module \
--with-http_stub_status_module \
--with-http_sub_module \
--with-http_v2_module \
--with-mail \
--with-mail_ssl_module \
--with-stream \
--with-stream_realip_module \
--with-stream_ssl_module \
--with-stream_ssl_preread_module \
--with-select_module \
--with-poll_module \
--with-file-aio \
--with-http_xslt_module=dynamic \
--with-http_image_filter_module=dynamic \
--with-http_perl_module=dynamic \
--with-stream=dynamic \
--with-mail=dynamic \
--with-http_xslt_module=dynamic \
--add-module=/etc/nginx/third-modules/nginx-module-vts

验证

至此编译完成，输入nginx -V查看编译参数，如果有以下参数则表示编译成功。

--add-module=/etc/nginx/third-modules/nginx-module-vts

vts 配置

进入 /etc/nginx，编辑 nginx.conf 输入以下内容。这里的关键配置是 vhost_traffic_status_zone，它用于启用 vts 共享内存统计区。

user  nginx;
worker_processes  1;

events {
    worker_connections  1024;
}

http {
    include       mime.types;
    default_type  application/octet-stream;
	vhost_traffic_status_zone;
    vhost_traffic_status_filter on;
    vhost_traffic_status_filter_by_set_key $status $server_name;

    sendfile        on;

    keepalive_timeout  65;
    include conf.d/*.conf;
}

创建 conf.d 目录，编辑一个 test.conf 输入以下内容。/vts_status 用于查看状态页，后续 Prometheus 格式指标从 /vts_status/format/prometheus 获取。

upstream test {
    server 127.0.0.1:18788 weight=10 max_fails=2 fail_timeout=5s;
}

server {
        listen 80;
        server_name 192.168.11.201;

		location /vts_status {
			vhost_traffic_status_display;
            vhost_traffic_status_display_format html;
        }

		location / {
                        add_header Content-Type text/plain;
                        return 200 "User-agent: *\nDisallow: /\n";
		}

		location /test {
            proxy_pass_header Authorization;
            proxy_pass_header Accept;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_set_header X-Scheme $scheme;
            proxy_set_header Authorization $http_authorization;
            proxy_set_header Accept $http_accept;
            proxy_pass http://test;
		}
}

启动nginx

  nginx -t # 检查配置文件
  nginx #启动nginx

访问 http://192.168.11.201/vts_status 查看状态

Nginx vts status

categraf input.prometheus插件

配置 conf/input.prometheus/nginx.toml 内容如下

[[instances]]
urls = [
  "http://192.168.11.201/vts_status/format/prometheus",
]

url_label_key = "instance"
url_label_value = "{{.Host}}"

启动 Categraf 测试，可以看到已经采集到指标。

Nginx vts 指标采集

vts 指标比较全面，推荐在需要更细粒度 Nginx 监控时使用 vts 方式采集。

方案	指标丰富度	典型用途	本文对应插件
stub status	基础	连接数、请求数、读写等待状态	`input.nginx`
upstream check	中等	upstream 后端健康检查	`input.nginx_upstream_check`
vts	较全面	vhost、upstream、状态码等维度监控	`input.prometheus`

vts 输出 Prometheus 格式指标后，可以直接复用 Prometheus 生态中的采集、告警和大盘能力。需要注意的是，状态页同样建议只对采集器开放，不建议暴露到公网。

大盘链接

根据指标整理的监控大盘见 https://github.com/flashcatcloud/categraf/blob/main/inputs/nginx_vts/dashboards.json

常见问题

Q1：为什么选择 input.prometheus，而不是专门的 Nginx 插件？ A：vts 可以输出 Prometheus 格式指标，input.prometheus 直接抓取 /vts_status/format/prometheus 即可，配置更通用。

Q2：vhost_traffic_status_filter_by_set_key $status $server_name; 有什么作用？ A：本文示例用它按状态码和 server_name 维度组织统计信息，便于后续查看不同虚拟主机与状态码相关指标。

Q3：vts 是否一定优于 stub status？ A：不一定。vts 指标更丰富，但模块和配置也更多。只做基础 Nginx 存活和连接状态监控时，stub_status 更简单；需要细分维度时再选择 vts。

小结

Nginx vts 采集适合希望获得更完整 Nginx 指标视图的团队。本文流程的关键路径是：编译加入 nginx-module-vts，在 Nginx 中启用 vts 状态页，再用 Categraf input.prometheus 抓取 Prometheus 格式指标。这样可以在不改业务代码的前提下获得更细的 Nginx 运行观测数据。