upstream-log: Schreibt Upstream-Anforderungsprotokolle in einem bestimmten Format

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-upstream-log

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-upstream-log

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

load_module modules/ngx_http_upstream_log_module.so;

Dieses Dokument beschreibt nginx-module-upstream-log v0.1.1, veröffentlicht am 06. Januar 2026.

Im Gegensatz zum Zugriffsprotokollmodul wird es am Ende jeder Upstream-Anfrage protokolliert. Wenn während der Anforderungsverarbeitung mehrere Server kontaktiert wurden, wird am Ende jedes Kontakts ein Upstream-Protokoll aufgezeichnet. Wenn eine interne Umleitung von einer Servergruppe zu einer anderen erfolgt, die durch „X-Accel-Redirect“ oder error_page initiiert wurde, wird ebenfalls am Ende jedes Kontakts ein Upstream-Protokoll aufgezeichnet.

~~Dieses Modul bietet auch eine Reihe von Variablen für das Upstream-Logging. Viele dieser Variablen beginnen mit $upstream_last_, was verwendet wird, um sie von den Variablen in ngx_http_upstream zu unterscheiden. Diese Variablen geben nur Informationen zurück, die sich auf den aktuellen Kontakt mit dem Upstream beziehen, oder Informationen, die sich auf den letzten Kontakt mit dem Upstream beziehen. Kommas und Doppelpunkte werden nicht verwendet, um Informationen über mehrere Kontakte mit dem Upstream aufzuzeichnen.~~

Hinweis: Dieses Modul exportiert keine zusätzlichen Variablen mehr. Zusätzliche Upstream-Variablen wurden in ngx_http_extra_variables_module verschoben.

Die Verwendung dieses Moduls ist sehr ähnlich wie bei ngx_http_log_module. Verwenden Sie einfach die upstream_log-Direktive, um den Pfad, das Format und die Konfiguration für einen gepufferten Protokolleintrag festzulegen.

Synopsis

    http {

        log_format access '$remote_addr - $remote_user [$time_local] "$request" '
                        '$status $body_bytes_sent "$http_referer" '
                        '"$http_user_agent" "$http_x_forwarded_for"';

        log_format upstream '$remote_addr $upstream_last_addr [$time_local] "$upstream_method $upstream_uri" '
                                 '$upstream_last_status $upstream_last_response_length $upstream_last_bytes_sent $upstream_last_bytes_received '
                                 '$upstream_last_connect_time $upstream_last_header_time $upstream_last_response_time';

        upstream cluster {
            server 192.168.0.1:80;
            server 192.168.0.2:80;
        }

        server {
            listen 80;

            access_log logs/access.log access;
            upstream_log logs/upstream.log upstream;

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

    }

Direktive

upstream_log

Syntax: upstream_log path [format [buffer=size] [gzip[=level]] [flush=time] [if=condition]]; upstream_log off;
Standard: -;
Kontext: http, server, location, if in location, limit_except

Legt den Pfad, das Format und die Konfiguration für einen gepufferten Protokolleintrag fest. Mehrere Protokolle können auf derselben Konfigurationsebene angegeben werden. Das Protokollieren in syslog kann konfiguriert werden, indem das Präfix „syslog:“ im ersten Parameter angegeben wird. Der spezielle Wert off hebt alle upstream_log-Direktiven auf der aktuellen Ebene auf. Im Gegensatz zur access_log-Direktive akzeptiert diese Direktive nicht das vordefinierte "combined" Format. Sie müssen zuerst das Protokollformat mit der log_format-Direktive definieren und dann mit dieser Direktive darauf verweisen.

Wenn entweder der Puffer- oder der gzip-Parameter verwendet wird, werden die Protokolleinträge gepuffert.

Die Puffergröße darf die Größe eines atomaren Schreibvorgangs in eine Datei nicht überschreiten. Für FreeBSD ist diese Größe unbegrenzt.

Wenn das Puffern aktiviert ist, werden die Daten in die Datei geschrieben:

wenn die nächste Protokollzeile nicht in den Puffer passt;
wenn die gepufferten Daten älter sind als durch den flush-Parameter angegeben;
wenn ein Worker-Prozess Protokolldateien erneut öffnet oder heruntergefahren wird. Wenn der gzip-Parameter verwendet wird, werden die gepufferten Daten vor dem Schreiben in die Datei komprimiert. Der Komprimierungsgrad kann zwischen 1 (schnellste, weniger Kompression) und 9 (langsamste, beste Kompression) eingestellt werden. Standardmäßig beträgt die Puffergröße 64K Bytes und der Komprimierungsgrad ist auf 1 eingestellt. Da die Daten in atomaren Blöcken komprimiert werden, kann die Protokolldatei jederzeit mit „zcat“ dekomprimiert oder gelesen werden.

Beispiel:

upstream_log /path/to/log.gz upstream gzip flush=5m;

Damit die gzip-Kompression funktioniert, muss nginx mit der zlib-Bibliothek erstellt werden. Der Dateipfad kann Variablen enthalten, aber solche Protokolle haben einige Einschränkungen:

Der Benutzer, dessen Anmeldeinformationen von den Worker-Prozessen verwendet werden, sollte die Berechtigung haben, Dateien in einem Verzeichnis mit solchen Protokollen zu erstellen;
gepufferte Schreibvorgänge funktionieren nicht;
die Datei wird für jeden Protokolleintrag geöffnet und geschlossen. Da die Deskriptoren häufig verwendeter Dateien jedoch in einem Cache gespeichert werden können, kann das Schreiben in die alte Datei während der Zeit fortgesetzt werden, die durch den valid-Parameter der open_log_file_cache-Direktive angegeben ist.
Bei jedem Protokolleintrag wird die Existenz des Wurzelverzeichnisses der Anfrage überprüft, und wenn es nicht existiert, wird das Protokoll nicht erstellt. Es ist daher eine gute Idee, sowohl root als auch upstream_log auf derselben Konfigurationsebene anzugeben:
```
server {
    root         /spool/vhost/data/$host;
    upstream_log /spool/vhost/logs/$host;
    ...
```
Der if-Parameter ermöglicht bedingtes Protokollieren. Eine Anfrage wird nicht protokolliert, wenn die Bedingung auf „0“ oder einen leeren String ausgewertet wird. Im folgenden Beispiel werden die letzten Anfragen mit den Antwortcodes 2xx und 3xx nicht protokolliert:
```
map $upstream_status $upstream_loggable {
    ~(?:^|:\s|,\s)[23][0-9]{2}  0;
    default 1;
}

upstream_log /path/to/upstream.log upstream if=$upstream_loggable;
```

GitHub

Sie finden zusätzliche Konfigurationstipps und Dokumentationen für dieses Modul im GitHub-Repository für nginx-module-upstream-log.