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

装完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、计算和间隔
• 9、管控指令（Control）
  • 动态获取流量区域（zones）状态
    • 获取全部区域
    • 获取组区域
    • 获取每个区域
  • 动态重置流量区域
    • 重置全部分区
    • 重置组区域
    • 重置每个分区
  • 动态删除流量区域
    • 删除全部分区
    • 删除组分区
    • 删除每个分区
• 10、设置指令（Set）
• 11、JSON及字段说明
  • 状态中使用的Json
  • Control中使用的Json
• 12、变量
• 13、流量限制
  • 限制server的流量
  • 限制筛选器（filter）的流量
  • 限制上游（upstream）流量
• 14、用例
  • 使用GeoIP计算各个国家的流量
  • 单个存储容量（storage volume）的流量计算
  • 计算单个用户代理（user agent）的流量
  • 为详细的http状态代码计算流量
  • 动态dns的流量计算
  • 排除状态页的流量计算
  • 永久维护统计数据
• 15、自定义
  • 安装模块后进行自定义
  • 在安装模块之前进行自定义
• 16、指令
  • vhost_traffic_status
  • vhost_traffic_status_zone
  • vhost_traffic_status_dump
  • vhost_traffic_status_display
  • vhost_traffic_status_display_format
  • vhost_traffic_status_display_jsonp
  • vhost_traffic_status_display_sum_key
  • vhost_traffic_status_filter
  • vhost_traffic_status_filter_by_host
  • vhost_traffic_status_filter_by_set_key
  • vhost_traffic_status_filter_check_duplicate
  • vhost_traffic_status_filter_max_node
  • vhost_traffic_status_limit
  • vhost_traffic_status_limit_traffic
  • vhost_traffic_status_limit_traffic_by_set_key
  • vhost_traffic_status_limit_check_duplicate
  • vhost_traffic_status_set_by_filter
  • vhost_traffic_status_average_method
  • vhost_traffic_status_histogram_buckets
  • vhost_traffic_status_bypass_limit
  • vhost_traffic_status_bypass_stats
• 17、另请参阅
• 18、待办事项
• 19、捐赠
• 20、作者

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 个值来计算的。

9、管控指令（Control）

control指令能够通过查询字符串重置或删除流量区域。
该请求以JSON文档响应。

• URI 语法
  • /{status_uri}/control?cmd={command}&group={group}&zone={name}

http {

    geoip_country /usr/share/GeoIP/GeoIP.dat;

    vhost_traffic_status_zone;
    vhost_traffic_status_filter_by_set_key $geoip_country_code country::*;

    ...

    server {

        server_name example.org;

        ...

        vhost_traffic_status_filter_by_set_key $geoip_country_code country::$server_name;

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

如果设置如上，则control的uri类似于example.org/status/control。

可用的请求参数如下：

• cmd=\<status|reset|delete>
  • status
    • 它将流量区域（zones）的状态返回为json格式，如status/format/json。
  • reset
    • 重置流量区域（zones）而不删除共享中的节点（nodes）。
  • delete
    • 删除共享内存中的流量区域（zones）。当重新请求时重新创建时。
• group=\<server|filter|upstream@alone|upstream@group|cache|*>
  • server
  • filter
  • upstream@alone
  • upstream@group
  • cache
  • *
• zone=name
  • server
    • name
  • filter
    • filter_group@name
  • upstream@group
    • upstream_group@name
  • upstream@alone
    • @name
  • cache
    • name

动态获取流量区域（zones）状态

与status/format/json相似，只是它可以获得每个区域。

获取全部区域

• 与status/format/json完全相同。
  • /status/control?cmd=status&group=*

获取组区域

• mainZones
  • /status/control?cmd=status&group=server&zone=::main
• serverZones
  • /status/control?cmd=status&group=server&zone=*
• filterZones
  • /status/control?cmd=status&group=filter&zone=*
• upstreamZones
  • /status/control?cmd=status&group=upstream@group&zone=*
• upstreamZones::nogroups
  • /status/control?cmd=status&group=upstream@alone&zone=*
• cacheZones
  • /status/control?cmd=status&group=cache&zone=*

mainZones中是默认状态值，包括hostName、nginxVersion、loadMsec、nowMsec、connections。

获取每个区域

• single zone in serverZones
  • /status/control?cmd=status&group=server&zone=name
• single zone in filterZones
  • /status/control?cmd=status&group=filter&zone=filter_group@name
• single zone in upstreamZones
  • /status/control?cmd=status&group=upstream@group&zone=upstream_group@name
• single zone in upstreamZones::nogroups
  • /status/control?cmd=status&group=upstream@alone&zone=name
• single zone in cacheZones
  • /status/control?cmd=status&group=cache&zone=name

动态重置流量区域

将指定区域的值重置为0。

重置全部分区

• /status/control?cmd=reset&group=*

重置组区域

• serverZones
  • /status/control?cmd=reset&group=server&zone=*
• filterZones
  • /status/control?cmd=reset&group=filter&zone=*
• upstreamZones
  • /status/control?cmd=reset&group=upstream@group&zone=*
• upstreamZones::nogroups
  • /status/control?cmd=reset&group=upstream@alone&zone=*
• cacheZones
  • /status/control?cmd=reset&group=cache&zone=*

重置每个分区

• single zone in serverZones
  • /status/control?cmd=reset&group=server&zone=name
• single zone in filterZones
  • /status/control?cmd=reset&group=filter&zone=filter_group@name
• single zone in upstreamZones
  • /status/control?cmd=reset&group=upstream@group&zone=upstream_group@name
• single zone in upstreamZones::nogroups
  • /status/control?cmd=reset&group=upstream@alone&zone=name
• single zone in cacheZones
  • /status/control?cmd=reset&group=cache&zone=name

动态删除流量区域

删除共享内存中指定的区域。

删除全部分区

• /status/control?cmd=delete&group=*

删除组分区

• serverZones
  • /status/control?cmd=delete&group=server&zone=*
• filterZones
  • /status/control?cmd=delete&group=filter&zone=*
• upstreamZones
  • /status/control?cmd=delete&group=upstream@group&zone=*
• upstreamZones::nogroups
  • /status/control?cmd=delete&group=upstream@alone&zone=*
• cacheZones
  • /status/control?cmd=delete&group=cache&zone=*

删除每个分区

• single zone in serverZones
  • /status/control?cmd=delete&group=server&zone=name
• single zone in filterZones
  • /status/control?cmd=delete&group=filter&zone=filter_group@name
• single zone in upstreamZones
  • /status/control?cmd=delete&group=upstream@group&zone=upstream_group@name
• single zone in upstreamZones::nogroups
  • /status/control?cmd=delete&group=upstream@alone&zone=name
• single zone in cacheZones
  • /status/control?cmd=delete&group=cache&zone=name

10、设置指令（Set）

可以使用vhost_traffic_status_set_by_filter指令分别获取nginx配置中的状态值。
可以获取几乎所有状态值，并将获得的值存储在用户定义的变量（第一个参数）中。

• 指令语法
  • vhost_traffic_status_set_by_filter $variable group/zone/name

http {

    geoip_country /usr/share/GeoIP/GeoIP.dat;

    vhost_traffic_status_zone;
    vhost_traffic_status_filter_by_set_key $geoip_country_code country::*;

    ...
    upstream backend {
        10.10.10.11:80;
        10.10.10.12:80;
    }

    server {

        server_name example.org;

        ...

        vhost_traffic_status_filter_by_set_key $geoip_country_code country::$server_name;

        vhost_traffic_status_set_by_filter $requestCounter server/example.org/requestCounter;
        vhost_traffic_status_set_by_filter $requestCounterKR filter/country::example.org@KR/requestCounter;

        location /backend {
            vhost_traffic_status_set_by_filter $requestCounterB1 upstream@group/backend@10.10.10.11:80/requestCounter;
            proxy_pass http://backend;
        }
    }
}

以上设置如下：

• $requestCounter
  • serverZones -> example.org -> requestCounter
• $requestCounterKR
  • filterZones -> country::example.org -> KR -> requestCounter
• $requestCounterB1
  • upstreamZones -> backend -> 10.0.10.11:80 -> requestCounter

请参见vhost_traffic_status_set_by_filter指令以了解详细用法。

11、JSON及字段说明

以下状态信息以JSON格式提供：

状态中使用的Json

/{status_uri}/format/json

/{status_uri}/control?cmd=status&…

• hostName
  • 主机名。
• nginxVersion
  • nginx的版本。
• loadMsec
  • 以毫秒为单位的处理时间。
• nowMsec
  • 以毫秒为单位的当前时间
• connections
  • active
    • 当前活动的客户端连接数。
  • reading
    • 读取客户端连接的总数。
  • writing
    • 写入客户端连接的总数。
  • waiting
    • 正在等待的客户端连接总数。
  • accepted
    • 接受的客户端连接总数。
  • handled
    • 已处理的客户端连接总数
  • requests
    • 请求请求的客户端连接总数。
• sharedZones
  • name
    • 配置中指定的共享内存的名称。(默认值为：vhost_traffic_status)
  • maxSize
    • 配置中指定的共享内存的最大大小的限制。
  • usedSize
    • 共享内存的当前大小。
  • usedNode
    • 共享内存中当前使用的节点数。可以通过以下公式获得一个节点的近似大小：（usedSize / usedNode）
• serverZones
  • requestCounter
    • 从客户端接收的客户端请求总数。
  • inBytes
    • 从客户端接收的总字节数。
  • outBytes
    • 发送到客户端的总字节数。
  • responses
    • 1xx, 2xx, 3xx, 4xx, 5xx
      • 状态代码为1xx、2xx、3xx、4xx和5xx的响应数。
    • miss
      • 未命中的缓存数。
    • bypass
      • 绕过缓存旁路数。
    • expired
      • 过期的缓存数。
    • stale
      • 失效缓存的数量。
    • updating
      • 缓存更新的次数。
    • revalidated
      • 重新验证的缓存数。
    • hit
      • 缓存命中数。
    • scarce
      • 未达缓存要求的请求次数。
  • requestMsecCounter
    • 累积的请求处理时间（毫秒）。
  • requestMsec
    • 请求处理时间的平均值（毫秒）。
  • requestMsecs
    • times
      • 请求处理时间的时间（毫秒）。
    • msecs
      • 请求处理时间的时间（毫秒）。
  • requestBuckets
    • msecs
      • 由vhost_traffic_status_histogram_buckets指令设置的柱状图的桶的值.
    • counters
      • 每个存储桶段值大于或等于对应请求处理时间的累积值。
• filterZones
  • 它提供了与serverZones相同的字段，只是包含了组名。
• upstreamZones
  • server
    • server地址。
  • requestCounter
    • 转发到此服务器的客户端连接总数。
  • inBytes
    • 从该服务器接收的总字节数。
  • outBytes
    • 发送到此服务器的总字节数。
  • responses
    • 1xx, 2xx, 3xx, 4xx, 5xx
      • 状态代码为1xx、2xx、3xx、4xx和5xx的响应数。
  • requestMsecCounter
    • 包括upstream在内的累计请求处理时间数（毫秒）。
  • requestMsec
    • 包括upstream在内请求处理时间的平均毫秒数。
  • requestMsecs
    • times
      • 请求处理时间的时间（毫秒）。
    • msecs
      • 包括upstream在内请求处理时间的时间（毫秒）。
  • requestBuckets
    • msecs
      • 由vhost_traffic_status_histogram_buckets指令设置的直方图的bucket值。
    • counters
      • 每个存储桶段值大于或等于对应请求处理时间（包括上游）的累积值。
  • responseMsecCounter
    • 仅upstream响应处理时间累加值（毫秒）。
  • responseMsec
    • 仅upstream响应处理时间平均值（毫秒）。
  • responseMsecs
    • times
      • 请求处理时间（毫秒）。
    • msecs
      • 仅upstream响应处理时间平均值（毫秒）。
  • responseBuckets
    • msecs
      • 由vhost_traffic_status_histogram_buckets指令设置的柱状图的存储桶值。
    • counters
      • 仅upstream响应处理时间大于或等于每个存储桶值的累计次数
  • weight
    • server的当前的weight设置。
  • maxFails
    • server的当前的max_fails设置。
  • failTimeout
    • server的当前的fail_timeout设置。
  • backup
    • server的当前的backup设置。
  • down
    • 服务器的当前down设置。
      基本上，这只是ngx_http_upstream_module的server关闭的标记（例如server backend3.example.com down），不是实际的upstream状态。
      如果启用了上游区域指令，它将变为实际状态。
• cacheZones
  • maxSize
    • 配置中指定的最大缓存大小限制。
  • usedSize
    • 当前缓存的大小。
  • inBytes
    • 从缓存接收的字节总数。
  • outBytes
    • 从缓存发送的字节总数。
  • responses
    • miss
      • 未命中的缓存数。
    • bypass
      • 绕过缓存旁路数。
    • expired
      • 过期的缓存数。
    • stale
      • 失效缓存的数量。
    • updating
      • 缓存更新的次数。
    • revalidated
      • 重新验证的缓存数。
    • hit
      • 缓存命中数。
    • scarce
      • 未达缓存要求的请求次数。

Control中使用的Json

/{status_uri}/control?cmd=reset&…

/{status_uri}/control?cmd=delete&…

• processingReturn
  • The result of true or false.
• processingCommandString
  • The requested command string.
• processingGroupString
  • The requested group string.
• processingZoneString
  • The requested zone string.
• processingCounts
  • The actual processing number.

12、变量

提供了以下嵌入式变量：

• $vts_request_counter
  • 从客户端接收的客户端请求总数。
• $vts_in_bytes
  • 从客户端接收的字节总数。
• $vts_out_bytes
  • 发送到客户端的总字节数。
• $vts_1xx_counter
  • 状态代码为1xx的响应数。
• $vts_2xx_counter
  • 状态代码为2xx的响应数。
• $vts_3xx_counter
  • 状态代码为3xx的响应数。
• $vts_4xx_counter
  • 状态代码为4xx的响应数。
• $vts_5xx_counter
  • 状态代码为5xx的响应数。
• $vts_cache_miss_counter
  • 缓存未命中数。
• $vts_cache_bypass_counter
  • 缓存旁路数。
• $vts_cache_expired_counter
  • 缓存已过期数。
• $vts_cache_stale_counter
  • 缓存失效的数量。
• $vts_cache_updating_counter
  • 缓存更新的次数。
• $vts_cache_revalidated_counter
  • 重新验证的缓存数。
• $vts_cache_hit_counter
  • 缓存命中数。
• $vts_cache_scarce_counter
  • 未达缓存要求的请求的数量。
• $vts_request_time_counter
  • 请求处理时间的累计数量。
• $vts_request_time
  • 请求处理的平均时间。

13、流量限制

它能够通过使用指令vhost_traffic_status_limit_traffic来限制每个主机的总流量。
它还可以通过使用指令vhost_traffic_status_limit_traffic_by_set_key来限制所有流量。
当超过限制时，服务器将返回503（服务暂时不可用）错误以响应请求。返回码可以更改。

限制server的流量

http {

    vhost_traffic_status_zone;

    ...

    server {

        server_name *.example.org;

        vhost_traffic_status_limit_traffic in:64G;
        vhost_traffic_status_limit_traffic out:1024G;

        ...
    }
}

• 将*.example.org上的入/出总流量分别限制为64G和1024G。如果启用vhost_traffic_status_filter_by_host指令，则每个域（domain）单独工作。

限制筛选器（filter）的流量

http {
    geoip_country /usr/share/GeoIP/GeoIP.dat;

    vhost_traffic_status_zone;

    ...

    server {

        server_name example.org;

        vhost_traffic_status_filter_by_set_key $geoip_country_code country::$server_name;
        vhost_traffic_status_limit_traffic_by_set_key FG@country::$server_name@US out:1024G;
        vhost_traffic_status_limit_traffic_by_set_key FG@country::$server_name@CN out:2048G;

        ...

    }
}

• 限制example.org上进入美国和中国的总流量分别为1024G和2048G。

限制上游（upstream）流量

http {

    vhost_traffic_status_zone;

    ...

    upstream backend {
        server 10.10.10.17:80;
        server 10.10.10.18:80;
    }

    server {

        server_name example.org;

        location /backend {
            vhost_traffic_status_limit_traffic_by_set_key UG@backend@10.10.10.17:80 in:512G;
            vhost_traffic_status_limit_traffic_by_set_key UG@backend@10.10.10.18:80 in:1024G;
            proxy_pass http://backend;
        }

        ...

    }
}

• 将进入example.org上游后端的每个对等端的总流量分别限制为512G和1024G。

注意： 流量是累积传输或计数器，而不是带宽。

14、用例

它能够使用指令vhost_traffic_status_filter_by_set_key计算用户定义的单个统计信息。

使用GeoIP计算各个国家的流量

http {
    geoip_country /usr/share/GeoIP/GeoIP.dat;

    vhost_traffic_status_zone;
    vhost_traffic_status_filter_by_set_key $geoip_country_code country::*;

    ...

    server {

        ...

        vhost_traffic_status_filter_by_set_key $geoip_country_code country::$server_name;

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

• 计算总服务器组（server groups）的各个国家/地区的流量。
• 计算每个服务器组（server groups）的各个国家/地区的流量。

基本上，国旗图像是HTML内置的。
如果country字符串包含在vhost_traffic_status_filter_by_set_key指令的第二个参数group name中，则启用国家标志图像。

单个存储容量（storage volume）的流量计算

http {
    vhost_traffic_status_zone;

    ...

    server {

        ...

        location ~ ^/storage/(.+)/.*$ {
            set $volume $1;
            vhost_traffic_status_filter_by_set_key $volume storage::$server_name;
        }

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

• 计算与location指令正则表达式匹配的单个存储容量的流量。

计算单个用户代理（user agent）的流量

http {
    vhost_traffic_status_zone;

    map $http_user_agent $filter_user_agent {
        default 'unknown';
        ~iPhone ios;
        ~Android android;
        ~(MSIE|Mozilla) windows;
    }

    vhost_traffic_status_filter_by_set_key $filter_user_agent agent::*;

    ...

    server {

        ...

        vhost_traffic_status_filter_by_set_key $filter_user_agent agent::$server_name;

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

• 单个http_user_agent的流量计算

为详细的http状态代码计算流量

http {
    vhost_traffic_status_zone;

    server {

        ...

        vhost_traffic_status_filter_by_set_key $status $server_name;

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

• 按照详细的http status code计算流量

注意：变量$status 在nginx-(1.3.2, 1.2.2)中可用。

动态dns的流量计算

如果域有多个DNS A记录，则可以使用过滤功能或proxy_pass中的变量计算域的各个ip的流量。

http {
    vhost_traffic_status_zone;

    upstream backend {
        elb.example.org:80;
    }

    ...

    server {

        ...

        location /backend {
            vhost_traffic_status_filter_by_set_key $upstream_addr upstream::backend;
            proxy_pass backend;
        }
    }
}

• 计算域elb.example.org的各个IP的流量。
  如果elb.example.org有多个DNS A记录，将在filterZones中的显示所有ip。
  在上述设置中，NGINX启动或重新加载配置时，它会查询DNS服务器来解析域并将DNS A记录缓存在内存中。
  当DNS管理员更改了DNS A记录时内存中的对应记录并不会更新，除非NGINX 重新启动（restart）或重新加载（reload）。

http {
    vhost_traffic_status_zone;

    resolver 10.10.10.53 valid=10s

    ...

    server {

        ...

        location /backend {
            set $backend_server elb.example.org;
            proxy_pass http://$backend_server;
        }
    }
}

• 计算域elb.example.org的各个IP的流量。
  如果elb.example.org的DNS A记录被更改，则::nogroups中将同时显示旧IP和新IP。
  与第一个上游组（upstream grou）设置不同，即使DNS管理员更改了DNS A记录，第二个设置也能正常工作。

注意： 更多有关NGINX DNS的详细信息请参阅dns-service-discovery-nginx-plus 。

排除状态页的流量计算

http {
    vhost_traffic_status_zone;

    ...

    server {

        ...

        location /status {
            vhost_traffic_status_bypass_limit on;
            vhost_traffic_status_bypass_stats on;
            vhost_traffic_status_display;
            vhost_traffic_status_display_format html;
        }
    }
}

• 从状态流量计算和限制功能中排除/statusuri。
  请参阅以下指令：See the following directives:
  • vhost_traffic_status_bypass_limit
  • vhost_traffic_status_bypass_stats

永久维护统计数据

http {
    vhost_traffic_status_zone;
    vhost_traffic_status_dump /var/log/nginx/vts.db;

    ...

    server {

        ...

    }
}

• 使用vhost_traffic_status_dump指令可以永久地维护统计数据，即使系统已经重新启动或nginx已经重新启动。
  有关详细用法，请参见 vhost_traffic_status_dump 。

15、自定义

安装模块后进行自定义

1. 您需要将字符串更改为status.template.html中的状态uri，如下所示：

   shell> vi share/status.template.html

   var vtsStatusURI = "yourStatusUri/format/json", vtsUpdateInterval = 1000;

2. 然后，自定义status.template.html并将其复制到服务器（server）根目录，如下所示：

   shell> cp share/status.template.html /usr/share/nginx/html/status.html

3. 配置 nginx.conf

   server {
       server_name example.org;
       root /usr/share/nginx/html;
   
       # Redirect requests for / to /status.html
       location = / {
           return 301 /status.html;
       }
   
       location = /status.html {}
   
       # Everything beginning /status (except for /status.html) is
       # processed by the status handler
       location /status {
           vhost_traffic_status_display;
           vhost_traffic_status_display_format json;
       }
   }

4. 访问 html

   http://example.org/status.html

在安装模块之前进行自定义

1. 修改share/status.template.html（不要更改字符串）

2. 重新创建ngx_http_vhost_traffic_status_module_html.h， 如下所示:

   shell> cd util
   shell> ./tplToDefine.sh ../share/status.template.html > ../src/ngx_http_vhost_traffic_status_module_html.h

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

4. 构建nginx二进制文件。

5. 安装nginx二进制文件。

16、指令

vhost_traffic_status

-	-
语法	vhost_traffic_status \<on\	off>
默认值	off
语境	http, server, location

说明： 启用或禁用模块工作。如果设置vhost_traffic_status_zone指令，则会自动启用。

vhost_traffic_status_zone

-	-
语法	vhost_traffic_status_zone [shared:name:size]
默认值	shared:vhost_traffic_status:1m
语境	http

说明： 为共享内存区域设置参数，该区域将保存各种键的状态。缓存在所有工作进程之间共享。
在大多数情况下，nginx-module-vts使用的共享内存大小不会增加太多。
当使用vhost_traffic_status_filter_by_set_key指令时，共享内存的大小会增加很多，但是如果过滤器的键是固定的（例如，国家代码的总数约为240），则不会持续增加。

如果使用vhost_traffic_status_filter_by_set_key指令，请按如下方式设置：

• 默认设置为32M共享内存大小。(vhost_traffic_status_zone shared:vhost_traffic_status:32m)
• 如果出现("ngx_slab_alloc() failed: no memory in vhost_traffic_status_zone")的异常日志，则增加到大于（usedSize*2）

  vhost_traffic_status_dump

-	-
语法	vhost_traffic_status_dump path [period]
默认值	-
语境	http

说明： 启用统计数据存储和还原。
path 是存储统计数据的位置。(例如 /var/log/nginx/vts.db)
period 是一个备份周期。(默认: 60s)
如果nginx被（SIGKILL）信号退出，则不管备份周期如何，它都会立即备份。

vhost_traffic_status_display

-	-
语法	vhost_traffic_status_display
默认值	-
语境	http, server, location

说明： 启用或禁用显示处理程序模块。

vhost_traffic_status_display_format

-	-
语法	vhost_traffic_status_display_format \<json\	html\	jsonp\	prometheus>
默认值	json
语境	http, server, location

说明： 设置显示处理模块输出的格式。
如果设置json，则将用JSON文档响应。
如果设置了html，则将以内置的HTML格式的实时仪表板进行响应。
如果设置jsonp，则将使用JSONP回调函数（默认值：ngx_http_vhost_traffic_status_JSONP_callback）响应。
如果设置prometheus，则将用一个prometheus 文档来响应。

vhost_traffic_status_display_jsonp

-	-
语法	vhost_traffic_status_display_jsonp callback
默认值	ngx_http_vhost_traffic_status_jsonp_callback
语境	http, server, location

说明： 设置JSONP的回调名称。

vhost_traffic_status_display_sum_key

-	-
语法	vhost_traffic_status_display_sum_key name
默认值	*
语境	http, server, location

说明： 在serverZones字段的JSON中设置sum键对应的字符串。默认的sum键字符串是“*”。

vhost_traffic_status_filter

-	-
语法	vhost_traffic_status_filter \<on\	off>
默认值	on
语境	http, server, location

说明： 启用或禁用筛选器功能。

vhost_traffic_status_filter_by_host

-	-
语法	vhost_traffic_status_filter_by_host \<on\	off>
默认值	off
语境	http, server, location

说明： 启用或禁用keys by Host header 字段。
如果设置on同时nginx的server_name指令设置多个或以星号开头的通配符名称，例如“.example.org”，同时请求server使用主机名，如(a|b|c).example.org或.example.org，则json格式的 serverZones将按如下方式打印：

server {
  server_name *.example.org;
  vhost_traffic_status_filter_by_host on;

  ...

}

...
"serverZones": {
    "a.example.org": {
    ...
    },
    "b.example.org": {
    ...
    },
    "c.example.org": {
    ...
    }
    ...
 },
 ...

It provides the same function that set vhost_traffic_status_filter_by_set_key $host.
它与设置vhost_traffic_status_filter_by_set_key $host提供了相同的函数。

vhost_traffic_status_filter_by_set_key

-	-
语法	vhost_traffic_status_filter_by_set_key key [name]
默认值	-
语境	http, server, location

说明： 启用由用户定义的键。
key 是用于计算流量的键字符串。
name 是用于计算流量的分组字符串。
key和name 可以包含变量，如$host，$server_name。
指定第二个参数name时对应的分组信息在filterZones中体现。
如果没有指定第二个参数name，则key的组属于serverZones。
geoip模块示例如下：

server {
  server_name example.org;
  vhost_traffic_status_filter_by_set_key $geoip_country_code country::$server_name;

  ...

}

...
"serverZones": {
...
},
"filterZones": {
    "country::example.org": {
        "KR": {
            "requestCounter":...,
            "inBytes":...,
            "outBytes":...,
            "responses":{
                "1xx":...,
                "2xx":...,
                "3xx":...,
                "4xx":...,
                "5xx":...,
                "miss":...,
                "bypass":...,
                "expired":...,
                "stale":...,
                "updating":...,
                "revalidated":...,
                "hit":...,
                "scarce":...
            },
            "requestMsecCounter":...,
            "requestMsec":...,
            "requestMsecs":{
                "times":[...],
                "msecs":[...]
            },
        },
        "US": {
        ...
        },
        ...
    },
    ...
},
...

vhost_traffic_status_filter_check_duplicate

-	-
语法	vhost_traffic_status_filter_check_duplicate \<on\	off>
默认值	on
语境	http, server, location

说明： 启用或禁用vhost_traffic_status_filter_by_set_key的重复数据删除。
如果启用此选项，则在每个指令（http、server、location）中只处理一个重复值（key + name）。

vhost_traffic_status_filter_max_node

-	-
语法	vhost_traffic_status_filter_max_node number [string …]
默认值	0
语境	http

说明： 基于指定的number和string参数启用筛选器大小限制。
如果超过制定的number，则通过LRU 算法删除现有节点。
number参数是将限制的节点的大小。默认值0不限制过滤器。
一个节点是JSON文档中filterZones中的一个对象。
string参数匹配在vhost_traffic_status_filter_by_set_key指令中设置的组字符串对应的值。
即使只有第一部分匹配，匹配也是成功的，就像正则表达式/^string.*/。
默认情况下，如果不设置string参数，则它将应用于所有的筛选器。

例如：

$ vi nginx.conf

http {

    geoip_country /usr/share/GeoIP/GeoIP.dat;

    vhost_traffic_status_zone;

    # The all filters are limited to a total of 16 nodes.
    # vhost_traffic_status_filter_max_node 16

    # The `/^uris.*/` and `/^client::ports.*/` group string patterns are limited to a total of 64 nodes.
    vhost_traffic_status_filter_max_node 16 uris client::ports

    ...

    server {

        server_name example.org;

        ...

        vhost_traffic_status_filter_by_set_key $uri uris::$server_name;
        vhost_traffic_status_filter_by_set_key $remote_port client::ports::$server_name;
        vhost_traffic_status_filter_by_set_key $geoip_country_code country::$server_name;

    }
}

$ for i in {0..1000}; do curl -H 'Host: example.org' -i "http://localhost:80/test$i"; done

在上面的例子中，/^uris.*/和/^client::ports.*/分组字符串被限制为总共16个节点。其他过滤器，如country::.*不受限制。

vhost_traffic_status_limit

-	-
语法	vhost_traffic_status_limit \<on\	off>
默认值	on
语境	http, server, location

说明： 启用或禁用限制功能。

vhost_traffic_status_limit_traffic

-	-
语法	vhost_traffic_status_limit_traffic member:size [code]
默认值	-
语境	http, server, location

说明： 为指定member启用流量限制。
参数member是限制流量的统计粒度字符串。
参数size是限制流量的大小字符串，单位（k/m/g）。
参数code是请求被拒绝时候的响应代码。(默认响应码:503）

可用的member字符串如下

• request
  • 从客户端接收的请求总数。
• in
  • 从客户端接收的总字节数。
• out
  • 发送到客户端的总字节数。
• 1xx
  • 状态代码为1xx的响应数。
• 2xx
  • 状态代码为2xx的响应数。
• 3xx
  • 状态代码为3xx的响应数。
• 4xx
  • 状态代码为4xx的响应数。
• 5xx
  • 状态代码为5xx的响应数。
• cache_miss
  • 缓存未命中数。
• cache_bypass
  • 缓存旁路数。
• cache_expired
  • 缓存已过期数。
• cache_stale
  • 缓存失效的数量。
• cache_updating
  • 缓存更新的次数。
• cache_revalidated
  • 重新验证的缓存数。
• cache_hit
  • 缓存命中数
• cache_scarce
  • 未达缓存要求的请求的数量。

vhost_traffic_status_limit_traffic_by_set_key

-	-
语法	vhost_traffic_status_limit_traffic_by_set_key key member:size [code]
默认值	-
语境	http, server, location

说明： 针对制定的key和member进行流量控制
参数key是限制流量的key字符串
参数member是限制流量的member字符串
参数size是流量的限制的大小字符串，单位（k/m/g）。
参数code是请求被拒绝时候的响应代码。(默认响应码:503）

key 语法如下：

• group@[subgroup@]name

可用的group 字符串如下：

• NO
  • server group。
• UA
  • upstream alone group。
• UG
  • The group of upstream group.(use subgroup)
• CC
  • cache group。
• FG
  • filter group。(use subgroup)

可用的member字符串如下：

• request
  • 从客户端接收的请求总数。
• in
  • 从客户端接收的总字节数。
• out
  • 发送到客户端的总字节数。
• 1xx
  • 状态代码为1xx的响应数。
• 2xx
  • 状态代码为2xx的响应数。
• 3xx
  • 状态代码为3xx的响应数。
• 4xx
  • 状态代码为4xx的响应数。
• 5xx
  • 状态代码为5xx的响应数。
• cache_miss
  • 缓存未命中数。
• cache_bypass
  • 缓存旁路数。
• cache_expired
  • 缓存已过期数。
• cache_stale
  • 缓存失效的数量。
• cache_updating
  • 缓存更新的次数。
• cache_revalidated
  • 重新验证的缓存数。
• cache_hit
  • 缓存命中数
• cache_scarce
  • 未达缓存要求的请求的数量。

这里的member与vhost_traffic_status_limit_traffic指令下的member相同。

vhost_traffic_status_limit_check_duplicate

-	-
语法	vhost_traffic_status_limit_check_duplicate \<on\	off>
默认值	on
语境	http, server, location

说明： 启用或禁用vhost_traffic_status_limit_by_set_key的重复数据删除。
如果启用此选项，则只处理每个指令（http、server、location）中的重复值（member或者key + member）中的一个。

vhost_traffic_status_set_by_filter

-	-
语法	vhost_traffic_status_set_by_filter $variable group/zone/name
默认值	-
语境	http, server, location, if

说明： 获取存储在共享内存中的指定状态值。
它可以获取几乎所有的状态值，并将获得的值存储在第一个参数$variable中。

• group
  • server
  • filter
  • upstream@alone
  • upstream@group
  • cache
• zone
  • server
    • name
  • filter
    • filter_group@name
  • upstream@group
    • upstream_group@name
  • upstream@alone
    • @name
  • cache
    • name
• name
  • requestCounter
    • 从客户端接收的客户端请求总数。
  • requestMsecCounter
    • 累积的请求处理时间（毫秒）。
  • requestMsec
    • 请求处理时间的平均值（毫秒）
  • responseMsecCounter
    • 仅上游响应处理时间的累积数（毫秒）。
  • responseMsec
    • 仅上游响应处理时间的平均值（毫秒）。
  • inBytes
    • 从客户端接收的总字节数。
  • outBytes
    • 发送到客户端的总字节数
  • 1xx, 2xx, 3xx, 4xx, 5xx
    • 状态代码为1xx、2xx、3xx、4xx和5xx的响应数。
  • cacheMaxSize
    • 配置中指定的缓存的最大大小限制。
  • cacheUsedSize
    • 缓存的当前大小。
  • cacheMiss
    • 缓存未命中数。
  • cacheBypass
    • 缓存旁路数。
  • cacheExpired
    • 缓存过期数。
  • cacheStale
    • 缓存失效的数量。
  • cacheUpdating
    • 缓存更新的次数。
  • cacheRevalidated
    • 重新验证的缓存数。
  • cacheHit
    • 缓存命中的数量
  • cacheScarce
    • 未达缓存要求的请求的数量。
  • weight
    • server的当前权重值。
  • maxFails
    • server的当前max_fails设置。
  • failTimeout
    • server的当前fail_timeout设置。
  • backup
    • server的当前备份设置(0或1)
  • down
    • server的当前下线设置(0或1)

注意：name区分大小写。所有返回值都采用整数类型。

例如：

• serverZones中的请求计数器设置
  • vhost_traffic_status_set_by_filter $requestCounter server/example.org/requestCounter
• filterZones中的请求计数器设置
  • vhost_traffic_status_set_by_filter $requestCounter filter/country::example.org@KR/requestCounter
• upstreamZones中的请求计数器设置
  • vhost_traffic_status_set_by_filter $requestCounter upstream@group/backend@10.10.10.11:80/requestCounter
• upstreamZones::nogroups中的请求计数器设置
  • vhost_traffic_status_set_by_filter $requestCounter upstream@alone/10.10.10.11:80/requestCounter
• cacheZones中的命中率计数器设置
  • vhost_traffic_status_set_by_filter $cacheHit cache/my_cache_name/cacheHit

vhost_traffic_status_average_method

-	-
语法	vhost_traffic_status_average_method <AMM或WMA> [period]
默认值	AMM 60s
语境	http, server, location

说明： 设置计算响应处理时间平均值的公式和方法。
The period is an effective time of the values used for the average calculation.(Default: 60s)
参数period用来平均值的有效期(默认值: 60s)。
如果period设置为0，则忽略有效时间。在这种情况下，即使没有请求并且经过一段时间后，也会显示最后的平均值。
在JSON中，对应的值是requestMsec和responseMsec。

• AMM
  • AMMarithmetic mean 是算术平均数。
• WMA
  • WMAweighted moving average 是加权移动平均数。

vhost_traffic_status_histogram_buckets

-	-
语法	vhost_traffic_status_histogram_buckets second …
默认值	-
语境	http, server, location

说明： 设置要在直方图中使用的观察桶。
默认情况下，如果不设置此指令，它将不起作用。
参数second可以用小数位表示，最小值为0.001（1ms）。
桶的最大尺寸为32。如果这个值不够，请在src/ngx_http_vhost_traffic_status_node.h中更改NGX_HTTP_VHOST_TRAFFIC_STATUS_DEFAULT_BUCKET_LEN对应的值。

例如：

• vhost_traffic_status_histogram_buckets 0.005 0.01 0.05 0.1 0.5 1 5 10
  • 观察桶是[5ms 10ms 50ms 1s 5s 10s]。
• vhost_traffic_status_histogram_buckets 0.005 0.01 0.05 0.1
  • 观察桶是[5ms 10ms 50ms 1s]。

注意： 默认情况下，如果不设置此指令，则直方图统计不起作用。
使用指令vhost_traffic_status_dump恢复的直方图不受指令vhost_traffic_status_histogram_buckets对存储桶的更改的影响。
因此，在通过vhost_traffic_status_histogram_buckets指令更改存储桶之前，必须首先删除zone或dump文件。
与上面类似，在第一次使用直方图时也需要删除dump文件。

vhost_traffic_status_bypass_limit

-	-
语法	vhost_traffic_status_bypass_limit \<on\	off>
默认值	off
语境	http, server, location

说明： 启用或禁用绕过vhost_traffic_status_limit指令。
如果启用此选项，将绕过限制功能。如果通过/status访问状态网页，而希望不考虑vhost_traffic_status_limit指令对它的限制，则这一点非常有用，使用如下的配置：

http {
    vhost_traffic_status_zone;

    ...

    server {

        ...

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

vhost_traffic_status_bypass_stats

-	-
语法	vhost_traffic_status_bypass_stats \<on\	off>
默认值	off
语境	http, server, location

说明： 启用或禁用绕过vhost_traffic_status。
如果启用此选项，将绕过流量状态统计功能。也就是说，它被排除在流量状态统计之外。
如果需要在像/status这样的状态网页中忽略请求，可以使用如下的设置：

http {
    vhost_traffic_status_zone;

    ...

    server {

        ...

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

17、另请参阅

• Stream traffic status

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

• Prometheus

  • nginx-vts-exporter

• System protection

  • nginx-module-sysguard

18、待办事项

19、捐赠

20、作者

YoungJoo.Kim(김영주) [vozltx@gmail.com]