tuning: module conseiller de réglage NGINX

Nécessite le plan Pro (ou supérieur) de l'abonnement GetPageSpeed NGINX Extras.

Installation

Vous pouvez installer ce module dans n'importe quelle distribution basée sur RHEL, y compris, mais sans s'y limiter :

• RedHat Enterprise Linux 7, 8, 9 et 10
• CentOS 7, 8, 9
• AlmaLinux 8, 9
• Rocky Linux 8, 9
• Amazon Linux 2 et Amazon Linux 2023

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 et Amazon Linux 2

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

Activez le module en ajoutant ce qui suit en haut de /etc/nginx/nginx.conf :

load_module modules/ngx_http_tuning_module.so;

Ce document décrit nginx-module-tuning v1.3.0 publié le 29 avril 2026.

---

Recommandations de réglage NGINX basées sur les données provenant d'un trafic réel

Arrêtez de deviner vos tailles de tampon. Ce module observe vos modèles de trafic réels et vous dit exactement quoi configurer.

Le Problème

Chaque guide de configuration de proxy NGINX vous dit de régler proxy_buffer_size, proxy_buffers et les délais d'expiration. Mais quelles valeurs devez-vous utiliser ?

L'approche traditionnelle consiste à exécuter des commandes curl contre vos backends :

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

Cela vous donne un seul point de données. Votre trafic réel a des milliers de requêtes par minute, chacune avec des tailles d'en-tête, des tailles de corps et des temps de réponse différents. Un seul curl ne vous dit rien sur le 95e percentile qui cause des erreurs upstream sent too big header en production.

La Solution

Ce module s'intègre dans NGINX, observe passivement chaque requête proxy et construit des histogrammes du trafic réel. Lorsque vous êtes prêt, interrogez le point de terminaison /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% des en-têtes tiennent dans 4k"
  },

  "proxy_buffers": {
    "observed": { "avg": "12.3k", "max": "2.1m", "p95_approx": "32.0k" },
    "recommendation": "OK",
    "suggested_value": "8 4k",
    "reason": "32k par défaut (8x4k) suffisant pour 95% des réponses"
  },

  "ssl_buffer_size": {
    "observed": { "avg": "12.3k", "max": "2.1m", "p95_approx": "32.0k" },
    "recommendation": "OK",
    "suggested_value": "16k",
    "reason": "La plupart des réponses dépassent un enregistrement TLS ; la taille dynamique des enregistrements ou ssl_buffer_size 4k n'offre aucun avantage mesurable"
  },

  "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": "http, server, ou bloc location"
  }
}

Copiez le snippet, collez-le dans votre configuration, rechargez. Fait.

Fonctionnalités

Collecte de Métriques

• Tailles des en-têtes de réponse en amont → réglez proxy_buffer_size
• Tailles des corps de réponse en amont → réglez proxy_buffers et ssl_buffer_size
• Temps de réponse en amont → réglez proxy_read_timeout
• Tailles des corps de requête client → réglez client_body_buffer_size
• Ratios de réutilisation de connexion → optimisez les paramètres keepalive
• Taux de réussite/échec du cache → évaluez l'efficacité du cache proxy

Performance

• Atomiques sans verrou — pas de mutex, pas de contention entre les travailleurs
• Mémoire partagée — tous les travailleurs contribuent aux mêmes compteurs
• Percentiles basés sur des histogrammes — approximation de p95/p99 sans stocker chaque valeur
• Surcharge en nanosecondes — ~10 incréments atomiques par requête

Formats de Sortie

• API JSON avec recommandations, raisons et snippets de configuration prêts à l'emploi
• Métriques Prometheus pour intégration avec Grafana, Alertmanager, et amis
• Point de terminaison de réinitialisation pour effacer les compteurs et commencer de nouvelles fenêtres d'observation

Démarrage Rapide

load_module modules/ngx_http_tuning_module.so;

http {
    # Activez la collecte pour toutes les requêtes proxy
    tuning_advisor on;

    server {
        # Exposez le point de terminaison de réglage (restreignez l'accès !)
        location = /tuning-advisor {
            tuning_advisor_status;
            allow 127.0.0.1;
            allow 10.0.0.0/8;
            deny all;
        }

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

Puis interrogez-le :

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

Référence de Configuration

tuning_advisor

tuning_advisor on | off;

Par défaut	off
Contexte	http, server, location

Active la collecte de métriques pour les requêtes proxy dans ce contexte.

tuning_advisor_shm_size

tuning_advisor_shm_size 1m;

Par défaut	1m
Contexte	http

Taille de la zone de mémoire partagée pour l'agrégation des métriques entre travailleurs. 1 Mo est largement suffisant pour les compteurs et histogrammes de taille fixe.

tuning_advisor_status

tuning_advisor_status;

Contexte	location

Active le gestionnaire d'état. Répond aux GET (retourne les métriques), POST (réinitialise les métriques), et GET avec ?reset (réinitialise également).

Référence API

GET /tuning-advisor

Retourne un JSON avec les métriques observées, les recommandations et un snippet de configuration prêt à l'emploi.

Structure de la réponse :

Section	Description
sample_size	Total des requêtes proxy observées
uptime_seconds	Secondes depuis le début de la collecte (ou dernière réinitialisation)
requests_per_second	Taux moyen de requêtes
proxy_buffer_size	Métriques de taille d'en-tête et recommandation
proxy_buffers	Métriques de taille de corps et recommandation
ssl_buffer_size	Recommandation de taille d'enregistrement TLS dérivée du P95 du corps
proxy_read_timeout	Métriques de temps de réponse et recommandation
client_body_buffer_size	Métriques de corps de requête et recommandation
connection_reuse	Efficacité du keepalive client et en amont
proxy_cache	Statistiques de réussite/échec/bypass du cache
nginx_config	Snippet de configuration à copier-coller
histograms	Comptes bruts de seaux pour analyse personnalisée

GET /tuning-advisor?prometheus

Retourne le format d'exposition Prometheus :

# HELP nginx_tuning_requests_total Total des requêtes proxy observées
# TYPE nginx_tuning_requests_total counter
nginx_tuning_requests_total 847293

# HELP nginx_tuning_header_size_bucket Distribution de la taille des en-têtes
# 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

Configurez le scraping Prometheus :

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

POST /tuning-advisor

Réinitialise tous les compteurs à zéro et retourne une confirmation. Utile pour commencer une nouvelle fenêtre d'observation après des modifications de configuration.

GET /tuning-advisor?reset

Identique à POST — réinitialise toutes les métriques.

Logique de Recommandation

Le module analyse les percentiles et fournit des recommandations exploitables :

Métrique	Recommandation	Quand
proxy_buffer_size	OK	taille d'en-tête p95 ≤ 4 Ko
	INCREASE	p95 > 4 Ko (suggère 8k, 16k, ou 32k)
	WARNING	p95 > 16 Ko (investiguer en amont)
proxy_buffers	OK	taille de corps p95 ≤ 32 Ko
	INCREASE	p95 > 32 Ko (suggère des tampons plus grands)
ssl_buffer_size	REDUCE à 4k	p95 corps ≤ 4 Ko (taille d'enregistrement statique de style Cloudflare)
	OK à 16k	p95 corps > 4 Ko (par défaut est approprié)
proxy_read_timeout	CONSIDER_REDUCING	temps de réponse p99 < 5 s
	OK	p99 entre 5 s et 30 s
	WARNING	p99 > 30 s (backend trop lent)
connection_reuse	EXCELLENT	Client ≥ 80% de réutilisation, en amont ≥ 70%
	WARNING	Faible réutilisation (suggère un réglage du keepalive)
proxy_cache	EXCELLENT	Taux de réussite ≥ 80%
	WARNING	Taux de réussite < 20%
##

Histogrammes

Le module utilise des histogrammes à seaux exponentiels pour approximer les percentiles sans stocker chaque valeur :

Seaux de taille : <1k, 1-2k, 2-4k, 4-8k, 8-16k, 16-32k, 32-64k, >64k

Seaux de temps : <10ms, 10-50ms, 50-100ms, 100-500ms, 500ms-1s, 1-5s, 5-10s, >10s

Les comptes bruts des seaux sont disponibles dans la section histograms de la réponse JSON pour une analyse personnalisée.

Considérations de Sécurité

Le point de terminaison /tuning-advisor révèle des informations sur vos modèles de trafic. Restreignez toujours l'accès :

location = /tuning-advisor {
    tuning_advisor_status;

    # Autoriser uniquement depuis localhost et le réseau interne
    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 exigez une authentification
    # auth_basic "Tuning Advisor";
    # auth_basic_user_file /etc/nginx/.htpasswd;
}

Lectures Associées

• Tuning proxy_buffer_size in NGINX — approfondissement sur la taille des tampons
• NGINX Timeout Directives Explained — compréhension de tous les réglages de délai d'expiration