upstream-log: 以指定格式记录上游请求日志

安装

您可以在任何基于 RHEL 的发行版中安装此模块，包括但不限于：

RedHat Enterprise Linux 7、8、9 和 10
CentOS 7、8、9
AlmaLinux 8、9
Rocky Linux 8、9
Amazon Linux 2 和 Amazon Linux 2023

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

通过在 /etc/nginx/nginx.conf 顶部添加以下内容来启用模块：

load_module modules/ngx_http_upstream_log_module.so;

本文档描述了 nginx-module-upstream-log v0.1.1，于 2026 年 1 月 6 日发布。

与访问日志模块不同，它将在每个上游请求结束时记录。如果在请求处理期间联系了多个服务器，则在每次联系结束时记录上游日志。如果发生了从一个服务器组到另一个服务器组的内部重定向，由“X-Accel-Redirect”或 error_page 发起，则在每次联系结束时也会记录上游日志。

注意：此模块不再导出任何额外变量。额外的上游变量已移至 ngx_http_extra_variables_module。

此模块的用法与 ngx_http_log_module 非常相似，只需使用 upstream_log 指令设置缓冲日志写入的路径、格式和配置。

概述

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

    }

指令

upstream_log

语法: upstream_log path [format [buffer=size] [gzip[=level]] [flush=time] [if=condition]]; upstream_log off;
默认: -;
上下文: http, server, location, if in location, limit_except

设置缓冲日志写入的路径、格式和配置。可以在同一配置级别上指定多个日志。通过在第一个参数中指定“syslog:”前缀，可以配置日志记录到 syslog。特殊值 off 会取消当前级别上的所有 upstream_log 指令。与 access_log 指令不同，此指令不接受预定义的“combined”格式。您必须先使用 log_format 指令定义日志格式，然后使用此指令引用它。

如果使用了 buffer 或 gzip 参数，则写入日志将被缓冲。

缓冲区大小不得超过对磁盘文件的原子写入大小。对于 FreeBSD，此大小是无限制的。

启用缓冲时，数据将写入文件：

如果下一行日志不适合缓冲区；
如果缓冲的数据比 flush 参数指定的时间要旧；
当工作进程重新打开日志文件或关闭时。如果使用了 gzip 参数，则缓冲的数据将在写入文件之前进行压缩。压缩级别可以设置在 1（最快，压缩较少）和 9（最慢，压缩最好）之间。默认情况下，缓冲区大小为 64K 字节，压缩级别设置为 1。由于数据是以原子块进行压缩的，因此日志文件可以随时通过“zcat”进行解压或读取。

示例：

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

要使 gzip 压缩工作，nginx 必须使用 zlib 库构建。文件路径可以包含变量，但此类日志有一些限制：

使用工作进程凭据的用户应具有在该目录中创建文件的权限；
缓冲写入无效；
每次日志写入时都会打开和关闭文件。然而，由于频繁使用的文件的描述符可以存储在缓存中，因此在 open_log_file_cache 指令的 valid 参数指定的时间内，可以继续写入旧文件；
在每次日志写入时，会检查请求的根目录是否存在，如果不存在，则不会创建日志。因此，最好在同一配置级别上同时指定 root 和 upstream_log：
```
server {
    root         /spool/vhost/data/$host;
    upstream_log /spool/vhost/logs/$host;
    ...
```
if 参数启用条件日志记录。如果条件评估为“0”或空字符串，则请求不会被记录。在以下示例中，响应代码为 2xx 和 3xx 的最后请求将不会被记录：
```
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

您可以在 nginx-module-upstream-log 的 GitHub 仓库中找到此模块的其他配置提示和文档。