装完NG，为了拿到各种状态指标，就要对NG做监控。

Github 2.3k的开源项目nginx-module-vts没准真是你需求的。

链接数，qps，1xx、2xx,、3xx、4xx、5xx的响应数，响应耗时，响应时间分布，访问用户国家分布；甚至是基于各种状态的流量控制统统能满足你的需求。

nginx-module-vts具体怎么用？我们还是从官方文档开始撸吧，还是英文的，那就翻译一下吧。

内容有点长，你看到的文档会四篇文档的方式分别出现。这里是第四篇，第一篇你可以点这里查看，第二篇你可以点这里查看，第三篇你可以点这里查看。

Nginx虚拟主机流量状态模块

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

-	-
语法	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]

凋谢的不是花，萎蔫的是时间；星辰大海，点滴为途。