Nginx虚拟主机流量状态模块（nginx-module-vts）使用说明文档（一）

前面的博文 Nginx安装，开箱即用？讲了NG的安装，装完NG，为了拿到各种状态指标，就要对NG做监控。
Github 2.3k的开源项目nginx-module-vts没准真是你需求的。
链接数，qps，1xx、2xx,、3xx、4xx、5xx的响应数，响应耗时，响应时间分布，访问用户国家分布；甚至是基于各种状态的流量控制统统能满足你的需求。
nginx-module-vts具体怎么用？我们还是从官方文档开始撸吧，还是英文的，那就翻译一下吧。
内容有点长，你看到的文档会四篇文档的方式分别出现。这里是第一篇，余下的三篇会在后面分别发出。

Nginx虚拟主机流量状态模块

目录

• 1、版本
• 2、依赖
• 3、兼容性
• 4、状态截图
• 5、安装
• 6、概要
• 7、描述
• 8、计算和间隔

1、版本

本文件描述了2018年6月22日发布的nginx-module-vtsv0.1.18。

2、依赖

• nginx

3、兼容性

• Nginx
  • 1.15.x (最后一次测试：1.15.0)
  • 1.14.x (最后一次测试：1.14.0)
  • 1.13.x (最后一次测试：1.13.12)
  • 1.12.x (最后一次测试 1.12.2)
  • 1.11.x (最后一次测试：1.11.10)
  • 1.10.x (最后一次测试：1.10.3)
  • 1.8.x (最后一次测试：1.8.0)
  • 1.6.x (最后一次测试 1.6.3)
  • 1.4.x (最后一次测试：1.4.7)

早期版本不进行测试。

4、状态截图

5、安装

1. 克隆git存储库。

shell> git clone git://github.com/vozlt/nginx-module-vts.git

2. 通过--add-module=/path/to/nginx-module-vts将该模块添加到构建配置中

3. 构建nginx二进制文件。

4. 安装nginx二进制文件。

6、概要

http {
    vhost_traffic_status_zone;

    ...

    server {

        ...

        location /status {
            vhost_traffic_status_display;
            vhost_traffic_status_display_format html;
        }
    }
}

7、描述

这是一个Nginx模块，提供对虚拟主机状态信息的访问。
它包含当前状态，例如servers, upstreams, caches。
这类似于nginx plus的实时活动监视。
内置的html和旧版本的演示页面也保持一致。

首先，指令vhost_traffic_status_zone是必需的，如果指令vhost_traffic_status_display被设置，可以通过下方式访问：

• /status/format/json
  • 请求/status/format/json将用一个包含当前活动数据的json文档进行响应，以便在实时仪表板和三方监视工具中使用。
• /status/format/html
  • 请求/status/format/html将会用一个内置的内置的html仪表板网页进行响应，该仪表盘的内部请求走/status/format/json。
• /status/format/jsonp
  • 请求/status/format/jsonp将用一个jsonp回调函数进行响应，该函数包含用于实时仪表板和三方监视工具的当前活动数据。
• /status/format/prometheus
  • 请求/status/format/prometheus将用包含当前活动数据的prometheus文档来响应。
• /status/control
  • 请求/status/control将返回基于查询语句字符串重置或删除区域后的JSON文档。更多可以参考Control.

JSON文档包含以下内容：

{
    "hostName": ...,
    "nginxVersion": ...,
    "loadMsec": ...,
    "nowMsec": ...,
    "connections": {
        "active":...,
        "reading":...,
        "writing":...,
        "waiting":...,
        "accepted":...,
        "handled":...,
        "requests":...
    },
    "sharedZones": {
        "name":...,
        "maxSize":...,
        "usedSize":...,
        "usedNode":...
    },
    "serverZones": {
        "...":{
            "requestCounter":...,
            "inBytes":...,
            "outBytes":...,
            "responses":{
                "1xx":...,
                "2xx":...,
                "3xx":...,
                "4xx":...,
                "5xx":...,
                "miss":...,
                "bypass":...,
                "expired":...,
                "stale":...,
                "updating":...,
                "revalidated":...,
                "hit":...,
                "scarce":...
            },
            "requestMsecCounter":...,
            "requestMsec":...,
            "requestMsecs":{
                "times":[...],
                "msecs":[...]
            },
            "requestBuckets":{
                "msecs":[...],
                "counters":[...]
            },
        }
        ...
    },
    "filterZones": {
        "...":{
            "...":{
                "requestCounter":...,
                "inBytes":...,
                "outBytes":...,
                "responses":{
                    "1xx":...,
                    "2xx":...,
                    "3xx":...,
                    "4xx":...,
                    "5xx":...,
                    "miss":...,
                    "bypass":...,
                    "expired":...,
                    "stale":...,
                    "updating":...,
                    "revalidated":...,
                    "hit":...,
                    "scarce":...
                },
                "requestMsecCounter":...,
                "requestMsec":...,
                "requestMsecs":{
                    "times":[...],
                    "msecs":[...]
                },
                "requestBuckets":{
                    "msecs":[...],
                    "counters":[...]
                },
            },
            ...
        },
        ...
    },
    "upstreamZones": {
        "...":[
            {
                "server":...,
                "requestCounter":...,
                "inBytes":...,
                "outBytes":...,
                "responses":{
                    "1xx":...,
                    "2xx":...,
                    "3xx":...,
                    "4xx":...,
                    "5xx":...
                },
                "requestMsecCounter":...,
                "requestMsec":...,
                "requestMsecs":{
                    "times":[...],
                    "msecs":[...]
                },
                "requestBuckets":{
                    "msecs":[...],
                    "counters":[...]
                },
                "responseMsecCounter":...,
                "responseMsec":...,
                "responseMsecs":{
                    "times":[...],
                    "msecs":[...]
                },
                "responseBuckets":{
                    "msecs":[...],
                    "counters":[...]
                },
                "weight":...,
                "maxFails":...,
                "failTimeout":...,
                "backup":...,
                "down":...
            }
            ...
        ],
        ...
    }
    "cacheZones": {
        "...":{
            "maxSize":...,
            "usedSize":...,
            "inBytes":...,
            "outBytes":...,
            "responses":{
                "miss":...,
                "bypass":...,
                "expired":...,
                "stale":...,
                "updating":...,
                "revalidated":...,
                "hit":...,
                "scarce":...
            }
        },
        ...
    }
}

• main
  • nginx版本，nginx运行时间((nowMsec - loadMsec)/1000)
  • nowMsec，loadMsec是毫秒数.
• connections
  • 统计总连接数和总请求数(和nginx的stub_status_module相同)
• sharedZones
  • 统计nginx-module-vts中使用的共享内存信息
• serverZones
  • 统计每个server的流量（in/out）以及请求和响应计数和缓存命中率
  • 统计总流量（in/out）以及总请求和总响应计数（区域名称为*）和总缓存命中率
• filterZones
  • 通过vhost_traffic_status_filter_by_set_key指令过滤统计的server的流量（输入/输出），请求和响应计数以及缓存命中率。
  • 总流量（in/out）以及总请求和总响应计数（区域名称为*）和命中率通过vhost_traffic_status_filter_by_set_key指令过滤。
• upstreamZones
  • 统计每个upstream组中每个server的流量（in/out）以及请求和响应计数
  • nginx.conf中的当前设置（权重，maxfails，failtimeout …）
• cacheZones
  • 使用proxy_cache指令时，每个缓存区域的流量（in/out）和大小（capacity/used）以及命中率。

JSON文档中的overCounts对象主要用于32位系统，如果其值溢出，则将递增1。使用指令vhost_traffic_status_display_format设置默认的输出格式，即json、jsonp、html、prometheus之一。（默认值为json）

流量的计算规则如下：

• ServerZones
  • in += requested_bytes
  • out += sent_bytes
• FilterZones
  • in += requested_bytes via the filter
  • out += sent_bytes via the filter
• UpstreamZones
  • in += requested_bytes via the ServerZones
  • out += sent_bytes via the ServerZones
• cacheZones
  • in += requested_bytes via the ServerZones
  • out += sent_bytes via the ServerZones

所有计算都在Nginx的日志处理阶段中进行。
内部重定向（X-Accel-Redirect或error_page）不在UpstreamZones中计算。

注意：此模块依赖于nginx日志记录系统（NGX_HTTP_LOG_PHASE：nginx http的最后阶段），因此流量可能在某些情况下和实际带宽流量会有所不同。
Websocket以及取消的下载可能是造成差异的原因。
无论access_log指令是on还是off，模块的工作都没有关系。
同样，此模块在access_log off时也可以正常工作。
当使用多个域时，它将设置为server_name指令的第一个域（左侧）。
如果不需要，请参见vhost_traffic_status_filter_by_host, vhost_traffic_status_filter_by_set_key指令。

有关stream流量统计信息请参见以下模块:

• nginx-module-sts
• nginx-module-stream-sts

8、计算和间隔

平均值

所有的平均值目前都是用算术平均值AMM(Arithmetic Mean)基于最新的64 个值来计算的。