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

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

Nginx虚拟主机流量状态模块

目录

• 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、作者

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]