upstream-log: Escribe registros de solicitudes upstream en un formato especificado
Instalación
Puedes instalar este módulo en cualquier distribución basada en RHEL, incluyendo, pero no limitado a:
- RedHat Enterprise Linux 7, 8, 9 y 10
- CentOS 7, 8, 9
- AlmaLinux 8, 9
- Rocky Linux 8, 9
- Amazon Linux 2 y Amazon Linux 2023
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
Habilita el módulo añadiendo lo siguiente en la parte superior de /etc/nginx/nginx.conf:
load_module modules/ngx_http_upstream_log_module.so;
Este documento describe nginx-module-upstream-log v0.1.1 lanzado el 06 de enero de 2026.
A diferencia del módulo de registro de acceso, se registrará al final de cada solicitud upstream. Si se contactaron varios servidores durante el procesamiento de la solicitud, se registra un log upstream al final de cada contacto. Si ocurre una redirección interna de un grupo de servidores a otro, iniciada por “X-Accel-Redirect” o error_page, también se registrará un log upstream al final de cada contacto.
~~Este módulo también proporciona una serie de variables para el registro upstream. Muchas de estas variables comienzan con $upstream_last_, que se utiliza para distinguirlas de las variables en ngx_http_upstream. Estas variables solo devuelven información relacionada con el contacto actual con el upstream, o información relacionada con la última vez que se contactó al upstream. No se utilizan comas ni dos puntos para registrar información sobre múltiples contactos con el upstream.~~
Nota: Este módulo ya no exporta ninguna variable adicional. Las variables upstream adicionales se han trasladado a ngx_http_extra_variables_module.
El uso de este módulo es muy similar al de ngx_http_log_module. Solo usa la directiva upstream_log para establecer la ruta, el formato y la configuración para una escritura de log en búfer.
Sinopsis
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;
}
}
}
Directiva
upstream_log
- Sintaxis: upstream_log path [format [buffer=size] [gzip[=level]] [flush=time] [if=condition]]; upstream_log off;
- Predeterminado: -;
- Contexto: http, server, location, if en location, limit_except
Establece la ruta, el formato y la configuración para una escritura de log en búfer. Se pueden especificar varios logs en el mismo nivel de configuración. El registro en syslog se puede configurar especificando el prefijo “syslog:” en el primer parámetro. El valor especial off cancela todas las directivas upstream_log en el nivel actual. A diferencia de la directiva access_log, esta directiva no acepta el formato predefinido "combined". Debes definir primero el formato del log usando la directiva log_format y luego hacer referencia a él usando esta directiva.
Si se utiliza el parámetro buffer o gzip, las escrituras en el log serán en búfer.
El tamaño del búfer no debe exceder el tamaño de una escritura atómica en un archivo de disco. Para FreeBSD, este tamaño es ilimitado.
Cuando el búfer está habilitado, los datos se escribirán en el archivo:
- si la siguiente línea de log no cabe en el búfer;
- si los datos en búfer son más antiguos de lo especificado por el parámetro flush;
- cuando un proceso worker está reabriendo archivos de log o está cerrándose. Si se utiliza el parámetro gzip, los datos en búfer se comprimirán antes de escribir en el archivo. El nivel de compresión puede establecerse entre 1 (más rápido, menos compresión) y 9 (más lento, mejor compresión). Por defecto, el tamaño del búfer es igual a 64K bytes, y el nivel de compresión se establece en 1. Dado que los datos se comprimen en bloques atómicos, el archivo de log se puede descomprimir o leer con “zcat” en cualquier momento.
Ejemplo:
upstream_log /path/to/log.gz upstream gzip flush=5m;
Para que la compresión gzip funcione, nginx debe ser compilado con la biblioteca zlib. La ruta del archivo puede contener variables, pero tales logs tienen algunas restricciones:
- el usuario cuyas credenciales son utilizadas por los procesos worker debe tener permisos para crear archivos en un directorio con tales logs;
- las escrituras en búfer no funcionan;
- el archivo se abre y se cierra para cada escritura de log. Sin embargo, dado que los descriptores de archivos utilizados con frecuencia pueden almacenarse en una caché, la escritura en el archivo antiguo puede continuar durante el tiempo especificado por el parámetro valid de la directiva open_log_file_cache.
- durante cada escritura de log se verifica la existencia del directorio raíz de la solicitud, y si no existe, el log no se crea. Por lo tanto, es una buena idea especificar tanto root como upstream_log en el mismo nivel de configuración:
El parámetro if habilita el registro condicional. Una solicitud no se registrará si la condición evalúa a “0” o a una cadena vacía. En el siguiente ejemplo, las últimas solicitudes con códigos de respuesta 2xx y 3xx no se registrarán:
server { root /spool/vhost/data/$host; upstream_log /spool/vhost/logs/$host; ...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
Puedes encontrar consejos de configuración adicionales y documentación para este módulo en el repositorio de GitHub para nginx-module-upstream-log.