Pular para conteúdo

tuning: módulo de recomendação de ajuste do NGINX

Requer o plano Pro (ou superior) da assinatura GetPageSpeed NGINX Extras.

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-tuning

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-tuning

Ative o módulo adicionando o seguinte no topo de /etc/nginx/nginx.conf:

load_module modules/ngx_http_tuning_module.so;

Este documento descreve o nginx-module-tuning v1.2.0 lançado em 16 de fevereiro de 2026.

Recomendações de ajuste de proxy NGINX baseadas em dados de tráfego real

Pare de adivinhar os tamanhos dos seus buffers. Este módulo observa seus padrões de tráfego reais e diz exatamente o que configurar.

O Problema

Todo guia de configuração de proxy NGINX diz para você ajustar proxy_buffer_size, proxy_buffers e timeouts. Mas quais valores você deve usar?

A abordagem tradicional envolve executar comandos curl contra seus backends: 

curl -s -w %{size_header} -o /dev/null https://backend.example.com

Isso lhe dá um único ponto de dados. Seu tráfego real tem milhares de solicitações por minuto, cada uma com diferentes tamanhos de cabeçalho, tamanhos de corpo e tempos de resposta. Um único curl não diz nada sobre o 95º percentil que está causando erros upstream sent too big header em produção.

A Solução

Este módulo fica dentro do NGINX, observa passivamente cada solicitação proxy e constrói histogramas do tráfego real. Quando você estiver pronto, consulte o endpoint /tuning-advisor:

{
  "sample_size": 847293,
  "uptime_seconds": 86400,
  "requests_per_second": 9.81,

  "proxy_buffer_size": {
    "observed": { "avg": "1.8k", "max": "23.4k", "p95_approx": "4.0k" },
    "recommendation": "OK",
    "suggested_value": "4k",
    "reason": "95% dos cabeçalhos cabem em 4k"
  },

  "proxy_buffers": {
    "observed": { "avg": "12.3k", "max": "2.1m", "p95_approx": "32.0k" },
    "recommendation": "OK",
    "suggested_value": "8 4k",
    "reason": "Default 32k (8x4k) suficiente para 95% das respostas"
  },

  "nginx_config": {
    "snippet": "proxy_buffer_size 4k;\nproxy_buffers 8 4k;\nproxy_read_timeout 10s;\nclient_body_buffer_size 8k;",
    "apply_to": "bloco http, server ou location"
  }
}

Copie o trecho, cole em sua configuração, recarregue. Pronto.

Recursos

Coleta de Métricas

  • Tamanhos de cabeçalho de resposta upstream → ajuste proxy_buffer_size
  • Tamanhos de corpo de resposta upstream → ajuste proxy_buffers
  • Tempos de resposta upstream → ajuste proxy_read_timeout
  • Tamanhos de corpo de solicitação do cliente → ajuste client_body_buffer_size
  • Taxas de reutilização de conexão → otimize as configurações de keepalive
  • Taxas de acertos/perdas de cache → avalie a eficácia do cache proxy

Desempenho

  • Atomics sem bloqueio — sem mutexes, sem contenção entre trabalhadores
  • Memória compartilhada — todos os trabalhadores contribuem para os mesmos contadores
  • Percentis baseados em histogramas — aproximação de p95/p99 sem armazenar cada valor
  • Sobrecarga em nanossegundos — ~10 incrementos atômicos por solicitação

Formatos de Saída

  • API JSON com recomendações, razões e trechos de configuração prontos para uso
  • Métricas Prometheus para integração com Grafana, Alertmanager e amigos
  • Endpoint de redefinição para limpar contadores e iniciar novas janelas de observação

Início Rápido

load_module modules/ngx_http_tuning_module.so;

http {
    # Ativar coleta para todas as solicitações proxy
    tuning_advisor on;

    server {
        # Expor o endpoint de ajuste (restrinja o acesso!)
        location = /tuning-advisor {
            tuning_advisor_status;
            allow 127.0.0.1;
            allow 10.0.0.0/8;
            deny all;
        }

        location / {
            proxy_pass http://backend;
        }
    }
}

Então consulte-o: 

curl http://localhost/tuning-advisor | jq .

Referência de Configuração

tuning_advisor

tuning_advisor on | off;
Padrão off
Contexto http, server, location

Habilita a coleta de métricas para solicitações proxy neste contexto.

tuning_advisor_shm_size

tuning_advisor_shm_size 1m;
Padrão 1m
Contexto http

Tamanho da zona de memória compartilhada para agregação de métricas entre trabalhadores. 1MB é suficiente para os contadores e histogramas de tamanho fixo.

tuning_advisor_status

tuning_advisor_status;
Contexto location

Habilita o manipulador de status. Responde a GET (retorna métricas), POST (reinicia métricas) e GET com ?reset (também reinicia).

Referência da API

GET /tuning-advisor

Retorna JSON com métricas observadas, recomendações e um trecho de configuração pronto para uso.

Estrutura da resposta:

Seção Descrição
sample_size Total de solicitações proxy observadas
uptime_seconds Segundos desde que a coleta começou (ou última redefinição)
requests_per_second Taxa média de solicitações
proxy_buffer_size Métricas de tamanho de cabeçalho e recomendação
proxy_buffers Métricas de tamanho de corpo e recomendação
proxy_read_timeout Métricas de tempo de resposta e recomendação
client_body_buffer_size Métricas de corpo de solicitação e recomendação
connection_reuse Eficácia do keepalive do cliente e upstream
proxy_cache Estatísticas de acertos/perdas/bypass de cache
nginx_config Trecho de configuração para copiar e colar
histograms Contagens brutas de buckets para análise personalizada

GET /tuning-advisor?prometheus

Retorna o formato de exposição do Prometheus:

# HELP nginx_tuning_requests_total Total de solicitações proxy observadas
# TYPE nginx_tuning_requests_total counter
nginx_tuning_requests_total 847293

# HELP nginx_tuning_header_size_bucket Distribuição do tamanho do cabeçalho
# TYPE nginx_tuning_header_size_bucket histogram
nginx_tuning_header_size_bucket{le="1024"} 423841
nginx_tuning_header_size_bucket{le="2048"} 712453
nginx_tuning_header_size_bucket{le="4096"} 831029
nginx_tuning_header_size_bucket{le="+Inf"} 847293

Configure a coleta do Prometheus: 

scrape_configs:
  - job_name: nginx-tuning
    metrics_path: /tuning-advisor
    params:
      prometheus: ['1']
    static_configs:
      - targets: ['nginx:80']

POST /tuning-advisor

Reinicia todos os contadores para zero e retorna confirmação. Útil para iniciar uma nova janela de observação após alterações na configuração.

GET /tuning-advisor?reset

Mesma coisa que POST — reinicia todas as métricas.

Lógica de Recomendação

O módulo analisa percentis e fornece recomendações acionáveis:

Métrica Recomendação Quando
proxy_buffer_size OK p95 tamanho do cabeçalho ≤ 4KB
INCREASE p95 > 4KB (sugere 8k, 16k ou 32k)
WARNING p95 > 16KB (investigue upstream)
proxy_buffers OK p95 tamanho do corpo ≤ 32KB
INCREASE p95 > 32KB (sugere buffers maiores)
proxy_read_timeout CONSIDER_REDUCING p99 tempo de resposta < 5s
OK p99 entre 5s e 30s
WARNING p99 > 30s (backend muito lento)
connection_reuse EXCELLENT Cliente ≥ 80% de reutilização, upstream ≥ 70%
WARNING Baixa reutilização (sugere ajuste de keepalive)
proxy_cache EXCELLENT Taxa de acertos ≥ 80%
WARNING Taxa de acertos < 20%

Histogramas

O módulo usa histogramas de buckets exponenciais para aproximar percentis sem armazenar cada valor:

Buckets de tamanho: <1k, 1-2k, 2-4k, 4-8k, 8-16k, 16-32k, 32-64k, >64k

Buckets de tempo: <10ms, 10-50ms, 50-100ms, 100-500ms, 500ms-1s, 1-5s, 5-10s, >10s

Contagens brutas de buckets estão disponíveis na seção histograms da resposta JSON para análise personalizada.

Considerações de Segurança

O endpoint /tuning-advisor revela informações sobre seus padrões de tráfego. Sempre restrinja o acesso:

location = /tuning-advisor {
    tuning_advisor_status;

    # Permitir apenas de localhost e rede interna
    allow 127.0.0.1;
    allow ::1;
    allow 10.0.0.0/8;
    allow 172.16.0.0/12;
    allow 192.168.0.0/16;
    deny all;

    # Ou exigir autenticação
    # auth_basic "Tuning Advisor";
    # auth_basic_user_file /etc/nginx/.htpasswd;
}

Leitura Relacionada