upstream-log: Écrit des journaux de requêtes en amont dans un format spécifié

Installation

Vous pouvez installer ce module dans n'importe quelle distribution basée sur RHEL, y compris, mais sans s'y limiter :

RedHat Enterprise Linux 7, 8, 9 et 10
CentOS 7, 8, 9
AlmaLinux 8, 9
Rocky Linux 8, 9
Amazon Linux 2 et Amazon Linux 2023

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

Activez le module en ajoutant ce qui suit en haut de /etc/nginx/nginx.conf :

load_module modules/ngx_http_upstream_log_module.so;

Ce document décrit nginx-module-upstream-log v0.1.1 publié le 06 janvier 2026.

Contrairement au module de journal d'accès, il sera enregistré à la fin de chaque requête en amont. Si plusieurs serveurs ont été contactés lors du traitement de la requête, un journal en amont est enregistré à la fin de chaque contact. Si une redirection interne d'un groupe de serveurs à un autre se produit, initiée par “X-Accel-Redirect” ou error_page, un journal en amont sera également enregistré à la fin de chaque contact.

~~Ce module fournit également une série de variables pour la journalisation en amont. Beaucoup de ces variables commencent par $upstream_last_, qui est utilisé pour les distinguer des variables dans ngx_http_upstream. Ces variables ne retournent que des informations liées au contact actuel avec l'amont, ou des informations liées à la dernière fois que l'amont a été contacté. Les virgules et les deux-points ne sont pas utilisés pour enregistrer des informations sur plusieurs contacts avec l'amont.~~

Note : Ce module n'exporte plus aucune variable supplémentaire. Les variables en amont supplémentaires ont été déplacées vers ngx_http_extra_variables_module.

L'utilisation de ce module est très similaire à ngx_http_log_module. Il suffit d'utiliser la directive upstream_log pour définir le chemin, le format et la configuration pour un écriture de journal mise en tampon.

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;
            }
        }

    }

Directive

upstream_log

Syntaxe : upstream_log path [format [buffer=size] [gzip[=level]] [flush=time] [if=condition]]; upstream_log off;
Par défaut : -;
Contexte : http, server, location, if in location, limit_except

Définit le chemin, le format et la configuration pour une écriture de journal mise en tampon. Plusieurs journaux peuvent être spécifiés au même niveau de configuration. L'enregistrement dans syslog peut être configuré en spécifiant le préfixe “syslog:” dans le premier paramètre. La valeur spéciale off annule toutes les directives upstream_log au niveau actuel. Contrairement à la directive access_log, cette directive n'accepte pas le format "combined" prédéfini. Vous devez d'abord définir le format du journal à l'aide de la directive log_format, puis le référencer en utilisant cette directive.

Si le paramètre buffer ou gzip est utilisé, les écritures dans le journal seront mises en tampon.

La taille du tampon ne doit pas dépasser la taille d'une écriture atomique dans un fichier disque. Pour FreeBSD, cette taille est illimitée.

Lorsque la mise en tampon est activée, les données seront écrites dans le fichier :

si la prochaine ligne de journal ne tient pas dans le tampon ;
si les données mises en tampon sont plus anciennes que ce qui est spécifié par le paramètre flush ;
lorsque un processus de travail rouvre des fichiers journaux ou se ferme. Si le paramètre gzip est utilisé, les données mises en tampon seront compressées avant d'être écrites dans le fichier. Le niveau de compression peut être réglé entre 1 (le plus rapide, moins de compression) et 9 (le plus lent, meilleure compression). Par défaut, la taille du tampon est égale à 64 Ko, et le niveau de compression est réglé sur 1. Étant donné que les données sont compressées en blocs atomiques, le fichier journal peut être décompressé ou lu par “zcat” à tout moment.

Exemple :

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

Pour que la compression gzip fonctionne, nginx doit être construit avec la bibliothèque zlib. Le chemin du fichier peut contenir des variables, mais de tels journaux ont certaines contraintes :

l'utilisateur dont les informations d'identification sont utilisées par les processus de travail doit avoir les autorisations nécessaires pour créer des fichiers dans un répertoire avec de tels journaux ;
les écritures mises en tampon ne fonctionnent pas ;
le fichier est ouvert et fermé pour chaque écriture de journal. Cependant, étant donné que les descripteurs de fichiers fréquemment utilisés peuvent être stockés dans un cache, l'écriture dans l'ancien fichier peut continuer pendant le temps spécifié par le paramètre valid de la directive open_log_file_cache ;
lors de chaque écriture de journal, l'existence du répertoire racine de la requête est vérifiée, et s'il n'existe pas, le journal n'est pas créé. Il est donc judicieux de spécifier à la fois root et upstream_log au même niveau de configuration :
```
server {
    root         /spool/vhost/data/$host;
    upstream_log /spool/vhost/logs/$host;
    ...
```
Le paramètre if permet une journalisation conditionnelle. Une requête ne sera pas enregistrée si la condition évalue à “0” ou à une chaîne vide. Dans l'exemple suivant, les dernières requêtes avec des codes de réponse 2xx et 3xx ne seront pas enregistrées :
```
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

Vous pouvez trouver des conseils de configuration supplémentaires et de la documentation pour ce module dans le dépôt GitHub pour nginx-module-upstream-log.