NGINX Stub-status: de activiteit van de webserver live monitoren

Wat de NGINX Stub-status aangeeft

NGINX Stub-status levert basisstatistieken van de webserver als tekst via een geconfigureerd HTTP-eindpunt. Het antwoord beschrijft de activiteit van het opgevraagde NGINX-procescluster: met name clientverbindingen en het totale aantal getelde verzoeken. Je kunt deze gegevens lokaal opvragen en herhaaldelijk vergelijken, zonder daarvoor al een volledig monitoringsysteem te hoeven gebruiken.

Daarbij moet je twee soorten waarden uit elkaar houden: een Momentopname geeft bijvoorbeeld aan hoeveel clientverbindingen er actief zijn tijdens het ophalen. Totaltellers zoals requests geven daarentegen aan hoeveel verzoeken er in totaal zijn geteld. Pas door meerdere meterstanden over bekende tijdsintervallen met elkaar te vergelijken, kan een uitspraak worden gedaan over het aantal verzoeken.

De waarden zijn geen directe meting van het CPU- of geheugengebruik en geven evenmin een percentage weer van de beschikbare webservercapaciteit. Een groot aantal open verbindingen kan verschillende oorzaken en kosten hebben. Om de daadwerkelijke belasting in te schatten, heb je daarom aanvullende resource-statistieken en informatie over responstijden en fouten nodig.

Stub Status geeft geen uitsplitsing van de cijfers per virtuele website of opgevraagde URL. Als een installatie meerdere sites beheert, kun je aan de hand van het eindpunt alleen niet afleiden welke daarvan verantwoordelijk is voor een stijging. Bij meerdere NGINX-instanties moet je de waarden daarvan afzonderlijk registreren en eenduidig toewijzen.

Ook het opvragen van de statuspagina is op zich al een HTTP-verzoek en heeft een lichte invloed op de gemeten tellers. Hiermee moet rekening worden gehouden bij de interpretatie van kleine verzoekvolumes of zeer frequente opvragingen. Een enkele opvraging geeft sowieso slechts een momentopname weer; pas het verloop laat zien of de activiteit verandert.

Onderscheid maken tussen contacten en aanvragen

De waarde Actieve verbindingen omvat actieve clientverbindingen, inclusief de verbindingen in de wachtrij. Het telt dus niet alleen verbindingen waarover op dat moment een antwoord wordt verzonden. De statussen ‘Reading’, ‘Writing’ en ‘Waiting’ helpen om dit totale aantal in perspectief te plaatsen, maar geven geen informatie over het CPU-gebruik of het aantal actieve applicaties.

Bij een inkomend verzoek bevindt een verbinding zich in de status ‘Reading’, terwijl NGINX de header van het verzoek leest. Vervolgens kan de status 'Writing' verschijnen wanneer NGINX het antwoord verwerkt of schrijft. Dit betekent niet dat er gedurende de gehele tijd daadwerkelijk bytes naar de client stromen: ook het wachten op een upstream-antwoord kan hier deel van uitmaken.

Als er na een antwoord nog een verbinding open blijft staan voor verdere verzoeken, kan deze worden beschouwd als Wachten verschijnen. Deze status omvat inactieve clientverbindingen die wachten op een volgend verzoek. Een hoge ‘Waiting’-waarde op zich wijst daarom niet op overbelasting; deze kan ook passen bij een omgeving met veel hergebruikbare verbindingen.

Verbindingen en verzoeken zijn verschillende grootheden: via een keepalive-verbinding kunnen meerdere verzoeken achter elkaar worden verwerkt. Bij HTTP/2 kunnen meerdere verzoeken via één verbinding worden verzonden. Uit het aantal open verbindingen kan daarom geen vast aantal verzoeken worden afgeleid, en de requests-teller hoeft niet in dezelfde verhouding te stijgen als de verbindingstellers.

Voor een praktische beoordeling is het de moeite waard om meerdere verzoeken met elkaar te vergelijken: als de wachttijd toeneemt terwijl de responstijden en het aantal fouten ongewijzigd blijven, is dat in eerste instantie slechts een waarneming en geen reden tot ongerustheid. Hoe hergebruik en de grenzen daarvan kunnen worden geconfigureerd, wordt uitgelegd in het artikel over NGINX Keepalive-verzoeken.

Module en versie controleren

Voor Stub Status heb je een NGINX-installatie nodig met de module ngx_http_stub_status_module, toegang tot de configuratie ervan en later de mogelijkheid om het beveiligde eindpunt vanuit de daarvoor bestemde netwerkruimte op te vragen. De module wordt niet standaard in de NGINX-build opgenomen. Of een distributiepakket deze module bevat, hangt af van het betreffende pakket en moet ter plaatse worden gecontroleerd.

Controleer in de terminal de versie en de configure-parameters van het NGINX-binaire bestand dat daadwerkelijk door de dienst wordt gebruikt. De volgende opdracht geeft deze gegevens weer; onder de parameters staat --with-http_stub_status_module naar de betreffende build-optie.

nginx -V

De beslissende factor is de juist binair bestand: Een programma dat via het zoekpad is gestart nginx kan een andere installatie zijn dan die welke de dienst uitvoert. Controleer bij twijfel de configuratie van de dienst en het daar gebruikte opstartprogramma. Roep vervolgens, indien nodig, het betreffende binaire bestand expliciet op, in plaats van uit de uitvoer van een andere installatie conclusies te trekken over de productieve dienst.

Ook de versie is van invloed op de schrijfwijze van de richtlijn. Sinds NGINX 1.7.5 wordt stub_status zonder argument gebruikt; oudere versies hadden een willekeurig argument nodig, bijvoorbeeld on. De versiegrens is een compatibiliteitsindicatie, geen aanname over welke versie op je systeem is geïnstalleerd.

Als de build-optie ontbreekt in de gecontroleerde installatie, moet je, voordat je de configuratie wijzigt, nagaan welk pakket of welke build in jouw omgeving is bedoeld. Een statuslocatie alleen vult een ontbrekende module niet aan. Wijzigingen aan pakketten en de configuratie van diensten moeten worden uitgevoerd volgens de daarvoor geldende bedrijfs- en goedkeuringsprocedure.

Status-eindpunt beveiligd instellen

Om de status lokaal op te vragen, kun je een aparte Loopback-listener instellen. Het volgende voorbeeld is een bestandsconfiguratie voor de bestaande http-Context, geen terminalopdracht. Hiervoor is vereist dat de stub-statusmodule beschikbaar is en dat de voorbeeldpoort 8088 op het betreffende adres nog niet door een andere dienst wordt gebruikt.

server {
    listen 127.0.0.1:8088;
    server_name localhost;

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

De band met 127.0.0.1 beperkt deze listener tot de lokale IPv4-loopback-interface. De exacte locatie wijst alleen het opgegeven pad toe; de richtlijn stub_status levert daar de statusgegevens. De listener is daardoor niet bereikbaar via andere IPv4-interfaces, ongeacht of de overige websites openbaar zijn.

De Toegangsregels vullen de regel aan: NGINX controleert ze achtereenvolgens tot de eerste treffer. Het lokale IPv4-adres is toegestaan, alle andere adressen worden geweigerd. Omdat er in deze locatie eigen regels staan, worden toegangsregels van een bovenliggende context niet extra overgenomen. Controleer daarom de volledige configuratie voordat je het voorbeeld overneemt.

Bij containers is de netwerkruimte van cruciaal belang: een exporter in een aparte container bereikt via zijn eigen localhost Meestal niet de loopback-interface van de NGINX-container. Voor een externe aanvraag heb je een zorgvuldig gepland privéverbindingspad en passende toegangscontroles nodig. Maak de statuspagina niet zomaar openbaar; deze bevat bedrijfsinformatie.

Configuratie controleren en status opvragen

Controleer na het invoeren eerst de configuratie in de terminal. De volgende opdracht controleert de syntaxis en probeert de bestanden waarnaar wordt verwezen te openen. Gebruik daarbij het voor de dienst relevante NGINX-binaire bestand en, indien van toepassing, het afwijkende configuratiepad; een succesvolle controle activeert de wijziging nog niet.

nginx -t

A goedgekeurde herlaadbeurt is een afzonderlijke productieve stap. Voer deze pas uit na goedkeuring en volgens de operationele procedure van jouw omgeving. Bij het herladen laadt NGINX de configuratie opnieuw, start nieuwe workers met de nieuwe configuratie en sluit de oude workers op een geordende manier af. Controleer vervolgens of het gelukt is en bekijk de logbestanden, in plaats van uit de geslaagde syntaxiscontrole te concluderen dat er een actieve wijziging is doorgevoerd.

Nadat de activering is goedgekeurd, kun je het eindpunt lokaal in dezelfde netwerkruimte bereiken met curl opvragen. De schakelaar -i toont naast de inhoud van het antwoord ook de HTTP-status en de headers. In het volgende voorbeeld wordt ervan uitgegaan dat de listener en het pad al in het configuratiebestand zijn opgegeven.

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

Er wordt een succesvol HTTP-antwoord verwacht met statusgegevens als Tekst, niet als JSON. Bij een fout helpen de statuscode en de NGINX-logbestanden bij het opsporen van de oorzaak. Een succesvolle lokale opvraging toont echter alleen aan dat deze toegangsroute werkt: het bewijst niet dat er geen andere configuratie is waardoor het eindpunt van buitenaf bereikbaar is.

Statuswaarden uitlezen en snelheden berekenen

De uitvoer combineert actuele verbindingsstatussen met geaggregeerde waarden. Voor de interpretatie is dit onderscheid belangrijker dan de absolute grootte van een afzonderlijke waarde: Een huidige waarde beschrijft de toestand op het moment van opvraging; een totaalsteller geeft het aantal tot dan toe getelde gebeurtenissen weer. De tabel geeft een overzicht van de afzonderlijke velden en typische onjuiste conclusies.

Van de teller requests kan men een gemiddelde Aantal aanvragen Bereken voor een interval: trek de eerste waarde af van de tweede en deel het verschil door het aantal verstreken seconden. Illustratief rekenvoorbeeld, geen meting: als de waarde in 60 seconden stijgt van 12.000 naar 12.600, levert 600 gedeeld door 60 een gemiddelde op van 10 verzoeken per seconde.

Dit gemiddelde geeft noch de hoogste piek op korte termijn weer, noch welke URL’s zijn bezocht. Noteer voor elke opvraging het tijdstip en de opgevraagde instantie. Als de teller daalt of als je tussen instanties wisselt, mag je het eenvoudige verschil niet zonder controle als frequentie interpreteren; begin voor de betreffende instantie een nieuwe vergelijkingsreeks.

Als je intervallen van verschillende lengte met elkaar vergelijkt, moet je telkens uitgaan van de daadwerkelijk verstreken tijd in plaats van de geplande opvraaginterval. Een opvraging met een vertraging van twee minuten vereist bijvoorbeeld een andere deler dan een opvraging na één minuut. Een langere observatieperiode vlakt kortetermijnschommelingen sterker af; korte intervallen maken veranderingen beter zichtbaar, maar verhogen het aantal statusopvragingen.

Ook de statusopvraging zelf is een HTTP-verzoek en heeft een gering effect op de gemeten tellers. Dit speelt vooral een rol bij zeer weinig verkeer of bij frequente opvragingen. Een regelmatig, gedocumenteerd opvraaginterval maakt het gemakkelijker om bij de interpretatie rekening te houden met dergelijke monitoringpercentages.

Bij meerdere instanties bereken je het gemiddelde eerst op basis van de opeenvolgende waarden van elke afzonderlijke instantie. Pas daarna kunnen de percentages voor vergelijkbare periodes worden samengevoegd. Als er een afhaling ontbreekt of de toewijzing van een exemplaar verandert, moet het ontstane gat zichtbaar blijven, in plaats van een schijnbaar ononderbroken verloop te simuleren.

Fouten en beperkingen onderzoeken

Als het status-eindpunt met HTTP 403 reageert, controleer dan eerst het bronadres dat daadwerkelijk bij NGINX binnenkomt en de toegangsregels van de locatie. allow en deny worden achtereenvolgens geëvalueerd totdat de eerste treffer wordt gevonden. Eigen regels in de locatie vervangen, indien van toepassing, overgenomen regels; ze vormen daar niet automatisch een aanvulling op.

Bij een HTTP 404-fout moet je eerst op andere punten zoeken: kloppen de poort en de listener, het opgevraagde pad en het geselecteerde serverblok? Controleer bovendien of de beoogde configuratie na het herladen daadwerkelijk actief is. Een succesvolle lokale aanroep via een andere poort of een ander pad bewijst niet dat de gewenste locatie is bereikt.

Als er helemaal geen HTTP-antwoord wordt ontvangen, maak dan onderscheid tussen de bereikbaarheid van de listener en een antwoord met een foutstatus. Controleer eerst het adres, de poort en het netwerkbereik van het aanvragende proces, evenals de servicestatus. Pas wanneer er verbinding is gemaakt met de juiste listener, helpen de HTTP-status en de geselecteerde locatie bij het verder afbakenen van het probleem.

Voor de lopende foutanalyse is het de moeite waard om de totaltellers te vergelijken accepteert en verwerkt. Normaal gesproken zijn ze gelijk. Als het verschil groter wordt, kan dit te maken hebben met het bereiken van een limiet voor de beschikbare bronnen; de vergelijking van de tellers alleen geeft echter geen uitsluitsel over de concrete oorzaak, noch over het aantal afgewezen HTTP-verzoeken. Betrek daarom de foutlogboeken en de configuratie bij het onderzoek.

Een reeds bestaand verschil geeft in eerste instantie alleen het verschil tussen de twee totaaltellers weer. Om te beoordelen of de situatie tijdens de observatieperiode is veranderd, vergelijk je dit verschil bij meerdere opvragingen van dezelfde instantie. Noteer de betreffende periode, zodat je de bijbehorende logboekvermeldingen en systeemgebeurtenissen kunt opzoeken.

De richtlijn worker_connections beperkt het aantal verbindingen per worker, niet uitsluitend clientverbindingen. Hieronder vallen bijvoorbeeld ook verbindingen met servers via een proxy; daarnaast kunnen limieten voor bestandsdescriptoren een beperking vormen. Het aantal actieve verbindingen gedeeld door het aantal workers maal worker_connections daardoor is er geen betrouwbaar beeld van de capaciteitsbenutting. Controleer in plaats daarvan de daadwerkelijke limieten en het overige verbruik van middelen in de context.

Een wijziging van verbindingslimieten mag niet uitsluitend worden gebaseerd op een hoge statuswaarde. Ga eerst na of een limiet daadwerkelijk wordt bereikt en welke andere bronnen of upstream-verbindingen hierbij betrokken zijn. Plan mogelijke wijzigingen in combinatie met het monitoren van fouten en responstijden en controleer deze volgens de vastgestelde operationele procedure.

Verloop en upstream-problemen in kaart brengen

Een eenmalige statusopvraging geeft slechts één moment weer. Herhaalde opvragingen met vaste tussenpozen helpen daarentegen om te vaststellen of de verbindingsstatus boven een normaal niveau stijgt of na een piek weer afneemt. Registreer meerdere NGINX-instanties afzonderlijk en noteer welke instantie achter elke tijdreeks schuilgaat; anders kunnen wisselingen tussen eindpunten het verloop vertekenen.

Een hoge Waiting-waarde geeft een overzicht van wachtende, momenteel inactieve clientverbindingen. Op zich is dit geen bewijs van overbelasting: bij hergebruikte verbindingen kunnen clients wachten op verdere verzoeken. Een stijging wordt pas echt veelzeggend als je deze vergelijkt met responstijden, fouten en resource-statistieken over dezelfde periode.

Blijft Schrijven Als de belasting gedurende langere tijd verhoogd is, onderzoek dan zowel de upstream-tijden als het gedrag van de clients. Deze status betekent niet dat er continu bytes worden verzonden; hieronder kan ook de wachttijd op een upstream-antwoord vallen. De status ‘Stub’ geeft geen informatie over de betreffende backend-dienst, noch over de oorzaak van een vertraging.

Aanvullende gegevens helpen bij het toewijzen: toegangslogs en geregistreerde upstream-tijden laten zien welke verzoeken en backends opvallen; foutlogs geven aanwijzingen over mislukte verbindingen. Als het gaat om CPU- of geheugenbelasting, heb je de bijbehorende systeemstatistieken nodig. Als herhaaldelijk tot stand brengen van verbindingen met de backend het onderzoek beïnvloedt, legt het artikel over NGINX Upstream Keepalive de configuratie van herbruikbare upstream-verbindingen.

Van status naar monitoring

Voor een incidentele diagnose kan een beveiligde lokale statusopvraging volstaan. Deze geeft aan welke basiswaarden de opgevraagde instantie op dat moment rapporteert, maar slaat zelf geen historisch overzicht op. Als je ontwikkelingen wilt vergelijken of op de hoogte wilt worden gesteld bij aanhoudende afwijkingen, heb je een regelmatige registratie en een systeem voor tijdreeksen en alarmen nodig.

De officiële NGINX Prometheus-exporter Hiervoor is er een aparte component: deze haalt de status van de stub op en stelt de gegevens beschikbaar als Prometheus-metrieken. Prometheus haalt vervolgens de exporter-eindpunt op. Plan de bereikbaarheid en de toegangsbeperking voor beide routes, dus zowel voor het status-eindpunt als voor de metriek-uitvoer van de exporter.

Noteer tijdens de configuratie welke exporter welke NGINX-instantie opvraagt en vanaf welke locatie Prometheus de exporter bereikt. Vooral bij afzonderlijke containers gaat het hier om twee verschillende netwerkpaden. Een bereikbaar eindpunt van de exporter is daarom op zichzelf geen vervanging voor de controle of de exporter op zijn beurt de juiste statuspagina succesvol kan ophalen.

De aanvullende registratie zorgt er niet voor dat de basiswaarden worden omgezet in gedetailleerde statistieken over responstijden of HTTP-statusklassen. Voor vragen over trage URL’s, foutmeldingen of afzonderlijke upstreams zijn geschikte toegangslogs en aanvullende telemetriegegevens nodig. Ook de uitgebreidere NGINX Plus API Er moet onderscheid worden gemaakt tussen Stub Status en NGINX Open Source; hun beschikbaarheid en configuratie zijn niet onderling uitwisselbaar.

Kies aanvullende gegevens op basis van de specifieke vraag: voor een stijgend aantal verzoeken volstaat in eerste instantie een vergelijking van de teller in de tijd. Als het daarentegen gaat om trage antwoorden of een bepaalde backend-dienst, heb je latentie- en upstream-gegevens nodig die in de tijd aansluiten. De statuspagina kan aanleiding geven tot onderzoek, maar kan de oorzaak niet op zichzelf vaststellen.

Alarmdrempels moeten worden afgestemd op het normale gedrag van de betreffende instantie en op de servicedoelstellingen, niet op een algemeen getal voor ‘Waiting’ of ‘Writing’. Vergelijk afwijkingen met latenties, fouten en beschikbare middelen en controleer of een alarm daadwerkelijk aanleiding geeft tot actie. Zo wordt een enkele tellerstand een aanleiding voor een gericht onderzoek in plaats van een overhaaste diagnose.

Houd bij het opstellen van het alarmplan ook rekening met het uitvallen van het registratiekanaal: ontbrekende gegevens zijn niet hetzelfde als nul verzoeken of nul verbindingen. Een afzonderlijke controle van de bereikbaarheid helpt om een mislukte opvraging te onderscheiden van daadwerkelijk lage activiteit. Bepaal bovendien wie een alarm afhandelt en welke aanvullende gegevens beschikbaar moeten zijn voor de diagnose.