TIL: nginx Debug-Log nur für bestimmte Verbindungen

Ich habe heute zum zweiten Mal in diesem Jahr nginx-Verbindungen debuggen müssen und musste erst wieder die Suchmaschine zum genauen Vorgehen befragen. Beim nächsten Mal weiß ich, dass ich hier einen Blogpost dazu habe.

Verhält sich nginx merkwürdig und möchte man die Ursachen finden, hilft das Debug-Log ungemein. Hier wird der Weg eines Requests von der Entgegennahme durch nginx bis zum Aufräumen nach dem Absenden der Response detailliert geloggt.

Für jede Anfrage kommt hier eine beeindruckende Zahl an Zeilen im Logfile zusammen: 300 oder 400 Zeilen sind durchaus normal. Das lässt sich auf Produktivsystem normalerweise nicht mehr ins Filesystem wegschreiben ohne ganz andere Probleme zu bekommen[1].

nginx bietet aber eine Option an, das Debug-Log nur für Requests von bestimmten IP-Adressen zu schreiben.

In der events-Section der Config werden einfach eine oder mehrere debug_connection-Direktiven angegeben:

1
2
3
4
events {
    debug_connection 127.0.0.1;
    debug_connection 10.0.2.0/24;
}

Für jeden Request von der angegebenen IP bzw. Netrange wird jetzt im Error-Log (bzw. in allen konfigurierten Error-Logs) ausführlich geloggt.

Hat man noch einen Proxy vor dem nginx, z. B. Cloudflare o. Ä, dann kann man die Requests ganz einfach mit curl am Proxy vorbei direkt an den Server senden:

1
curl --resolve www.example.org:443:10.0.1.10 https://www.example.org/

Hierbei wird curl gesagt, wie der Name www.example.org aufzulösen ist – 10.0.1.10 ist in diesem Beispiel die tatsächliche IP-Adresse des Servers. Damit kommt der Request aus der Sicht von nginx von einer IP-Adresse, die auch in debug_connection gelistet ist und so kann dann das Debug-Log aktiviert werden.

Die ausführliche Dokumentation gibt es bei nginx: A debugging log.


  1. der Vollständigkeit halber: es besteht die Möglichkeit das Log auch in einen zyklischen Buffer ins RAM zu schreiben