Aller au contenu

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
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.2.0 publié le 16 février 2026.

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

Cessez de deviner vos tailles de tampon. Ce module observe vos modèles de trafic réels et vous indique exactement ce qu'il faut 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'attente. Mais quelles valeurs devez-vous utiliser ?

L'approche traditionnelle consiste à exécuter des commandes curl contre vos serveurs en arrière-plan : 

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, de corps et des temps de réponse différents. Un seul curl ne vous dit rien sur le 95ème percentile qui cause des erreurs upstream sent too big header en production.

La Solution

Ce module s'intègre à NGINX, observe passivement chaque requête proxyée et construit des histogrammes de 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"
  },

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

Copiez le fragment, 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
  • 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 fragments de configuration prêts à l'emploi
  • Métriques Prometheus pour intégration avec Grafana, Alertmanager, et autres
  • 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 {
    # Activer la collecte pour toutes les requêtes proxyées
    tuning_advisor on;

    server {
        # Exposer le point de terminaison de réglage (restreindre 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ées 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 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 requêtes 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 fragment de configuration prêt à l'emploi.

Structure de la réponse :

Section Description
sample_size Total des requêtes proxyées 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
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 Fragment de configuration à copier-coller
histograms Comptes bruts des seaux pour une analyse personnalisée

GET /tuning-advisor?prometheus

Retourne le format d'exposition Prometheus :

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

# HELP nginx_tuning_header_size_bucket Distribution des tailles d'en-tête
# 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)
proxy_read_timeout CONSIDER_REDUCING temps de réponse p99 < 5s
OK p99 entre 5s et 30s
WARNING p99 > 30s (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 exiger une authentification
    # auth_basic "Tuning Advisor";
    # auth_basic_user_file /etc/nginx/.htpasswd;
}

Lectures Associées