NGINX Stub Status: Webserver-Aktivität live überwachen

Was NGINX Stub Status zeigt

NGINX Stub Status stellt grundlegende Webserver Metrics über einen konfigurierten HTTP-Endpunkt als Text bereit. Die Antwort beschreibt die Aktivität des abgefragten NGINX-Prozessverbunds: insbesondere Client-Verbindungen und die insgesamt gezählten Anfragen. Du kannst sie lokal abrufen und wiederholt vergleichen, ohne dafür bereits ein vollständiges Monitoring-System einzusetzen.

Dabei musst du zwei Arten von Werten auseinanderhalten: Eine Momentaufnahme zeigt beispielsweise, wie viele Client-Verbindungen beim Abruf aktiv sind. Gesamtzähler wie requests geben dagegen an, wie viele Anfragen insgesamt gezählt wurden. Erst der Vergleich mehrerer Zählerstände über bekannte Zeitabstände erlaubt eine Aussage über die Anfragerate.

Die Werte sind keine direkte Messung der CPU- oder Speicherauslastung und ergeben auch keinen Prozentwert für die verfügbare Webserver-Kapazität. Viele offene Verbindungen können unterschiedliche Ursachen und Kosten haben. Für eine Einschätzung der tatsächlichen Belastung brauchst du deshalb zusätzlich Ressourcenmetriken und Informationen über Antwortzeiten und Fehler.

Stub Status schlüsselt die Zahlen nicht nach virtueller Website oder angeforderter URL auf. Betreibt eine Installation mehrere Sites, lässt sich aus dem Endpunkt allein nicht ablesen, welche davon für einen Anstieg verantwortlich ist. Bei mehreren NGINX-Instanzen solltest du deren Werte getrennt erfassen und eindeutig zuordnen.

Auch der Abruf der Statusseite ist selbst eine HTTP-Anfrage und beeinflusst die beobachteten Zähler geringfügig. Das ist bei der Interpretation kleiner Anfragevolumen oder sehr häufiger Abfragen zu berücksichtigen. Ein einzelner Abruf liefert ohnehin nur einen Ausschnitt; erst der Verlauf zeigt, ob sich die Aktivität verändert.

Verbindungen und Anfragen unterscheiden

Der Wert Active connections umfasst aktive Client-Verbindungen einschließlich der wartenden Verbindungen. Er zählt also nicht nur Verbindungen, über die gerade eine Antwort übertragen wird. Die Zustände Reading, Writing und Waiting helfen dabei, diese Gesamtzahl einzuordnen, beschreiben aber weder CPU-Verbrauch noch die Zahl beschäftigter Anwendungen.

Bei einer eingehenden Anfrage befindet sich eine Verbindung im Zustand Reading, während NGINX den Anfrage-Header liest. Anschließend kann sie in Writing erscheinen, wenn NGINX die Antwort verarbeitet beziehungsweise schreibt. Das bedeutet nicht, dass während der gesamten Zeit tatsächlich Bytes zum Client fließen: Auch das Warten auf eine Upstream-Antwort kann dazugehören.

Bleibt eine Verbindung nach einer Antwort für weitere Anfragen offen, kann sie als Waiting erscheinen. Dieser Zustand umfasst inaktive Client-Verbindungen, die auf eine nächste Anfrage warten. Ein hoher Waiting-Wert allein beweist daher keine Überlastung; er kann auch zu einem Betrieb mit vielen wiederverwendbaren Verbindungen passen.

Verbindungen und Anfragen sind verschiedene Größen: Über eine Keepalive-Verbindung können nacheinander mehrere Anfragen laufen. Bei HTTP/2 können mehrere Anfragen über eine Verbindung übertragen werden. Aus der Anzahl offener Verbindungen lässt sich deshalb keine feste Anzahl von Anfragen ableiten, und der requests-Zähler muss nicht im gleichen Verhältnis wie die Verbindungszähler steigen.

Für die praktische Bewertung lohnt sich der Vergleich über mehrere Abrufe: Steigt Waiting, während Antwortzeiten und Fehler unauffällig bleiben, ist das zunächst eine Beobachtung und kein Alarmbeweis. Wie sich Wiederverwendung und ihre Grenzen konfigurieren lassen, erläutert der Beitrag zu NGINX Keepalive Requests.

Modul und Version prüfen

Für Stub Status benötigst du eine NGINX-Installation mit dem Modul ngx_http_stub_status_module, Zugriff auf ihre Konfiguration und später eine Möglichkeit, den geschützten Endpunkt aus dem vorgesehenen Netzwerkraum abzufragen. Das Modul wird beim NGINX-Build nicht standardmäßig eingebunden. Ob ein Distributionspaket es enthält, hängt vom jeweiligen Paket ab und muss vor Ort geprüft werden.

Prüfe im Terminal die Version und die Configure-Parameter der tatsächlich vom Dienst verwendeten NGINX-Binärdatei. Der folgende Befehl zeigt diese Angaben an; unter den Parametern weist --with-http_stub_status_module auf die entsprechende Build-Option hin.

nginx -V

Entscheidend ist die richtige Binärdatei: Ein über den Suchpfad gestartetes nginx kann eine andere Installation sein als diejenige, die der Dienst ausführt. Bestehen Zweifel, prüfe die Dienstkonfiguration und den dort verwendeten Programmstart. Rufe anschließend gegebenenfalls die betreffende Binärdatei ausdrücklich auf, statt aus der Ausgabe einer anderen Installation auf den produktiven Dienst zu schließen.

Auch die Version beeinflusst die Schreibweise der Direktive. Seit NGINX 1.7.5 wird stub_status ohne Argument verwendet; ältere Versionen benötigten ein beliebiges Argument, etwa on. Die Versionsgrenze ist eine Kompatibilitätsinformation, keine Annahme darüber, welche Version auf deinem System installiert ist.

Fehlt die Build-Option bei der geprüften Installation, solltest du vor einer Konfigurationsänderung klären, welches passende Paket oder welcher Build in deiner Umgebung vorgesehen ist. Eine Status-Location allein ergänzt kein fehlendes Modul. Änderungen an Paketen und Dienstkonfiguration gehören in das dafür geltende Betriebs- und Freigabeverfahren.

Status-Endpunkt geschützt einrichten

Für eine lokale Statusabfrage kannst du einen separaten Loopback-Listener einrichten. Das folgende Beispiel ist eine Dateikonfiguration für den bestehenden http-Kontext, kein Terminalbefehl. Es setzt voraus, dass das Stub-Status-Modul verfügbar ist und der Beispielport 8088 auf der betreffenden Adresse nicht bereits von einem anderen Dienst belegt wird.

server {
    listen 127.0.0.1:8088;
    server_name localhost;

    location = /stub_status {
        stub_status;
        allow 127.0.0.1;
        deny all;
    }
}

Die Bindung an 127.0.0.1 begrenzt diesen Listener auf das lokale IPv4-Loopback-Interface. Die exakte Location ordnet nur den angegebenen Pfad zu; die Direktive stub_status liefert dort die Statusdaten. Der Listener ist damit nicht über andere IPv4-Interfaces erreichbar, unabhängig davon, ob die übrigen Websites öffentlich sind.

Die Zugriffsregeln ergänzen die Bindung: NGINX prüft sie der Reihe nach bis zum ersten Treffer. Die lokale IPv4-Adresse ist erlaubt, alle anderen Adressen werden abgewiesen. Weil in dieser Location eigene Regeln stehen, werden Access-Regeln eines übergeordneten Kontexts nicht zusätzlich geerbt. Prüfe deshalb die vollständige Konfiguration, bevor du das Beispiel übernimmst.

Bei Containern ist der Netzwerkraum entscheidend: Ein Exporter in einem separaten Container erreicht über sein eigenes localhost normalerweise nicht das Loopback-Interface des NGINX-Containers. Für eine entfernte Abfrage brauchst du einen bewusst geplanten privaten Verbindungspfad und passende Zugriffskontrollen. Gib die Statusseite nicht einfach öffentlich frei; sie enthält Betriebsinformationen.

Konfiguration prüfen und Status abrufen

Prüfe nach dem Eintragen zunächst die Konfiguration im Terminal. Der folgende Befehl untersucht die Syntax und versucht, referenzierte Dateien zu öffnen. Verwende dabei die für den Dienst maßgebliche NGINX-Binärdatei und gegebenenfalls dessen abweichenden Konfigurationspfad; eine erfolgreiche Prüfung aktiviert die Änderung noch nicht.

nginx -t

Ein freigegebener Reload ist ein eigener produktiver Schritt. Führe ihn erst nach Freigabe und gemäß dem Betriebsverfahren deiner Umgebung aus. Beim Reload lädt NGINX die Konfiguration neu, startet neue Worker mit der neuen Konfiguration und beendet die alten Worker geordnet. Kontrolliere anschließend den Erfolg und die Logs, statt aus dem bestandenen Syntaxcheck auf eine aktive Änderung zu schließen.

Nach der genehmigten Aktivierung kannst du den Endpunkt im selben Netzwerkraum lokal mit curl abfragen. Der Schalter -i zeigt neben dem Antwortkörper auch den HTTP-Status und die Header. Das folgende Beispiel setzt den Listener und den Pfad aus der Dateikonfiguration voraus.

curl -i http://127.0.0.1:8088/stub_status

Erwartet wird eine erfolgreiche HTTP-Antwort mit Statusdaten als Text, nicht als JSON. Bei einem Fehler helfen Statuscode und NGINX-Logs bei der Eingrenzung. Ein erfolgreicher lokaler Abruf zeigt aber nur, dass dieser Zugriffsweg funktioniert: Er beweist nicht, dass keine andere Konfiguration den Endpunkt von außen erreichbar macht.

Statuswerte lesen und Raten berechnen

Die Ausgabe kombiniert aktuelle Verbindungszustände mit aufsummierten Werten. Für die Interpretation ist diese Unterscheidung wichtiger als die absolute Höhe eines einzelnen Werts: Ein Momentanwert beschreibt den Zustand beim Abruf, ein Gesamtzähler die bis dahin gezählten Ereignisse. Die Tabelle ordnet die einzelnen Felder und typische Fehlschlüsse ein.

Aus dem Zähler requests lässt sich eine durchschnittliche Anfragerate für ein Intervall berechnen: Ziehe den ersten Stand vom zweiten ab und teile die Differenz durch die verstrichenen Sekunden. Illustratives Rechenbeispiel, keine Messung: Steigt der Wert in 60 Sekunden von 12.000 auf 12.600, ergeben 600 geteilt durch 60 durchschnittlich 10 Anfragen pro Sekunde.

Dieser Durchschnitt zeigt weder die höchste kurzfristige Spitze noch, welche URLs aufgerufen wurden. Notiere für jeden Abruf den Zeitpunkt und die abgefragte Instanz. Sinkt der Zähler oder wechselst du zwischen Instanzen, darfst du die einfache Differenz nicht ungeprüft als Rate interpretieren; beginne für die betreffende Instanz eine neue Vergleichsreihe.

Vergleichst du Intervalle unterschiedlicher Länge, rechne jeweils mit der tatsächlich verstrichenen Zeit statt mit dem geplanten Abrufabstand. Ein verzögerter Abruf über zwei Minuten benötigt beispielsweise einen anderen Divisor als ein Abruf nach einer Minute. Eine längere Betrachtung glättet kurzfristige Schwankungen stärker; kurze Intervalle machen Veränderungen sichtbarer, erhöhen aber den Anteil der Statusabfragen.

Auch die Statusabfrage selbst ist eine HTTP-Anfrage und beeinflusst die beobachteten Zähler geringfügig. Das fällt besonders bei sehr niedrigem Verkehr oder häufigem Abruf ins Gewicht. Ein regelmäßiges, dokumentiertes Abfrageintervall erleichtert es, solche Monitoring-Anteile bei der Einordnung zu berücksichtigen.

Bei mehreren Instanzen berechnest du die Rate zunächst aus den aufeinanderfolgenden Werten jeder einzelnen Instanz. Erst danach lassen sich die Raten für vergleichbare Zeiträume zusammenführen. Fehlt ein Abruf oder ändert sich die Zuordnung einer Instanz, sollte die entstehende Lücke sichtbar bleiben, statt einen scheinbar durchgehenden Verlauf vorzutäuschen.

Fehler und Grenzen untersuchen

Antwortet der Status-Endpunkt mit HTTP 403, prüfe zuerst die tatsächlich bei NGINX ankommende Quelladresse und die Access-Regeln der Location. allow und deny werden der Reihe nach bis zum ersten Treffer ausgewertet. Eigene Regeln in der Location ersetzen gegebenenfalls geerbte Regeln; sie ergänzen diese nicht automatisch.

Bei HTTP 404 liegt die Suche zunächst an anderer Stelle: Stimmen Port und Listener, der angeforderte Pfad und der ausgewählte Serverblock? Prüfe außerdem, ob die vorgesehene Konfiguration nach dem Reload tatsächlich aktiv ist. Ein erfolgreicher lokaler Aufruf unter einem anderen Port oder Pfad belegt nicht, dass die gewünschte Location angesprochen wurde.

Kommt überhaupt keine HTTP-Antwort zustande, unterscheide die Erreichbarkeit des Listeners von einer Antwort mit Fehlerstatus. Prüfe zunächst Adresse, Port und Netzwerkraum des abrufenden Prozesses sowie den Dienstzustand. Erst wenn eine Verbindung zum richtigen Listener zustande kommt, helfen HTTP-Status und ausgewählte Location bei der weiteren Eingrenzung.

Für die laufende Fehleranalyse lohnt sich der Vergleich der Gesamtzähler accepts und handled. Normalerweise sind sie gleich. Wächst ihre Differenz, kann ein erreichtes Ressourcenlimit beteiligt sein; der Zählervergleich allein weist aber weder die konkrete Ursache noch die Zahl abgelehnter HTTP-Anfragen nach. Beziehe deshalb Fehlerlogs und Konfiguration in die Untersuchung ein.

Eine bereits bestehende Differenz zeigt zunächst nur den Abstand der beiden Gesamtzähler. Um zu beurteilen, ob sich die Situation im Beobachtungszeitraum verändert, vergleiche diesen Abstand bei mehreren Abrufen derselben Instanz. Halte den betreffenden Zeitraum fest, damit du passende Logeinträge und Betriebsereignisse dazu suchen kannst.

Die Direktive worker_connections begrenzt Verbindungen pro Worker, nicht ausschließlich Client-Verbindungen. Dazu gehören beispielsweise auch Verbindungen zu proxied Servern; zusätzlich können Dateideskriptor-Limits begrenzen. Aus Active connections geteilt durch Worker-Zahl mal worker_connections ergibt sich daher keine verlässliche Kapazitätsauslastung. Prüfe stattdessen die tatsächlichen Limits und den übrigen Ressourcenverbrauch im Kontext.

Eine Änderung von Verbindungslimits sollte nicht allein auf einem hohen Statuswert beruhen. Kläre zuerst, ob ein Limit tatsächlich erreicht wird und welche anderen Ressourcen oder Upstream-Verbindungen beteiligt sind. Plane mögliche Änderungen zusammen mit der Beobachtung von Fehlern und Antwortzeiten und prüfe sie nach dem vorgesehenen Betriebsverfahren.

Verläufe und Upstream-Probleme einordnen

Ein einzelner Statusabruf zeigt nur einen Zeitpunkt. Wiederholte Abfragen in festen Abständen helfen dagegen zu erkennen, ob Verbindungszustände über ein normales Niveau hinaus ansteigen oder nach einer Spitze wieder zurückgehen. Erfasse mehrere NGINX-Instanzen getrennt und halte fest, welche Instanz hinter jeder Zeitreihe steht; andernfalls können Wechsel zwischen Endpunkten den Verlauf verfälschen.

Ein hoher Waiting-Wert beschreibt wartende, momentan inaktive Client-Verbindungen. Er ist für sich genommen kein Beleg für Überlastung: Bei wiederverwendeten Verbindungen können Clients auf weitere Anfragen warten. Aussagekräftiger wird ein Anstieg, wenn du ihn mit Antwortzeiten, Fehlern und Ressourcenmetriken über denselben Zeitraum vergleichst.

Bleibt Writing über längere Zeit erhöht, untersuche sowohl Upstream-Zeiten als auch das Verhalten der Clients. Der Zustand bedeutet nicht, dass fortlaufend Bytes gesendet werden; dazu kann auch die Wartezeit auf eine Upstream-Antwort gehören. Stub Status benennt weder den betroffenen Backend-Dienst noch die Ursache einer Verzögerung.

Für die Zuordnung helfen ergänzende Daten: Zugriffslogs und erfasste Upstream-Zeiten zeigen, welche Anfragen und Backends auffällig sind; Fehlerlogs liefern Hinweise auf fehlgeschlagene Verbindungen. Geht es um CPU- oder Speicherdruck, brauchst du entsprechende Systemmetriken. Wenn wiederholter Verbindungsaufbau zum Backend die Untersuchung betrifft, erklärt der Beitrag zu NGINX Upstream Keepalive die Konfiguration wiederverwendbarer Upstream-Verbindungen.

Vom Status zum Monitoring

Für eine gelegentliche Diagnose kann eine geschützte lokale Statusabfrage ausreichen. Sie beantwortet, welche Basiswerte die abgefragte Instanz gerade meldet, speichert aber selbst keinen Verlauf. Sollst du Entwicklungen vergleichen oder bei anhaltenden Auffälligkeiten benachrichtigt werden, brauchst du eine regelmäßige Erfassung und ein System für Zeitreihen und Alarme.

Der offizielle NGINX Prometheus Exporter ist dafür eine getrennte Komponente: Er ruft Stub Status ab und stellt die Daten als Prometheus-Metriken bereit. Prometheus ruft anschließend den Exporter-Endpunkt ab. Plane die Erreichbarkeit und Zugriffsbeschränkung für beide Wege, also sowohl zum Status-Endpunkt als auch zur Metrikausgabe des Exporters.

Dokumentiere bei der Einrichtung, welcher Exporter welche NGINX-Instanz abfragt und von wo Prometheus den Exporter erreicht. Gerade bei getrennten Containern sind das zwei unterschiedliche Netzwerkwege. Ein erreichbarer Exporter-Endpunkt allein ersetzt deshalb nicht die Prüfung, ob der Exporter seinerseits die richtige Statusseite erfolgreich abrufen kann.

Die zusätzliche Erfassung macht aus den Basiswerten keine detaillierten Antwortzeit- oder HTTP-Statusklassenmetriken. Für Fragen nach langsamen URLs, Fehlerantworten oder einzelnen Upstreams sind geeignete Zugriffslogs und weitere Telemetrie nötig. Auch die umfangreichere NGINX Plus API ist von Stub Status in NGINX Open Source zu unterscheiden; ihre Verfügbarkeit und Konfiguration sind nicht austauschbar.

Wähle zusätzliche Daten nach der konkreten Frage: Für eine steigende Anfragerate genügt zunächst der zeitliche Vergleich des Zählers. Geht es dagegen um langsame Antworten oder einen bestimmten Backend-Dienst, brauchst du zeitlich passende Latenz- und Upstream-Daten. Die Statusseite kann einen Anlass zur Untersuchung liefern, die Zuordnung aber nicht allein leisten.

Alarmschwellen sollten sich am Normalverhalten der jeweiligen Instanz und an den Dienstzielen orientieren, nicht an einer allgemeinen Zahl für Waiting oder Writing. Vergleiche Auffälligkeiten mit Latenzen, Fehlern und verfügbaren Ressourcen und prüfe, ob ein Alarm tatsächlich handlungsrelevant ist. So wird aus einem einzelnen Zähler ein Anlass für eine gezielte Untersuchung statt einer voreiligen Diagnose.

Berücksichtige bei der Alarmplanung auch den Ausfall des Erfassungswegs: Fehlende Daten sind nicht dasselbe wie null Anfragen oder null Verbindungen. Eine getrennte Prüfung der Erreichbarkeit hilft, einen ausgefallenen Abruf von tatsächlich niedriger Aktivität zu unterscheiden. Lege außerdem fest, wer einen Alarm bearbeitet und welche weiteren Daten für die Diagnose verfügbar sein müssen.