Zum Inhalt

tuning: NGINX Tuning Advisor Modul

Erfordert den Pro-Plan (oder höher) des GetPageSpeed NGINX Extras Abonnements.

Installation

Sie können dieses Modul in jeder RHEL-basierten Distribution installieren, einschließlich, aber nicht beschränkt auf:

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

Aktivieren Sie das Modul, indem Sie Folgendes an den Anfang von /etc/nginx/nginx.conf hinzufügen:

load_module modules/ngx_http_tuning_module.so;

Dieses Dokument beschreibt nginx-module-tuning v1.2.0, veröffentlicht am 16. Februar 2026.

Datengetriebene NGINX Proxy-Tuning-Empfehlungen aus echtem Traffic

Hören Sie auf, Ihre Puffergrößen zu raten. Dieses Modul beobachtet Ihre tatsächlichen Verkehrsströme und sagt Ihnen genau, was Sie konfigurieren sollen.

Das Problem

Jede NGINX Proxy-Setup-Anleitung sagt Ihnen, dass Sie proxy_buffer_size, proxy_buffers und Timeouts anpassen sollen. Aber welche Werte sollten Sie verwenden?

Der traditionelle Ansatz besteht darin, curl-Befehle gegen Ihre Backends auszuführen: 

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

Dies gibt Ihnen einen einzelnen Datenpunkt. Ihr echter Traffic hat Tausende von Anfragen pro Minute, jede mit unterschiedlichen Headergrößen, Körpergrößen und Antwortzeiten. Ein einzelnes curl sagt Ihnen nichts über das 95. Perzentil, das upstream sent too big header-Fehler in der Produktion verursacht.

Die Lösung

Dieses Modul sitzt innerhalb von NGINX, beobachtet passiv jede proxied Anfrage und erstellt Histogramme des tatsächlichen Verkehrs. Wenn Sie bereit sind, fragen Sie den /tuning-advisor Endpunkt ab:

{
  "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% der Header passen in 4k"
  },

  "proxy_buffers": {
    "observed": { "avg": "12.3k", "max": "2.1m", "p95_approx": "32.0k" },
    "recommendation": "OK",
    "suggested_value": "8 4k",
    "reason": "Standard 32k (8x4k) ausreichend für 95% der Antworten"
  },

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

Kopieren Sie den Snippet, fügen Sie ihn in Ihre Konfiguration ein, laden Sie neu. Fertig.

Funktionen

Metriksammlung

  • Headergrößen der Upstream-Antworten → tune proxy_buffer_size
  • Körpergrößen der Upstream-Antworten → tune proxy_buffers
  • Antwortzeiten der Upstream → tune proxy_read_timeout
  • Körpergrößen der Client-Anfragen → tune client_body_buffer_size
  • Verbindungswiederverwendungsraten → optimieren Sie die Keepalive-Einstellungen
  • Cache-Treffer-/Verfehlungsraten → bewerten Sie die Effektivität des Proxy-Caches

Leistung

  • Lock-freie Atomics — keine Mutexes, keine Konkurrenz zwischen Workern
  • Geteilte Speicher — alle Worker tragen zu denselben Zählern bei
  • Histogrammbasierte Perzentile — approximieren p95/p99, ohne jeden Wert zu speichern
  • Nanosekunden-Overhead — ~10 atomare Inkremente pro Anfrage

Ausgabeformate

  • JSON API mit Empfehlungen, Gründen und sofort verwendbaren Konfigurationssnippets
  • Prometheus-Metriken zur Integration mit Grafana, Alertmanager und Co.
  • Reset-Endpunkt zum Zurücksetzen der Zähler und zum Start neuer Beobachtungsfenster

Schnellstart

load_module modules/ngx_http_tuning_module.so;

http {
    # Aktivieren Sie die Sammlung für alle proxied Anfragen
    tuning_advisor on;

    server {
        # Exponieren Sie den Tuning-Endpunkt (Zugriff einschränken!)
        location = /tuning-advisor {
            tuning_advisor_status;
            allow 127.0.0.1;
            allow 10.0.0.0/8;
            deny all;
        }

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

Fragen Sie dann ab: 

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

Konfigurationsreferenz

tuning_advisor

tuning_advisor on | off;
Standard off
Kontext http, server, location

Aktiviert die Metriksammlung für proxied Anfragen in diesem Kontext.

tuning_advisor_shm_size

tuning_advisor_shm_size 1m;
Standard 1m
Kontext http

Größe des Shared-Memory-Bereichs für die Aggregation von Metriken über Worker hinweg. 1MB ist ausreichend für die festen Zähler und Histogramme.

tuning_advisor_status

tuning_advisor_status;
Kontext location

Aktiviert den Status-Handler. Reagiert auf GET (gibt Metriken zurück), POST (setzt Metriken zurück) und GET mit ?reset (setzt ebenfalls zurück).

API-Referenz

GET /tuning-advisor

Gibt JSON mit beobachteten Metriken, Empfehlungen und einem sofort verwendbaren Konfigurationssnippet zurück.

Antwortstruktur:

Abschnitt Beschreibung
sample_size Gesamtzahl der beobachteten proxied Anfragen
uptime_seconds Sekunden seit Beginn der Sammlung (oder letztem Reset)
requests_per_second Durchschnittliche Anfragerate
proxy_buffer_size Headergrößenmetriken und Empfehlung
proxy_buffers Körpergrößenmetriken und Empfehlung
proxy_read_timeout Antwortzeitmetriken und Empfehlung
client_body_buffer_size Anfragekörpermetriken und Empfehlung
connection_reuse Effektivität von Client- und Upstream-Keepalive
proxy_cache Cache-Treffer-/Verfehlungs-/Umgehungsstatistiken
nginx_config Kopieren-Einfügen Konfigurationssnippet
histograms Rohbucket-Zählungen für benutzerdefinierte Analysen

GET /tuning-advisor?prometheus

Gibt das Prometheus-Expositionsformat zurück:

# HELP nginx_tuning_requests_total Gesamtzahl der beobachteten proxied Anfragen
# TYPE nginx_tuning_requests_total counter
nginx_tuning_requests_total 847293

# HELP nginx_tuning_header_size_bucket Headergrößendverteilung
# 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

Konfigurieren Sie das Scraping für Prometheus: 

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

POST /tuning-advisor

Setzt alle Zähler auf null zurück und gibt eine Bestätigung zurück. Nützlich, um ein neues Beobachtungsfenster nach Konfigurationsänderungen zu starten.

GET /tuning-advisor?reset

Dasselbe wie POST — setzt alle Metriken zurück.

Empfehlungslogik

Das Modul analysiert Perzentile und gibt umsetzbare Empfehlungen:

Metrik Empfehlung Wann
proxy_buffer_size OK p95 Headergröße ≤ 4KB
INCREASE p95 > 4KB (schlägt 8k, 16k oder 32k vor)
WARNING p95 > 16KB (Untersuchung des Upstreams)
proxy_buffers OK p95 Körpergröße ≤ 32KB
INCREASE p95 > 32KB (schlägt größere Puffer vor)
proxy_read_timeout CONSIDER_REDUCING p99 Antwortzeit < 5s
OK p99 zwischen 5s und 30s
WARNING p99 > 30s (Backend zu langsam)
connection_reuse EXCELLENT Client ≥ 80% Wiederverwendung, Upstream ≥ 70%
WARNING Niedrige Wiederverwendung (schlägt Keepalive-Tuning vor)
proxy_cache EXCELLENT Trefferquote ≥ 80%
WARNING Trefferquote < 20%

Histogramme

Das Modul verwendet exponentielle Bucket-Histogramme, um Perzentile zu approximieren, ohne jeden Wert zu speichern:

Größen-Buckets: <1k, 1-2k, 2-4k, 4-8k, 8-16k, 16-32k, 32-64k, >64k

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

Rohbucket-Zählungen sind im Abschnitt histograms der JSON-Antwort für benutzerdefinierte Analysen verfügbar.

Sicherheitsüberlegungen

Der /tuning-advisor Endpunkt gibt Informationen über Ihre Verkehrsströme preis. Beschränken Sie immer den Zugriff:

location = /tuning-advisor {
    tuning_advisor_status;

    # Nur von localhost und internem Netzwerk zulassen
    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;

    # Oder Authentifizierung erforderlich machen
    # auth_basic "Tuning Advisor";
    # auth_basic_user_file /etc/nginx/.htpasswd;
}

Weiterführende Literatur