Nginx流服务器流量状态模块
Nginx stream server traffic status module
This document describes nginx-module-sts v0.1.1 released on 04 Jul 2018.
Earlier versions does not work.
Clone the git repository.
shell> git clone git://github.com/vozlt/nginx-module-sts.git
shell> git clone git://github.com/vozlt/nginx-module-stream-sts.git
Add the module to the build configuration by adding
--with-stream--add-module=/path/to/nginx-module-sts--add-module=/path/to/nginx-module-stream-sts
Build the nginx binary.
Install the nginx binary.
http {stream_server_traffic_status_zone;...server {...location /status {stream_server_traffic_status_display;stream_server_traffic_status_display_format html;}}}stream {server_traffic_status_zone;...server {...}}
This is an Nginx module that provides access to stream server traffic status information.
This is a porting version of the nginx-module-vts to the NGINX “stream” subsystem so as to support the same features in nginx-module-vts.
It contains the current status such as servers, upstreams, user-defined filter.
First of all, It is required both the directive server_traffic_status_zone in stream block and stream_server_traffic_status_zone in http block, and then if the directive stream_server_traffic_status_display is set, can be access to as follows:
/status/format/json, will respond with a JSON document containing the current activity data for using in live dashboards and third-party monitoring tools./status/format/html, will respond with the built-in live dashboard in HTML that requests internally to /status/format/json./status/format/jsonp, will respond with a JSONP callback function containing the current activity data for using in live dashboards and third-party monitoring tools. /status/format/prometheus, will respond with a prometheus document containing the current activity data. /status/control, will respond with a JSON document after it reset or delete zones through a query string. See the Control.JSON document contains as follows:
{"hostName": ...,"nginxVersion": ...,"loadMsec": ...,"nowMsec": ...,"connections": {"active":...,"reading":...,"writing":...,"waiting":...,"accepted":...,"handled":...,"requests":...},"sharedZones": {"name":...,"maxSize":...,"usedSize":...,"usedNode":...},"streamServerZones": {"...":{"port":...,"protocol":...,"connectCounter":...,"inBytes":...,"outBytes":...,"responses":{"1xx":...,"2xx":...,"3xx":...,"4xx":...,"5xx":...,},"sessionMsecCounter":...,"sessionMsec":...,"sessionMsecs":{"times":[...],"msecs":[...]},"sessionBuckets":{"msecs":[...],"counters":[...]}}...},"streamFilterZones": {"...":{"...":{"port":...,"protocol":...,"connectCounter":...,"inBytes":...,"outBytes":...,"responses":{"1xx":...,"2xx":...,"3xx":...,"4xx":...,"5xx":...,},"sessionMsecCounter":...,"sessionMsec":...,"sessionMsecs":{"times":[...],"msecs":[...]},"sessionBuckets":{"msecs":[...],"counters":[...]}},...},...},"streamUpstreamZones": {"...":[{"server":...,"connectCounter":...,"inBytes":...,"outBytes":...,"responses":{"1xx":...,"2xx":...,"3xx":...,"4xx":...,"5xx":...},"sessionMsecCounter":...,"sessionMsec":...,"sessionMsecs":{"times":[...],"msecs":[...]},"sessionBuckets":{"msecs":[...]"counters":[...]},"uSessionMsecCounter":...,"uSessionMsec":...,"uSessionMsecs":{"times":[...],"msecs":[...]},"uSessionBuckets":{"msecs":[...]"counters":[...]},"uConnectMsecCounter":...,"uConnectMsec":...,"uConnectMsecs":{"times":[...],"msecs":[...]},"uConnectBuckets":{"msecs":[...]"counters":[...]},"uFirstByteMsecCounter":...,"uFirstByteMsec":...,"uFirstByteMsecs":{"times":[...],"msecs":[...]},"uFirstByteBuckets":{"msecs":[...]"counters":[...]},"weight":...,"maxFails":...,"failTimeout":...,"backup":...,"down":...}...],...}}
*) and hit ratioserver_traffic_status_filter_by_set_key directive*) and hit ratio filtered through the server_traffic_status_filter_by_set_key directiveThe directive stream_server_traffic_status_display_format sets the default ouput format that is one of json,jsonp,html,prometheus. (Default: json)
Traffic calculation as follows:
All calculations are working in log processing phase of Nginx.
Caveats: this module relies on nginx logging system(NGX_STREAM_LOG_PHASE:last phase of the nginx stream), so the traffic may be
in certain cirumstances different that real bandwidth traffic.
Websocket, canceled downloads may be cause of inaccuracies.
The working of the module doesn’t matter at all whether the access_log directive “on” or “off”.
Again, this module works well on “access_log off”.
It is able to reset or delete traffic zones through a query string.
The request responds with a JSON document.
{status_uri}/control?cmd={command}&group={group}&zone={name}
http {stream_server_traffic_status_zone;...server {server_name example.org;...location /status {stream_server_traffic_status_display;stream_server_traffic_status_display_format html;}} }}stream {geoip_country /usr/share/GeoIP/GeoIP.dat;server_traffic_status_zone;server_traffic_status_filter_by_set_key $geoip_country_code country::*;server {...}...}
If it set as above, then the control uri is like example.org/status/control.
The available request arguments are as follows:
status|reset|delete>status/format/json.This is similar to the status/format/json except that it can get each zones.
status/format/json.namefilter_group@nameupstream_group@namenameIt reset the values of specified zones to 0.
namefilter_group@nameupstream_group@namenameIt delete the specified zones in shared memory.
namefilter_group@nameupstream_group@namenameThe following status information is provided in the JSON format:
/{status_uri}/format/json
/{status_uri}/control?cmd=status&…
stream_server_traffic_status)server_traffic_status_histogram_buckets directive.streamServerZones except that it included group names.server_traffic_status_histogram_buckets directive.server_traffic_status_histogram_buckets directive.server_traffic_status_histogram_buckets directive.server_traffic_status_histogram_buckets directive.weight setting of the server.max_fails setting of the server.fail_timeout setting of the server.backup setting of the server.down setting of the server./{status_uri}/control?cmd=reset&…
/{status_uri}/control?cmd=delete&…
The following embedded variables are provided in stream block:
It is able to limit total traffic per each server by using the directiveserver_traffic_status_limit_traffic.
It also is able to limit all traffic by using the directiveserver_traffic_status_limit_traffic_by_set_key.
When the limit is exceeded, the server will return the 503
(Service Temporarily Unavailable) error in reply to a request.
The return code can be changeable.
stream {server_traffic_status_zone;...server {listen 1981;server_traffic_status_limit_traffic in:64G;server_traffic_status_limit_traffic out:1024G;...}}
1981/tcp to 64G and 1024G respectively.
stream {geoip_country /usr/share/GeoIP/GeoIP.dat;server_traffic_status_zone;...server {listen 1981;server_traffic_status_filter_by_set_key $geoip_country_code country::$server_addr;server_traffic_status_limit_traffic_by_set_key FG@country::$server_addr@US out:1024G;server_traffic_status_limit_traffic_by_set_key FG@country::$server_addr@CN out:2048G;...}}
example.org to 1024G and 2048G respectively.
stream {server_traffic_status_zone;...upstream backend {server 10.10.10.17:80;server 10.10.10.18:80;}server {listen 1981;server_traffic_status_limit_traffic_by_set_key UG@backend@10.10.10.17:80 in:512G;server_traffic_status_limit_traffic_by_set_key UG@backend@10.10.10.18:80 in:1024G;proxy_pass backend;...}}
1981/tcp to 512G and 1024G per each peer.Caveats: Traffic is the cumulative transfer or counter, not a bandwidth.
It is able to calculate the user defined individual stats by using the directive server_traffic_status_filter_by_set_key.
stream {geoip_country /usr/share/GeoIP/GeoIP.dat;server_traffic_status_zone;server_traffic_status_filter_by_set_key $geoip_country_code country::*;...server {...server_traffic_status_filter_by_set_key $geoip_country_code country::$server_addr:$server_port;}}
Basically, country flags image is built-in in HTML.
The country flags image is enabled if the country string is included
in group name which is second argument of server_traffic_status_filter_by_set_key directive.
You need to change the {{uri}} string to your status uri in status.template.html as follows:
shell> vi share/status.template.html
var vtsStatusURI = "yourStatusUri/format/json", vtsUpdateInterval = 1000;
And then, customizing and copy status.template.html to server root directory as follows:
shell> cp share/status.template.html /usr/share/nginx/html/status.html
Configure nginx.conf
server {server_name example.org;root /usr/share/nginx/html;# Redirect requests for / to /status.htmllocation = / {return 301 /status.html;}location = /status.html {}# Everything beginning /status (except for /status.html) is# processed by the status handlerlocation /status {stream_server_traffic_status_display;stream_server_traffic_status_display_format json;}}
Access to your html.
http://example.org/status.html
Modify share/status.template.html (Do not change {{uri}} string)
Recreate the ngx_http_stream_server_traffic_status_module_html.h as follows:
shell> cd utilshell> ./tplToDefine.sh ../share/status.template.html > ../src/ngx_http_stream_server_traffic_status_module_html.h
Add the module to the build configuration by adding
--add-module=/path/to/nginx-module-sts--add-module=/path/to/nginx-module-stream-sts
Build the nginx binary.
Install the nginx binary.
| - | - | |
|---|---|---|
| Syntax | stream_server_traffic_status \<on\ | off> |
| Default | off | |
| Context | http, server, location |
Description: Enables or disables the module working.
If you set stream_server_traffic_status_zone directive, is automatically enabled.
| - | - |
|---|---|
| Syntax | stream_server_traffic_status_zone [shared:name] |
| Default | shared:stream_server_traffic_status |
| Context | http |
Description: Sets parameters for a shared memory zone specified by server_traffic_status_zone
directive in stream block.Caveats: The name must be same as specified by server_traffic_status_zone.
| - | - |
|---|---|
| Syntax | stream_server_traffic_status_display |
| Default | - |
| Context | http, server, location |
Description: Enables or disables the module display handler.
| - | - | |||
|---|---|---|---|---|
| Syntax | stream_server_traffic_status_display_format \<json\ | html\ | jsonp\ | prometheus> |
| Default | json | |||
| Context | http, server, location |
Description: Sets the display handler’s output format.
If you set json, will respond with a JSON document.
If you set html, will respond with the built-in live dashboard in HTML.
If you set jsonp, will respond with a JSONP callback function(default: ngx_http_stream_server_traffic_status_jsonp_callback).
If you set prometheus, will respond with a prometheus document.
| - | - |
|---|---|
| Syntax | stream_server_traffic_status_display_jsonp callback |
| Default | ngx_http_stream_server_traffic_status_jsonp_callback |
| Context | http, server, location |
Description: Sets the callback name for the JSONP.
| - | - | |
|---|---|---|
| Syntax | stream_server_traffic_status_average_method \<AMM\ | WMA> [period] |
| Default | AMM 60s | |
| Context | http, server, location |
Description: Sets the method which is a formula that calculate the average of response processing times.
The period is an effective time of the values used for the average calculation.(Default: 60s)
If period set to 0, effective time is ignored.
In this case, the last average value is displayed even if there is no requests and after the elapse of time.
The corresponding values are sessionMsec, uSessionMsec, uConnectMsec, uFirstByteMsec in JSON.
| - | - | |
|---|---|---|
| Syntax | server_traffic_status \<on\ | off> |
| Default | off | |
| Context | stream, server |
Description: Enables or disables the module working.
If you set server_traffic_status_zone directive, is automatically enabled.
| - | - |
|---|---|
| Syntax | server_traffic_status_zone [shared:name:size] |
| Default | shared 1m |
| Context | stream |
Description: Sets parameters for a shared memory zone that will keep states for various keys.
The cache is shared between all worker processes.
| - | - | |
|---|---|---|
| Syntax | server_traffic_status_filter \<on\ | off> |
| Default | on | |
| Context | stream, server |
Description: Enables or disables the filter features.
| - | - |
|---|---|
| Syntax | server_traffic_status_filter_by_set_key key [name] |
| Default | - |
| Context | stream, server |
Description: Enables the keys by user defined variable.
The key is a key string to calculate traffic.
The name is a group string to calculate traffic.
The key and name can contain variables such as $host, $server_addr, $server_port.
The name‘s group belongs to streamFilterZones if specified.
The key‘s group belongs to streamServerZones if not specified second argument name.
The example with geoip module is as follows:
stream {...server {listen 1981;server_traffic_status_filter_by_set_key $geoip_country_code country::$server_addr:$server_port;...}}
..."streamServerZones": {...},"streamFilterZones": {"country::example.org": {"KR": {"port":...,"protocol":...,"connectCounter":...,"inBytes":...,"outBytes":...,"responses":{"1xx":...,"2xx":...,"3xx":...,"4xx":...,"5xx":...,},"sessionMsec":..."sessionMsecs":{"times":[...],"msecs":[...]},},},"US": {...},...},...},...
| - | - | |
|---|---|---|
| Syntax | server_traffic_status_filter_check_duplicate \<on\ | off> |
| Default | on | |
| Context | stream, server |
Description: Enables or disables the deduplication of server_traffic_status_filter_by_set_key.
It is processed only one of duplicate values(key + name) in each directives(stream, server) if this option is enabled.
| - | - | |
|---|---|---|
| Syntax | server_traffic_status_limit \<on\ | off> |
| Default | on | |
| Context | stream, server |
Description: Enables or disables the limit features.
| - | - |
|---|---|
| Syntax | server_traffic_status_limit_traffic member:size [code] |
| Default | - |
| Context | stream, server |
Description: Enables the traffic limit for specified member.
The member is a member string to limit traffic.
The size is a size(k/m/g) to limit traffic.
The code is a code to return in response to rejected requests.(Default: 503)
The available member strings are as follows:
| - | - |
|---|---|
| Syntax | server_traffic_status_limit_traffic_by_set_key key member:size [code] |
| Default | - |
| Context | stream, server |
Description: Enables the traffic limit for specified key and member.
The key is a key string to limit traffic.
The member is a member string to limit traffic.
The size is a size(k/m/g) to limit traffic.
The code is a code to return in response to rejected requests.(Default: 503)
The key syntax is as follows:
group@[subgroup@]nameThe available group strings are as follows:
subgroup)subgroup)The available member strings are as follows:
The member is the same as server_traffic_status_limit_traffic directive.
| - | - | |
|---|---|---|
| Syntax | server_traffic_status_limit_check_duplicate \<on\ | off> |
| Default | on | |
| Context | stream, server |
Description: Enables or disables the deduplication of server_traffic_status_limit_by_set_key.
It is processed only one of duplicate values(member | key + member)
in each directives(stream, server) if this option is enabled.
| - | - | |
|---|---|---|
| Syntax | server_traffic_status_average_method \<AMM\ | WMA> [period] |
| Default | AMM 60s | |
| Context | stream, server |
Description: Sets the method which is a formula that calculate the average of response processing times.
The period is an effective time of the values used for the average calculation.(Default: 60s)
If period set to 0, effective time is ignored.
In this case, the last average value is displayed even if there is no requests and after the elapse of time.
The corresponding value is only $sts_session_time variable.
Caveats: The $sts_session_time variable is the value calculated at the time of the last request.
It is not calculated when using variables.
| - | - |
|---|---|
| Syntax | server_traffic_status_histogram_buckets second … |
| Default | - |
| Context | stream |
Description: Sets the observe buckets to be used in the histograms.
By default, if you do not set this directive, it will not work.
The second can be expressed in decimal places with a minimum value of 0.001(1ms).
The maximum size of the buckets is 32. If this value is insufficient for you,
change the NGX_STREAM_SERVER_TRAFFIC_STATUS_DEFAULT_BUCKET_LEN in thenginx-mdule-stream-sts/src/ngx_stream_server_traffic_status_node.h
and the NGX_HTTP_STREAM_SERVER_TRAFFIC_STATUS_DEFAULT_BUCKET_LEN in thenginx-module-sts/src/ngx_http_stream_server_traffic_status_node.h.
For examples:
0.005 0.01 0.05 0.1 0.5 1 5 100.005 0.01 0.05 0.1Caveats: By default, if you do not set this directive, the histogram statistics does not work.
YoungJoo.Kim(김영주) [vozltx@gmail.com]