upstream-log: Registra logs de requisições upstream em um formato especificado
Instalação
Você pode instalar este módulo em qualquer distribuição baseada em RHEL, incluindo, mas não se limitando a:
- RedHat Enterprise Linux 7, 8, 9 e 10
- CentOS 7, 8, 9
- AlmaLinux 8, 9
- Rocky Linux 8, 9
- Amazon Linux 2 e 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
Ative o módulo adicionando o seguinte no topo de /etc/nginx/nginx.conf:
load_module modules/ngx_http_upstream_log_module.so;
Este documento descreve o nginx-module-upstream-log v0.1.1 lançado em 06 de janeiro de 2026.
Diferentemente do módulo de log de acesso, ele será registrado no final de cada requisição upstream. Se vários servidores forem contatados durante o processamento da requisição, um log upstream é registrado ao final de cada contato. Se um redirecionamento interno de um grupo de servidores para outro ocorrer, iniciado por “X-Accel-Redirect” ou error_page, um log upstream também será registrado ao final de cada contato.
~~Este módulo também fornece uma série de variáveis para logging upstream. Muitas dessas variáveis começam com $upstream_last_, que é usado para distingui-las das variáveis em ngx_http_upstream. Essas variáveis retornam apenas informações relacionadas ao contato atual com o upstream, ou informações relacionadas à última vez que o upstream foi contatado. Vírgulas e dois-pontos não são usados para registrar informações sobre múltiplos contatos com o upstream.~~
Nota: Este módulo não exporta mais variáveis adicionais. Variáveis upstream extras foram movidas para ngx_http_extra_variables_module.
A utilização deste módulo é muito semelhante ao ngx_http_log_module. Basta usar a diretiva upstream_log para definir o caminho, formato e configuração para uma gravação de log em buffer.
Sinopse
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;
}
}
}
Diretiva
upstream_log
- Sintaxe: upstream_log path [format [buffer=size] [gzip[=level]] [flush=time] [if=condition]]; upstream_log off;
- Padrão: -;
- Contexto: http, server, location, if em location, limit_except
Define o caminho, formato e configuração para uma gravação de log em buffer. Vários logs podem ser especificados no mesmo nível de configuração. O logging para syslog pode ser configurado especificando o prefixo “syslog:” no primeiro parâmetro. O valor especial off cancela todas as diretivas upstream_log no nível atual. Diferentemente da diretiva access_log, esta diretiva não aceita o formato "combined" pré-definido. Você deve primeiro definir o formato do log usando a diretiva log_format e, em seguida, referenciá-lo usando esta diretiva.
Se o parâmetro buffer ou gzip for usado, as gravações para o log serão armazenadas em buffer.
O tamanho do buffer não deve exceder o tamanho de uma gravação atômica em um arquivo de disco. Para FreeBSD, esse tamanho é ilimitado.
Quando o buffering está habilitado, os dados serão gravados no arquivo:
- se a próxima linha de log não couber no buffer;
- se os dados armazenados em buffer forem mais antigos do que o especificado pelo parâmetro flush;
- quando um processo worker estiver reabrindo arquivos de log ou estiver sendo encerrado. Se o parâmetro gzip for usado, os dados armazenados em buffer serão comprimidos antes de serem gravados no arquivo. O nível de compressão pode ser definido entre 1 (mais rápido, menos compressão) e 9 (mais lento, melhor compressão). Por padrão, o tamanho do buffer é igual a 64K bytes, e o nível de compressão é definido como 1. Como os dados são comprimidos em blocos atômicos, o arquivo de log pode ser descomprimido ou lido por “zcat” a qualquer momento.
Exemplo:
upstream_log /path/to/log.gz upstream gzip flush=5m;
Para que a compressão gzip funcione, o nginx deve ser compilado com a biblioteca zlib. O caminho do arquivo pode conter variáveis, mas esses logs têm algumas restrições:
- o usuário cujas credenciais são usadas pelos processos worker deve ter permissões para criar arquivos em um diretório com esses logs;
- gravações em buffer não funcionam;
- o arquivo é aberto e fechado para cada gravação de log. No entanto, como os descritores de arquivos frequentemente usados podem ser armazenados em cache, a gravação no arquivo antigo pode continuar durante o tempo especificado pelo parâmetro valid da diretiva open_log_file_cache.
- durante cada gravação de log, a existência do diretório raiz da requisição é verificada, e se ele não existir, o log não é criado. Portanto, é uma boa ideia especificar tanto root quanto upstream_log no mesmo nível de configuração:
O parâmetro if habilita o logging condicional. Uma requisição não será registrada se a condição avaliar para “0” ou uma string vazia. No exemplo a seguir, as últimas requisições com códigos de resposta 2xx e 3xx não serão registradas:
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
Você pode encontrar dicas adicionais de configuração e documentação para este módulo no repositório do GitHub para nginx-module-upstream-log.