Pular para conteúdo

tuning: módulo de aconselhamento 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 nginx-module-tuning v1.3.0 lançado em 29 de abril 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 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 requisições por minuto, cada uma com tamanhos de cabeçalho, tamanhos de corpo e tempos de resposta diferentes. Um único curl não diz nada sobre o percentil 95 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 requisiçã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"
  },

  "ssl_buffer_size": {
    "observed": { "avg": "12.3k", "max": "2.1m", "p95_approx": "32.0k" },
    "recommendation": "OK",
    "suggested_value": "16k",
    "reason": "A maioria das respostas excede um registro TLS; dimensionamento dinâmico de registro ou ssl_buffer_size 4k não oferece benefício mensurável"
  },

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

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

Recursos

Coleta de Métricas

  • Tamanhos dos cabeçalhos de resposta upstream → ajuste proxy_buffer_size
  • Tamanhos dos corpos de resposta upstream → ajuste proxy_buffers e ssl_buffer_size
  • Tempos de resposta upstream → ajuste proxy_read_timeout
  • Tamanhos dos corpos de requisiçã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 p95/p99 sem armazenar cada valor
  • Sobrecarga em nanossegundos — ~10 incrementos atômicos por requisiçã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 {
    # Ative a coleta para todas as requisições proxy
    tuning_advisor on;

    server {
        # Exponha 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: 

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 requisiçõ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 requisições proxy observadas
uptime_seconds Segundos desde que a coleta começou (ou última redefinição)
requests_per_second Taxa média de requisiçõ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
ssl_buffer_size Recomendação de tamanho de registro TLS derivada do corpo P95
proxy_read_timeout Métricas de tempo de resposta e recomendação
client_body_buffer_size Métricas de corpo de requisiçã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 no formato de exposição do Prometheus:

# HELP nginx_tuning_requests_total Total de requisiçõ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 de configuração.

GET /tuning-advisor?reset

Mesma função 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)
ssl_buffer_size REDUCE para 4k p95 corpo ≤ 4KB (tamanho de registro estático estilo Cloudflare)
OK em 16k p95 corpo > 4KB (default é apropriado)
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% 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