vts: модуль статуса трафика виртуальных хостов NGINX
Установка
Вы можете установить этот модуль в любом дистрибутиве на основе RHEL, включая, но не ограничиваясь:
- RedHat Enterprise Linux 7, 8, 9 и 10
- CentOS 7, 8, 9
- AlmaLinux 8, 9
- Rocky Linux 8, 9
- Amazon Linux 2 и Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-vts
yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-vts
Включите модуль, добавив следующую строку в начало /etc/nginx/nginx.conf:
load_module modules/ngx_http_vhost_traffic_status_module.so;
Этот документ описывает nginx-module-vts v0.2.7 выпущенный 08 августа 2026.
Модуль статуса трафика виртуальных хостов Nginx
Тест
Запустите sudo prove -r t после установки этого модуля. Требуется sudo, потому что
тест требует, чтобы Nginx прослушивал порт 80.
Скриншоты


Синопсис
http {
vhost_traffic_status_zone;
...
server {
...
location /status {
vhost_traffic_status_display;
vhost_traffic_status_display_format html;
}
}
}
Описание
Это модуль Nginx, который предоставляет доступ к информации о статусе виртуальных хостов. Он содержит текущий статус, такой как серверы, апстримы, кэши. Это похоже на мониторинг живых активностей 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 callback-функция, содержащая данные о текущей активности для использования в живых дашбордах и сторонних инструментах мониторинга. - /status/format/prometheus
- Если вы запросите
/status/format/prometheus, будет получен документ prometheus, содержащий данные о текущей активности. - /status/control
- Если вы запросите
/status/control, будет получен JSON-документ после сброса или удаления зон через строку запроса. См. Control.
JSON-документ содержит следующее:
{
"hostName": ...,
"moduleVersion": ...,
"nginxVersion": ...,
"loadMsec": ...,
"nowMsec": ...,
"connections": {
"active":...,
"reading":...,
"writing":...,
"waiting":...,
"accepted":...,
"handled":...,
"requests":...
},
"sharedZones": {
"name":...,
"maxSize":...,
"usedSize":...,
"usedNode":...,
"freeSize":...
},
"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
- Базовая версия, время работы((nowMsec - loadMsec)/1000)
- nowMsec, loadMsec — в миллисекундах.
- connections
- Всего соединений и запросов(так же, как в stub_status_module в NGINX)
- sharedZones
- Информация о разделяемой памяти, используемой в nginx-module-vts.
- serverZones
- Трафик(вход/выход), количество запросов и ответов, а также коэффициент попадания в кэш для каждой серверной зоны
- Общий трафик(вход/выход), количество запросов и ответов(имя зоны
*) и коэффициент попадания - filterZones
- Трафик(вход/выход), количество запросов и ответов, а также коэффициент попадания в кэш для каждой серверной зоны, отфильтрованной через директиву
vhost_traffic_status_filter_by_set_key - Общий трафик(вход/выход), количество запросов и ответов(имя зоны
*) и коэффициент попадания, отфильтрованные через директивуvhost_traffic_status_filter_by_set_key - upstreamZones
- Трафик(вход/выход), количество запросов и ответов для каждого сервера в каждой группе апстримов
- Текущие настройки(weight, maxfails, failtimeout...) в nginx.conf
- cacheZones
- Трафик(вход/выход), размер(емкость/использовано) и коэффициент попадания для каждой кэш-зоны при использовании директивы proxy_cache.
Объекты overCounts в JSON-документе в основном предназначены для 32-битных систем и будут увеличиваться на 1, если их значение переполнено.
Директива vhost_traffic_status_display_format устанавливает формат вывода по умолчанию: json, jsonp, html, prometheus. (По умолчанию: json)
Расчет трафика выглядит следующим образом:
- ServerZones
- in += requested_bytes
- out += sent_bytes
- FilterZones
- in += requested_bytes через фильтр
- out += sent_bytes через фильтр
- UpstreamZones
- in += requested_bytes через ServerZones
- out += sent_bytes через ServerZones
- cacheZones
- in += requested_bytes через ServerZones
- out += sent_bytes через ServerZones
Все расчеты выполняются на этапе обработки логов Nginx. Внутренние редиректы(X-Accel-Redirect или error_page) не учитываются в UpstreamZones.
Предупреждения: этот модуль полагается на систему логирования nginx(NGX_HTTP_LOG_PHASE:последняя фаза http nginx), поэтому трафик может
в определенных обстоятельствах отличаться от реальной полосы пропускания.
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
Расчеты и интервалы
Средние значения
Все средние значения в настоящее время рассчитываются как AMM(среднее арифметическое) за последние 64 значения.
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
* Возвращает статус зон трафика в формате json, как status/format/json.
* reset
* Сбрасывает зоны трафика без удаления узлов в разделяемой памяти.(= инициализация в 0)
* delete
* Удаляет зоны трафика в разделяемой памяти. При повторном запросе создаются заново.
* 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
Получение статуса зон трафика на лету
Это похоже на 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, moduleVersion, nginxVersion, loadMsec, nowMsec, connections.
Получение отдельных зон
- отдельная зона в serverZones
- /status/control?cmd=status&group=server&zone=
name - отдельная зона в filterZones
- /status/control?cmd=status&group=filter&zone=
filter_group@name - отдельная зона в upstreamZones
- /status/control?cmd=status&group=upstream@group&zone=
upstream_group@name - отдельная зона в upstreamZones::nogroups
- /status/control?cmd=status&group=upstream@alone&zone=
name - отдельная зона в 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=*
Сброс отдельных зон
- отдельная зона в serverZones
- /status/control?cmd=reset&group=server&zone=
name - отдельная зона в filterZones
- /status/control?cmd=reset&group=filter&zone=
filter_group@name - отдельная зона в upstreamZones
- /status/control?cmd=reset&group=upstream@group&zone=
upstream_group@name - отдельная зона в upstreamZones::nogroups
- /status/control?cmd=reset&group=upstream@alone&zone=
name - отдельная зона в 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=*
Удаление отдельных зон
- отдельная зона в serverZones
- /status/control?cmd=delete&group=server&zone=
name - отдельная зона в filterZones
- /status/control?cmd=delete&group=filter&zone=
filter_group@name - отдельная зона в upstreamZones
- /status/control?cmd=delete&group=upstream@group&zone=
upstream_group@name - отдельная зона в upstreamZones::nogroups
- /status/control?cmd=delete&group=upstream@alone&zone=
name - отдельная зона в cacheZones
- /status/control?cmd=delete&group=cache&zone=
name
Set
Можно получить значения статуса в конфигурации nginx отдельно с помощью директивы vhost_traffic_status_set_by_filter.
Можно получить почти все значения статуса, и полученное значение сохраняется в пользовательской переменной, которая является первым аргументом.
- Синтаксис директивы
- 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/[email protected]: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 для подробного использования.
JSON
Следующая информация о статусе предоставляется в формате JSON:
Json, используемый для status
/{status_uri}/format/json
/{status_uri}/control?cmd=status&...
- hostName
- Имя хоста.
- moduleVersion
- Версия модуля в формате
{version}(|.dev.{commit}). - nginxVersion
- Версия предоставленного.
- loadMsec
- Время загрузки процесса в миллисекундах.
- nowMsec
- Текущее время в миллисекундах
- connections
- active
- Текущее количество активных клиентских соединений.
- reading
- Общее количество читающих клиентских соединений.
- writing
- Общее количество пишущих клиентских соединений.
- waiting
- Общее количество ожидающих клиентских соединений.
- accepted
- Общее количество принятых клиентских соединений.
- handled
- Общее количество обработанных клиентских соединений.
- requests
- Общее количество запрошенных клиентских соединений.
- sharedZones
- name
- Имя разделяемой памяти, указанное в конфигурации.(по умолчанию:
vhost_traffic_status)
- Имя разделяемой памяти, указанное в конфигурации.(по умолчанию:
- maxSize
- Ограничение максимального размера разделяемой памяти, указанное в конфигурации.
- usedSize
- Текущий размер разделяемой памяти.
- usedNode
- Текущее количество узлов, используемых в разделяемой памяти. Можно получить приблизительный размер одного узла по следующей формуле: (usedSize / usedNode)
- freeSize
- Место, которое осталось в разделяемой памяти для дополнительных узлов. usedSize выше — это сумма размеров узлов, а не то, что зона потратила, потому что slab-аллокатор выделяет целую страницу или целый слот для каждого из них. Поэтому зона перестает принимать узлы, пока usedSize все еще читается ниже maxSize, и это значение говорит об этом. Узел больше половины страницы, поэтому, если страница равна 4k, это место для дополнительных узлов; если страница больше, это нижняя граница, поскольку частично использованная страница все еще может содержать один узел.
- 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
- Адрес сервера.
- 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. - counters
- Накопительные значения, поскольку каждое значение корзины больше или равно времени обработки запроса, включая upstream.
- responseMsecCounter
- Количество накопленного времени обработки ответов только upstream в миллисекундах.
- responseMsec
- Среднее время обработки ответов только upstream в миллисекундах.
- responseMsecs
- times
- Время в миллисекундах при обработке запросов.
- msecs
- Время обработки ответов только upstream в миллисекундах.
- responseBuckets
- msecs
- Значения корзин гистограммы, установленные директивой
vhost_traffic_status_histogram_buckets. - counters
- Накопительные значения, поскольку каждое значение корзины больше или равно времени обработки ответов только upstream.
- weight
- Текущая настройка
weightсервера.
- Текущая настройка
- maxFails
- Текущая настройка
max_failsсервера.
- Текущая настройка
- failTimeout
- Текущая настройка
fail_timeoutсервера.
- Текущая настройка
- backup
- Текущая настройка
backupсервера.
- Текущая настройка
- down
- Текущая настройка
downсервера. В основном это просто метка для ngx_http_upstream_module server down(например,server backend3.example.com down), а не фактическое состояние upstream-сервера. Оно изменится на фактическое состояние, если вы включите директиву upstream zone.
- Текущая настройка
- cacheZones
- maxSize
- Ограничение максимального размера кэша, указанное в конфигурации. Если
max_sizeв директивеproxy_cache_pathне указан, по умолчанию присваивается системное значениеNGX_MAX_OFF_T_VALUE. Другими словами, это значение от nginx, а не то, что указал я.
- Ограничение максимального размера кэша, указанное в конфигурации. Если
- usedSize
- Текущий размер кэша. Это значение берется из nginx, как и значение
maxSizeвыше.
- Текущий размер кэша. Это значение берется из nginx, как и значение
- inBytes
- Общее количество байт, полученных из кэша.
- outBytes
- Общее количество байт, отправленных из кэша.
- responses
- miss
- Количество промахов кэша.
- bypass
- Количество обходов кэша.
- expired
- Количество истекших кэшей.
- stale
- Количество устаревших кэшей.
- updating
- Количество обновляемых кэшей.
- revalidated
- Количество повторно проверенных кэшей.
- hit
- Количество попаданий в кэш.
- scarce
- Количество дефицитных кэшей.
Json, используемый для control
/{status_uri}/control?cmd=reset&...
/{status_uri}/control?cmd=delete&...
- processingReturn
- Результат true или false.
- processingCommandString
- Запрошенная строка команды.
- processingGroupString
- Запрошенная строка группы.
- processingZoneString
- Запрошенная строка зоны.
- processingCounts
- Фактическое количество обработок.
Переменные
Предоставляются следующие встроенные переменные:
- $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
- Среднее время обработки запросов.
Лимит
Можно ограничить общий трафик для каждого хоста с помощью директивы
vhost_traffic_status_limit_traffic.
Также можно ограничить весь трафик с помощью директивы
vhost_traffic_status_limit_traffic_by_set_key.
Когда лимит превышен, сервер вернет ошибку 503
(Service Temporarily Unavailable) в ответ на запрос.
Код возврата можно изменить.
Ограничение трафика для сервера
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.
Ограничение трафика для фильтра
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;
...
}
}
- Ограничивает общий трафик, идущий в US и CN на
example.org, до 1024G и 2048G соответственно.
Ограничение трафика для upstream
```Nginx 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