Saltar a contenido

tuning: módulo asesor de ajuste de NGINX

Requiere el plan Pro (o superior) de la suscripción de NGINX Extras de GetPageSpeed.

Instalación

Puedes instalar este módulo en cualquier distribución basada en RHEL, incluyendo, pero no limitado a:

  • RedHat Enterprise Linux 7, 8, 9 y 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 y 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

Habilita el módulo añadiendo lo siguiente en la parte superior de /etc/nginx/nginx.conf:

load_module modules/ngx_http_tuning_module.so;

Este documento describe nginx-module-tuning v1.3.0 lanzado el 29 de abril de 2026.

Recomendaciones de ajuste de proxy NGINX basadas en datos del tráfico real

Deja de adivinar los tamaños de tus buffers. Este módulo observa tus patrones de tráfico reales y te dice exactamente qué configurar.

El Problema

Cada guía de configuración de proxy NGINX te dice que ajustes proxy_buffer_size, proxy_buffers y los timeouts. Pero, ¿qué valores deberías usar?

El enfoque tradicional implica ejecutar comandos curl contra tus backend: 

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

Esto te da un único punto de datos. Tu tráfico real tiene miles de solicitudes por minuto, cada una con diferentes tamaños de encabezado, tamaños de cuerpo y tiempos de respuesta. Un solo curl no te dice nada sobre el percentil 95 que está causando errores de upstream sent too big header en producción.

La Solución

Este módulo se encuentra dentro de NGINX, observa pasivamente cada solicitud proxy y construye histogramas del tráfico real. Cuando estés listo, consulta el 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% de los encabezados caben en 4k"
  },

  "proxy_buffers": {
    "observed": { "avg": "12.3k", "max": "2.1m", "p95_approx": "32.0k" },
    "recommendation": "OK",
    "suggested_value": "8 4k",
    "reason": "El valor predeterminado de 32k (8x4k) es suficiente para el 95% de las respuestas"
  },

  "ssl_buffer_size": {
    "observed": { "avg": "12.3k", "max": "2.1m", "p95_approx": "32.0k" },
    "recommendation": "OK",
    "suggested_value": "16k",
    "reason": "La mayoría de las respuestas superan un registro TLS; el tamaño dinámico de registro o ssl_buffer_size 4k no ofrece ningún beneficio medible"
  },

  "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": "bloque http, server o location"
  }
}

Copia el fragmento, pégalo en tu configuración, recarga. Listo.

Características

Recolección de Métricas

  • Tamaños de encabezados de respuesta upstream → ajusta proxy_buffer_size
  • Tamaños de cuerpos de respuesta upstream → ajusta proxy_buffers y ssl_buffer_size
  • Tiempos de respuesta upstream → ajusta proxy_read_timeout
  • Tamaños de cuerpos de solicitudes del cliente → ajusta client_body_buffer_size
  • Ratios de reutilización de conexiones → optimiza la configuración de keepalive
  • Tasas de aciertos/fallos de caché → evalúa la efectividad de la caché proxy

Rendimiento

  • Atómicos sin bloqueo — sin mutexes, sin contención entre trabajadores
  • Memoria compartida — todos los trabajadores contribuyen a los mismos contadores
  • Percentiles basados en histogramas — aproxima p95/p99 sin almacenar cada valor
  • Sobrecarga en nanosegundos — ~10 incrementos atómicos por solicitud

Formatos de Salida

  • API JSON con recomendaciones, razones y fragmentos de configuración listos para usar
  • Métricas de Prometheus para integración con Grafana, Alertmanager y amigos
  • Endpoint de reinicio para borrar contadores y comenzar nuevas ventanas de observación

Inicio Rápido

load_module modules/ngx_http_tuning_module.so;

http {
    # Habilita la recolección para todas las solicitudes proxy
    tuning_advisor on;

    server {
        # Expone el endpoint de ajuste (¡restringe el acceso!)
        location = /tuning-advisor {
            tuning_advisor_status;
            allow 127.0.0.1;
            allow 10.0.0.0/8;
            deny all;
        }

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

Luego, consúltalo: 

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

Referencia de Configuración

tuning_advisor

tuning_advisor on | off;
Predeterminado off
Contexto http, server, location

Habilita la recolección de métricas para solicitudes proxy en este contexto.

tuning_advisor_shm_size

tuning_advisor_shm_size 1m;
Predeterminado 1m
Contexto http

Tamaño de la zona de memoria compartida para la agregación de métricas entre trabajadores. 1MB es suficiente para los contadores y histogramas de tamaño fijo.

tuning_advisor_status

tuning_advisor_status;
Contexto location

Habilita el manejador de estado. Responde a GET (devuelve métricas), POST (reinicia métricas) y GET con ?reset (también reinicia).

Referencia de API

GET /tuning-advisor

Devuelve JSON con métricas observadas, recomendaciones y un fragmento de configuración listo para usar.

Estructura de respuesta:

Sección Descripción
sample_size Total de solicitudes proxy observadas
uptime_seconds Segundos desde que comenzó la recolección (o último reinicio)
requests_per_second Tasa promedio de solicitudes
proxy_buffer_size Métricas de tamaño de encabezado y recomendación
proxy_buffers Métricas de tamaño de cuerpo y recomendación
ssl_buffer_size Recomendación de tamaño de registro TLS derivada del cuerpo P95
proxy_read_timeout Métricas de tiempo de respuesta y recomendación
client_body_buffer_size Métricas de cuerpo de solicitud y recomendación
connection_reuse Efectividad del keepalive del cliente y upstream
proxy_cache Estadísticas de aciertos/fallos/bypass de caché
nginx_config Fragmento de configuración para copiar y pegar
histograms Contadores de cubos en bruto para análisis personalizado

GET /tuning-advisor?prometheus

Devuelve el formato de exposición de Prometheus:

# HELP nginx_tuning_requests_total Total de solicitudes proxy observadas
# TYPE nginx_tuning_requests_total counter
nginx_tuning_requests_total 847293

# HELP nginx_tuning_header_size_bucket Distribución del tamaño de encabezado
# 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

Configura la recolección de Prometheus: 

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

POST /tuning-advisor

Reinicia todos los contadores a cero y devuelve una confirmación. Útil para comenzar una nueva ventana de observación después de cambios en la configuración.

GET /tuning-advisor?reset

Igual que POST — reinicia todas las métricas.

Lógica de Recomendación

El módulo analiza percentiles y proporciona recomendaciones accionables:

Métrica Recomendación Cuándo
proxy_buffer_size OK tamaño de encabezado p95 ≤ 4KB
INCREASE p95 > 4KB (sugiere 8k, 16k o 32k)
WARNING p95 > 16KB (investiga upstream)
proxy_buffers OK tamaño de cuerpo p95 ≤ 32KB
INCREASE p95 > 32KB (sugiere buffers más grandes)
ssl_buffer_size REDUCE a 4k p95 cuerpo ≤ 4KB (tamaño de registro estático estilo Cloudflare)
OK en 16k p95 cuerpo > 4KB (el predeterminado es apropiado)
proxy_read_timeout CONSIDER_REDUCING tiempo de respuesta p99 < 5s
OK p99 entre 5s y 30s
WARNING p99 > 30s (backend demasiado lento)
connection_reuse EXCELLENT Cliente ≥ 80% reutilización, upstream ≥ 70%
WARNING Baja reutilización (sugiere ajuste de keepalive)
proxy_cache EXCELLENT Tasa de aciertos ≥ 80%
WARNING Tasa de aciertos < 20%

Histogramas

El módulo utiliza histogramas de cubos exponenciales para aproximar percentiles sin almacenar cada valor:

Cubos de tamaño: <1k, 1-2k, 2-4k, 4-8k, 8-16k, 16-32k, 32-64k, >64k

Cubos de tiempo: <10ms, 10-50ms, 50-100ms, 100-500ms, 500ms-1s, 1-5s, 5-10s, >10s

Los contadores de cubos en bruto están disponibles en la sección histograms de la respuesta JSON para análisis personalizado.

Consideraciones de Seguridad

El endpoint /tuning-advisor revela información sobre tus patrones de tráfico. Siempre restringe el acceso:

location = /tuning-advisor {
    tuning_advisor_status;

    # Permitir solo desde localhost y red 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;

    # O requerir autenticación
    # auth_basic "Tuning Advisor";
    # auth_basic_user_file /etc/nginx/.htpasswd;
}

Lectura Relacionada