vts: Módulo de status de tráfego de host virtual NGINX
Instalação
Você pode instalar este módulo em qualquer distribuição baseada em RHEL, incluindo, mas não se limitando a:
- RedHat Enterprise Linux 7, 8, 9 e 10
- CentOS 7, 8, 9
- AlmaLinux 8, 9
- Rocky Linux 8, 9
- Amazon Linux 2 e 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
Habilite o módulo adicionando o seguinte no topo do /etc/nginx/nginx.conf:
load_module modules/ngx_http_vhost_traffic_status_module.so;
Este documento descreve o nginx-module-vts v0.2.7 lançado em 08 de agosto de 2026.
Módulo de status de tráfego de host virtual Nginx
Teste
Execute sudo prove -r t após ter instalado este módulo. O sudo é necessário porque
o teste requer que o Nginx escute na porta 80.
Capturas de tela


Sinopse
http {
vhost_traffic_status_zone;
...
server {
...
location /status {
vhost_traffic_status_display;
vhost_traffic_status_display_format html;
}
}
}
Descrição
Este é um módulo Nginx que fornece acesso às informações de status do host virtual. Ele contém o status atual, como servidores, upstreams, caches. Isso é semelhante ao monitoramento de atividade ao vivo do nginx plus. O html integrado também é retirado da página de demonstração da versão antiga.
Primeiro de tudo, a diretiva vhost_traffic_status_zone é obrigatória,
e então se a diretiva vhost_traffic_status_display estiver definida, pode-se acessar da seguinte forma:
- /status/format/json
- Se você solicitar
/status/format/json, responderá com um documento JSON contendo os dados de atividade atuais para uso em painéis ao vivo e ferramentas de monitoramento de terceiros. - /status/format/html
- Se você solicitar
/status/format/html, responderá com o painel ao vivo integrado em HTML que solicita internamente a/status/format/json. - /status/format/jsonp
- Se você solicitar
/status/format/jsonp, responderá com uma função de callback JSONP contendo os dados de atividade atuais para uso em painéis ao vivo e ferramentas de monitoramento de terceiros. - /status/format/prometheus
- Se você solicitar
/status/format/prometheus, responderá com um documento prometheus contendo os dados de atividade atuais. - /status/control
- Se você solicitar
/status/control, responderá com um documento JSON após redefinir ou excluir zonas através de uma query string. Veja Control.
O documento JSON contém o seguinte:
{
"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
- Versão básica, uptime((nowMsec - loadMsec)/1000)
- nowMsec, loadMsec é em milissegundos.
- connections
- Total de conexões e requisições (igual ao stub_status_module no NGINX)
- sharedZones
- As informações de memória compartilhada usadas no nginx-module-vts.
- serverZones
- Tráfego (entrada/saída) e contagens de requisições e respostas e taxa de acerto de cache por cada zona de servidor
- Tráfego total (Entrada/Saída) e contagens de requisições e respostas (O nome da zona é
*) e taxa de acerto - filterZones
- Tráfego (entrada/saída) e contagens de requisições e respostas e taxa de acerto de cache por cada zona de servidor filtrada através da diretiva
vhost_traffic_status_filter_by_set_key - Tráfego total (Entrada/Saída) e contagens de requisições e respostas (O nome da zona é
*) e taxa de acerto filtrados através da diretivavhost_traffic_status_filter_by_set_key - upstreamZones
- Tráfego (entrada/saída) e contagens de requisições e respostas por servidor em cada grupo de upstream
- Configurações atuais (weight, maxfails, failtimeout...) no nginx.conf
- cacheZones
- Tráfego (entrada/saída) e tamanho (capacidade/usado) e taxa de acerto por cada zona de cache ao usar a diretiva proxy_cache.
Os objetos overCounts no documento JSON são principalmente para sistemas de 32 bits e serão incrementados em 1 se seu valor estourar.
A diretiva vhost_traffic_status_display_format define o formato de saída padrão que é um de json, jsonp, html, prometheus. (Padrão: json)
O cálculo de tráfego é o seguinte:
- ServerZones
- in += bytes_requisitados
- out += bytes_enviados
- FilterZones
- in += bytes_requisitados via o filtro
- out += bytes_enviados via o filtro
- UpstreamZones
- in += bytes_requisitados via as ServerZones
- out += bytes_enviados via as ServerZones
- cacheZones
- in += bytes_requisitados via as ServerZones
- out += bytes_enviados via as ServerZones
Todos os cálculos funcionam na fase de processamento de log do Nginx. Redirecionamentos internos (X-Accel-Redirect ou error_page) não são calculados nas UpstreamZones.
Advertências: este módulo depende do sistema de logging do nginx (NGX_HTTP_LOG_PHASE: última fase do http do nginx), então o tráfego pode ser
em certas circunstâncias diferente do tráfego real de banda.
Websocket, downloads cancelados podem causar imprecisões.
O funcionamento do módulo não importa se a diretiva access_log está "on" ou "off".
Novamente, este módulo funciona bem com "access_log off".
Ao usar vários domínios, ele define como primeiro domínio (esquerda) da diretiva server_name.
Se você não quiser isso, veja as diretivas vhost_traffic_status_filter_by_host, vhost_traffic_status_filter_by_set_key.
Veja os seguintes módulos para estatísticas de tráfego stream:
* nginx-module-sts
* nginx-module-stream-sts
Cálculos e Intervalos
Médias
Todas as médias são atualmente calculadas como AMM(Média Aritmética) sobre os últimos 64 valores.
Controle
É possível redefinir ou excluir zonas de tráfego através de uma query string. A requisição responde com um documento JSON.
- Sintaxe da URI
- /
{status_uri}/control?cmd={comando}&group={grupo}&zone={nome}
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;
}
}
}
Se definido como acima, então a uri de controle é como example.org/status/control.
Os argumentos de requisição disponíveis são os seguintes:
* cmd=\<status|reset|delete>
* status
* Retorna o status das zonas de tráfego em formato json como status/format/json.
* reset
* Redefine as zonas de tráfego sem excluir nós na memória compartilhada.(= inicializar para 0)
* delete
* Exclui as zonas de tráfego na memória compartilhada. Quando re-requisitado, é recriado.
* group=\<server|filter|upstream@alone|upstream@group|cache|*>
* server
* filter
* upstream@alone
* upstream@group
* cache
* *
* zone=nome
* server
* nome
* filter
* grupo_filtro@nome
* upstream@group
* grupo_upstream@nome
* upstream@alone
* @nome
* cache
* nome
Para obter o status das zonas de tráfego em tempo real
Isso é semelhante ao status/format/json, exceto que pode obter cada zona.
Para obter todas as zonas
- É exatamente o mesmo que
status/format/json. - /status/control?cmd=status&group=*
Para obter zonas de grupo
- 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=*
Os valores mainZones são os valores de status padrão, incluindo hostName, moduleVersion, nginxVersion, loadMsec, nowMsec, connections.
Para obter cada zona
- zona única em serverZones
- /status/control?cmd=status&group=server&zone=
nome - zona única em filterZones
- /status/control?cmd=status&group=filter&zone=
grupo_filtro@nome - zona única em upstreamZones
- /status/control?cmd=status&group=upstream@group&zone=
grupo_upstream@nome - zona única em upstreamZones::nogroups
- /status/control?cmd=status&group=upstream@alone&zone=
nome - zona única em cacheZones
- /status/control?cmd=status&group=cache&zone=
nome
Para redefinir zonas de tráfego em tempo real
Redefine os valores das zonas especificadas para 0.
Para redefinir todas as zonas
- /status/control?cmd=reset&group=*
Para redefinir zonas de grupo
- 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=*
Para redefinir cada zona
- zona única em serverZones
- /status/control?cmd=reset&group=server&zone=
nome - zona única em filterZones
- /status/control?cmd=reset&group=filter&zone=
grupo_filtro@nome - zona única em upstreamZones
- /status/control?cmd=reset&group=upstream@group&zone=
grupo_upstream@nome - zona única em upstreamZones::nogroups
- /status/control?cmd=reset&group=upstream@alone&zone=
nome - zona única em cacheZones
- /status/control?cmd=reset&group=cache&zone=
nome
Para excluir zonas de tráfego em tempo real
Exclui as zonas especificadas na memória compartilhada.
Para excluir todas as zonas
- /status/control?cmd=delete&group=*
Para excluir zonas de grupo
- 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=*
Para excluir cada zona
- zona única em serverZones
- /status/control?cmd=delete&group=server&zone=
nome - zona única em filterZones
- /status/control?cmd=delete&group=filter&zone=
grupo_filtro@nome - zona única em upstreamZones
- /status/control?cmd=delete&group=upstream@group&zone=
grupo_upstream@nome - zona única em upstreamZones::nogroups
- /status/control?cmd=delete&group=upstream@alone&zone=
nome - zona única em cacheZones
- /status/control?cmd=delete&group=cache&zone=
nome
Definição
É possível obter os valores de status na configuração do nginx separadamente usando a diretiva vhost_traffic_status_set_by_filter.
É possível adquirir quase todos os valores de status e o valor obtido é armazenado em uma variável definida pelo usuário que é o primeiro argumento.
- Sintaxe da Diretiva
- vhost_traffic_status_set_by_filter $variável grupo/zona/nome
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;
}
}
}
As configurações acima são as seguintes:
- $requestCounter
- serverZones -> example.org -> requestCounter
- $requestCounterKR
- filterZones -> country::example.org -> KR -> requestCounter
- $requestCounterB1
- upstreamZones -> backend -> 10.0.10.11:80 -> requestCounter
Por favor, veja a diretiva vhost_traffic_status_set_by_filter para uso detalhado.
JSON
As seguintes informações de status são fornecidas no formato JSON:
Json usado por status
/{status_uri}/format/json
/{status_uri}/control?cmd=status&...
- hostName
- Nome do host.
- moduleVersion
- Versão do módulo no formato
{versão}(|.dev.{commit}). - nginxVersion
- Versão do fornecido.
- loadMsec
- Tempo de processo carregado em milissegundos.
- nowMsec
- Tempo atual em milissegundos
- connections
- active
- O número atual de conexões de clientes ativas.
- reading
- O número total de conexões de clientes em leitura.
- writing
- O número total de conexões de clientes em escrita.
- waiting
- O número total de conexões de clientes em espera.
- accepted
- O número total de conexões de clientes aceitas.
- handled
- O número total de conexões de clientes tratadas.
- requests
- O número total de conexões de clientes requisitadas.
- sharedZones
- name
- O nome da memória compartilhada especificada na configuração.(padrão:
vhost_traffic_status)
- O nome da memória compartilhada especificada na configuração.(padrão:
- maxSize
- O limite do tamanho máximo da memória compartilhada especificada na configuração.
- usedSize
- O tamanho atual da memória compartilhada.
- usedNode
- O número atual de nós usando a memória compartilhada. É possível obter um tamanho aproximado para um nó com a seguinte fórmula: (usedSize / usedNode)
- freeSize
- O espaço que a memória compartilhada tem disponível para mais nós. O usedSize acima é a soma dos tamanhos dos nós, que não é o que a zona gastou, porque o alocador de slab entrega uma página inteira ou um slot inteiro para cada um deles. Uma zona, portanto, para de aceitar nós enquanto usedSize ainda lê abaixo de maxSize, e este é o valor que diz isso. Um nó é maior que meia página, então onde uma página é 4k este é o espaço para mais deles; onde a página é maior, é um limite inferior, já que uma página parcialmente usada ainda pode conter um.
- serverZones
- requestCounter
- O número total de requisições de clientes recebidas dos clientes.
- inBytes
- O número total de bytes recebidos dos clientes.
- outBytes
- O número total de bytes enviados aos clientes.
- responses
- 1xx, 2xx, 3xx, 4xx, 5xx
- O número de respostas com códigos de status 1xx, 2xx, 3xx, 4xx e 5xx.
- miss
- O número de cache miss.
- bypass
- O número de cache bypass.
- expired
- O número de cache expirado.
- stale
- O número de cache obsoleto.
- updating
- O número de cache em atualização.
- revalidated
- O número de cache revalidado.
- hit
- O número de cache hit.
- scarce
- O número de cache escasso.
- requestMsecCounter
- O número de tempo de processamento de requisição acumulado em milissegundos.
- requestMsec
- A média dos tempos de processamento de requisição em milissegundos.
- requestMsecs
- times
- Os tempos em milissegundos nos tempos de processamento de requisição.
- msecs
- Os tempos de processamento de requisição em milissegundos.
- requestBuckets
- msecs
- Os valores de bucket do histograma definidos pela diretiva
vhost_traffic_status_histogram_buckets. - counters
- Os valores cumulativos pela razão de que cada valor de bucket é maior ou igual ao tempo de processamento de requisição.
- filterZones
- Fornece os mesmos campos que
serverZones, exceto que inclui nomes de grupo. - upstreamZones
- server
- Um endereço do servidor.
- requestCounter
- O número total de conexões de clientes encaminhadas para este servidor.
- inBytes
- O número total de bytes recebidos deste servidor.
- outBytes
- O número total de bytes enviados para este servidor.
- responses
- 1xx, 2xx, 3xx, 4xx, 5xx
- O número de respostas com códigos de status 1xx, 2xx, 3xx, 4xx e 5xx.
- requestMsecCounter
- O número de tempo de processamento de requisição acumulado incluindo upstream em milissegundos.
- requestMsec
- A média dos tempos de processamento de requisição incluindo upstream em milissegundos.
- requestMsecs
- times
- Os tempos em milissegundos nos tempos de processamento de requisição.
- msecs
- Os tempos de processamento de requisição incluindo upstream em milissegundos.
- requestBuckets
- msecs
- Os valores de bucket do histograma definidos pela diretiva
vhost_traffic_status_histogram_buckets. - counters
- Os valores cumulativos pela razão de que cada valor de bucket é maior ou igual ao tempo de processamento de requisição incluindo upstream.
- responseMsecCounter
- O número de tempo de processamento de resposta apenas do upstream acumulado em milissegundos.
- responseMsec
- A média dos tempos de processamento de resposta apenas do upstream em milissegundos.
- responseMsecs
- times
- Os tempos em milissegundos nos tempos de processamento de requisição.
- msecs
- Os tempos de processamento de resposta apenas do upstream em milissegundos.
- responseBuckets
- msecs
- Os valores de bucket do histograma definidos pela diretiva
vhost_traffic_status_histogram_buckets. - counters
- Os valores cumulativos pela razão de que cada valor de bucket é maior ou igual ao tempo de processamento de resposta apenas do upstream.
- weight
- Configuração atual de
weightdo servidor.
- Configuração atual de
- maxFails
- Configuração atual de
max_failsdo servidor.
- Configuração atual de
- failTimeout
- Configuração atual de
fail_timeoutdo servidor.
- Configuração atual de
- backup
- Configuração atual de
backupdo servidor.
- Configuração atual de
- down
- Configuração atual de
downdo servidor. Basicamente, isso é apenas uma marca do ngx_http_upstream_module server down (ex.server backend3.example.com down), não o estado real do servidor upstream. Mudará para o estado real se você habilitou a diretiva de zona upstream.
- Configuração atual de
- cacheZones
- maxSize
- O limite do tamanho máximo do cache especificado na configuração. Se
max_sizena diretivaproxy_cache_pathnão for especificado, o valor dependente do sistemaNGX_MAX_OFF_T_VALUEé atribuído por padrão. Em outras palavras, este valor é do nginx, não o que eu especifiquei.
- O limite do tamanho máximo do cache especificado na configuração. Se
- usedSize
- O tamanho atual do cache. Este valor é obtido do nginx como o valor
maxSizeacima.
- O tamanho atual do cache. Este valor é obtido do nginx como o valor
- inBytes
- O número total de bytes recebidos do cache.
- outBytes
- O número total de bytes enviados do cache.
- responses
- miss
- O número de cache miss.
- bypass
- O número de cache bypass.
- expired
- O número de cache expirado.
- stale
- O número de cache obsoleto.
- updating
- O número de cache em atualização.
- revalidated
- O número de cache revalidado.
- hit
- O número de cache hit.
- scarce
- O número de cache escasso.
Json usado por controle
/{status_uri}/control?cmd=reset&...
/{status_uri}/control?cmd=delete&...
- processingReturn
- O resultado de verdadeiro ou falso.
- processingCommandString
- A string de comando requisitada.
- processingGroupString
- A string de grupo requisitada.
- processingZoneString
- A string de zona requisitada.
- processingCounts
- O número de processamento real.
Variáveis
As seguintes variáveis incorporadas são fornecidas:
- $vts_request_counter
- O número total de requisições de clientes recebidas dos clientes.
- $vts_in_bytes
- O número total de bytes recebidos dos clientes.
- $vts_out_bytes
- O número total de bytes enviados aos clientes.
- $vts_1xx_counter
- O número de respostas com códigos de status 1xx.
- $vts_2xx_counter
- O número de respostas com códigos de status 2xx.
- $vts_3xx_counter
- O número de respostas com códigos de status 3xx.
- $vts_4xx_counter
- O número de respostas com códigos de status 4xx.
- $vts_5xx_counter
- O número de respostas com códigos de status 5xx.
- $vts_cache_miss_counter
- O número de cache miss.
- $vts_cache_bypass_counter
- O número de cache bypass.
- $vts_cache_expired_counter
- O número de cache expirado.
- $vts_cache_stale_counter
- O número de cache obsoleto.
- $vts_cache_updating_counter
- O número de cache em atualização.
- $vts_cache_revalidated_counter
- O número de cache revalidado.
- $vts_cache_hit_counter
- O número de cache hit.
- $vts_cache_scarce_counter
- O número de cache escasso.
- $vts_request_time_counter
- O número de tempo de processamento de requisição acumulado.
- $vts_request_time
- A média dos tempos de processamento de requisição.
Limite
É possível limitar o tráfego total por cada host usando a diretiva
vhost_traffic_status_limit_traffic.
Também é possível limitar todo o tráfego usando a diretiva
vhost_traffic_status_limit_traffic_by_set_key.
Quando o limite é excedido, o servidor retornará o erro 503
(Service Temporarily Unavailable) em resposta a uma requisição.
O código de retorno pode ser alterado.
Para limitar tráfego para servidor
http {
vhost_traffic_status_zone;
...
server {
server_name *.example.org;
vhost_traffic_status_limit_traffic in:64G;
vhost_traffic_status_limit_traffic out:1024G;
...
}
}
- Limita o tráfego total de entrada/saída no
*.example.orgpara 64G e 1024G respectivamente. Funciona individualmente por cada domínio se a diretivavhost_traffic_status_filter_by_hostestiver habilitada.
Para limitar tráfego para filtro
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;
...
}
}
- Limita o tráfego total de saída para US e CN no
example.orgpara 1024G e 2048G respectivamente.
Para limitar tráfego para 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 UG@[email protected]:80 in:512G;
vhost_traffic_status_limit_traffic_by_set_key UG@backend