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 個值來計算的。

凋謝的不是花，萎蔫的是時間；星辰大海，點滴為途。