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

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 und 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

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.3.0, veröffentlicht am 29. April 2026.

Datengetriebene NGINX Proxy-Tuning-Empfehlungen aus echtem Verkehr

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 tatsächlicher Verkehr 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"
  },

  "ssl_buffer_size": {
    "observed": { "avg": "12.3k", "max": "2.1m", "p95_approx": "32.0k" },
    "recommendation": "OK",
    "suggested_value": "16k",
    "reason": "Die meisten Antworten überschreiten einen TLS-Datensatz; dynamische Datensatzgrößen oder ssl_buffer_size 4k bieten keinen messbaren Vorteil"
  },

  "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 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 → Passen Sie proxy_buffer_size an
Körpergrößen der Upstream-Antworten → Passen Sie proxy_buffers und ssl_buffer_size an
Antwortzeiten der Upstream → Passen Sie proxy_read_timeout an
Körpergrößen der Client-Anfragen → Passen Sie client_body_buffer_size an
Verbindungswiederverwendungsraten → Optimieren Sie die Keepalive-Einstellungen
Cache-Treffer-/Verpassraten → Bewerten Sie die Effektivität des Proxy-Caches

Leistung

Lock-freie Atomics — keine Mutexes, keine Konflikte zwischen Arbeitern
Gemeinsamer Speicher — alle Arbeiter 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 einsatzbereiten Konfigurationssnippets
Prometheus-Metriken zur Integration mit Grafana, Alertmanager und Freunden
Zurücksetzen-Endpunkt zum Löschen von Zählern und 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 gemeinsamen Speicherbereichs für die Aggregation von Metriken über mehrere Arbeiter. 1 MB ist ausreichend für die festen Zähler und Histogramme.

tuning_advisor_status

tuning_advisor_status;


Kontext	`location`

Aktiviert den Statushandler. 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 einsatzbereiten Konfigurationssnippet zurück.

Antwortstruktur:

Abschnitt	Beschreibung
`sample_size`	Insgesamt beobachtete proxied Anfragen
`uptime_seconds`	Sekunden seit Beginn der Sammlung (oder letzte Rücksetzung)
`requests_per_second`	Durchschnittliche Anforderungsrate
`proxy_buffer_size`	Headergrößenmetriken und Empfehlung
`proxy_buffers`	Körpergrößenmetriken und Empfehlung
`ssl_buffer_size`	TLS-Datensatzgrößenempfehlung, abgeleitet vom Körper P95
`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-/Verpass-/Umgehestatistiken
`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 Insgesamt beobachtete proxied Anfragen
# TYPE nginx_tuning_requests_total counter
nginx_tuning_requests_total 847293

# HELP nginx_tuning_header_size_bucket Headergrößenverteilung
# 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 von 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)
`ssl_buffer_size`	`REDUCE` auf `4k`	p95 Körper ≤ 4KB (Cloudflare-ähnliche statische Datensatzgröße)
	`OK` bei `16k`	p95 Körper > 4KB (Standard ist angemessen)
`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 Endpunkt /tuning-advisor 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 erlauben
    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 verlangen
    # auth_basic "Tuning Advisor";
    # auth_basic_user_file /etc/nginx/.htpasswd;
}

Weiterführende Literatur

Tuning proxy_buffer_size in NGINX — tiefgehende Analyse der Puffereinstellungen
NGINX Timeout-Direktiven erklärt — Verständnis aller Timeout-Einstellungen