Nginx 日志格式自定义:access_log 改成排障时真正用得上的字段

Nginx 日志格式自定义:access_log 改成排障时真正用得上的字段

Nginxaccess_logerror_log日志排障
📶 入门 🧩 Nginx · Ubuntu

接口超时的深夜打开 access.log,看到的是一行 combined 格式:IP、时间、请求行、状态码、User-Agent。谁访问了、状态码多少,一眼能看出来;请求慢在哪一环、请求体多大、上游响应了多久,一个字段都没有。等出了事故再回头改日志格式,改完之后产生的日志才有新字段——出事那一刻恰恰什么都没记到。**日志格式要在出事之前埋好排障字段,这是零成本、收益最大的一件运维准备。**本文按 Ubuntu 24.04(nginx 1.24)讲清改法,文中用到的指令自 nginx 1.7 起陆续加入,任何近期版本都支持。

默认格式长什么样,缺了什么

nginx 预定义了一个 combined 格式,不指定格式名时 access_log 默认用它:

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

逐字段拆开看它的信息边界:

字段记录内容排障时能干什么
$remote_addr客户端 IP定位来源、配合封禁
$remote_userBasic 认证用户名一般是 -
$time_local请求时间(本地时区)和其他系统日志对时间线
$request完整请求行看路径和参数
$status响应状态码判断成败
$body_bytes_sent发出的响应体字节数看响应大小
$http_referer / $http_user_agent来源页与 UA识别流量类型

耗时类字段全缺。一个请求打了 30 秒才返回 200,combined 里只有一行看起来毫无异常的记录。补充字段的关键就两个:$request_time 和 $upstream_response_time。

自定义格式只需要改两个指令

log_format 定义格式,access_log 引用它。前者只能写在 http 块,后者可以在 http、server、location 各层覆盖。推荐 JSON 格式,后续交给 GoAccess、Loki 或任何日志系统都省去正则解析:

http {
    log_format main escape=json
        '{'
        '"time":"$time_iso8601",'
        '"remote_addr":"$remote_addr",'
        '"request":"$request",'
        '"status":$status,'
        '"bytes_sent":$bytes_sent,'
        '"request_time":$request_time,'
        '"upstream_time":"$upstream_response_time",'
        '"referer":"$http_referer",'
        '"ua":"$http_user_agent"'
        '}';
    access_log /var/log/nginx/access.log main;
}

三个细节:escape=json 会把值里的引号、换行等字符转义,UA 和 referer 里的脏字符不会破坏 JSON 结构;$status 和数字类字段不加引号,写入时保持数值类型;变量取不到值时,默认转义下记作 -,这是正常现象。

改完先验证语法再重载:

nginx -t && systemctl reload nginx
curl -s -o /dev/null localhost/ && tail -n 1 /var/log/nginx/access.log

看到一行合法 JSON、带 request_time 字段,格式就生效了。

排障字段怎么挑

不是所有变量都值得记,挑字段看排障场景:

变量记录内容什么时候有用
$request_time收到客户端首字节到发出响应末字节的总耗时判断慢请求,排障头号字段
$upstream_response_time反代场景下上游的响应耗时区分慢在应用还是慢在链路
$request_length请求总长(请求行+头+体)定位超大请求、恶意上传
$bytes_sent发出的总字节数比响应体多出协议开销,流量统计用它
$msec毫秒精度时间戳需要精确排序时替代 $time_local
$connection / $connection_requests连接序号与该连接上的请求数识别 keep-alive 复用异常

$request_time 和 $upstream_response_time 的差值最值得盯着:差值大,说明时间耗在 nginx 与客户端之间的传输上——弱网客户端上传大请求体、响应体太大发出缓慢,都算在这里。两个值都大且接近,慢在上游应用;只有 $request_time 大,先看 $request_length 是不是很大。

用 if 参数关掉无价值的请求记录

健康检查每 10 秒打一次、前端轮询每秒一次,2xx 记录很快淹没有用的部分。条件日志用 map 配合 access_log 的 if 参数实现:

# 2xx/3xx 不记,只留失败和慢请求
map $status $loggable {
    ~^[23]  0;
    default 1;
}
access_log /var/log/nginx/access.log main if=$loggable;

map 写在 http 块,条件结果为 0 或空字符串的请求不记。同样的思路可以基于 $uri 过滤健康检查路径,或者基于 $http_user_agent 过滤探活流量。注意 if 只是跳过记录,状态码统计、监控探针如果依赖 access.log 聚合,先把消费端改好再关。

高流量站给日志加 buffer 和 gzip

每条日志都同步写盘,高并发下是隐性开销。加缓冲后 nginx 攒一批再写:

access_log /var/log/nginx/access.log main buffer=64k flush=5s;

缓冲满或超过 flush 时间(这里是 5 秒)才写盘,重载和 worker 退出时强制写出。日常 tail 看日志要接受最多 5 秒延迟,排障时可以临时去掉 buffer 再复现。

磁盘紧张还可以让 nginx 直接写压缩日志:

access_log /var/log/nginx/access.gz main gzip flush=5m;

压缩按原子块写入,随时 zcat 能读,不用等轮转。

一个常见的坑:路径里带变量(如按域名分文件 access_log /var/log/nginx/$host/access.log)时,缓冲失效,每个请求都要开关一次文件,高流量下性能很差。确实需要按变量分文件,就配 open_log_file_cache 把常用文件句柄缓存在内存里,减少反复开关的开销:

open_log_file_cache max=1000 inactive=20s valid=1m min_uses=2;

error_log 级别怎么选

访问日志之外,error_log 记录 nginx 自身的运行错误,语法 error_log path [level];,可在 main、http、server、location 分层设置,每层只有一条生效:

级别记录内容
emerg / alert / crit无法启动、资源耗尽等致命问题
error配置或运行错误的默认级别
warn可疑但不致命,排障时临时开
notice / info流程记录,量大
debug全量调试信息,日志量极大

生产环境保持默认 error 即可,升级或复现问题时临时切 warn、看完切回来。debug 级别只在复现特定 bug 时短暂开启——Ubuntu 的 nginx 包编译时已带 debug 支持,但磁盘和 I/O 都扛不住长期跑。nginx 自己起不来时优先看这里:tail -n 50 /var/log/nginx/error.log,配置写错、端口占用、证书路径不对,报错都在。

轮转配合:切文件要用信号而不是重启

logrotate 每天切走 access.log,但 nginx 持有旧文件的句柄,文件被改名后它还在往原 inode 里写,新日志凭空消失。正确姿势是轮转后给 nginx 发 USR1 信号,让它重新打开日志文件:

nginx -s reopen    # 等价于 kill -USR1 <master_pid>

Ubuntu 软件源自带的 /etc/logrotate.d/nginx 已经内置这个动作,自己写轮转规则的参考 logrotate 配置详解,信号语义见 Linux 信号详解。另一个容易忽略的点:请求记录在处理结束的 location 上下文里,内部跳转后可能和最初匹配的 location 不同, location 层单独设 access_log 时要注意,匹配规则详见 Nginx location 匹配规则详解。

常见问题

改了 log_format,日志还是旧格式? log_format 只能写在 http 块,写在 server 里报错;改完先 nginx -t 再 reload。还要检查 server 或 location 块里有没有自己的 access_log 指令覆盖了 http 层——下层存在就整体生效,不会拼格式。

日志里大量 - 是坏了? 变量没有值时记 -,比如没有 Referer 头时 $http_referer 就是 -。这是标准行为,JSON 格式下它会变成 "-",同样是合法的 JSON。

access_log off 能省磁盘吗? 能关掉当前层的全部访问日志,但连状态码统计都没了。更稳的做法是 if 条件日志只记有价值的请求,或者用 buffer+gzip 降低写入成本。

$request_time 很大但 $upstream_response_time 很小? 时间耗在 nginx 和客户端之间。先看 $request_length:请求体很大的上传在弱网下会把 $request_time 拉得非常长,上游其实秒回。客户端下载大文件同理。

access.log 已经几百 GB 怎么救? 先加 logrotate 控制增量,历史归档 gzip 后按保留期删除;磁盘已经写满的机器,排查路径见 磁盘空间排查实战。

最小可行清单

只做三件事的话:把访问日志换成带 $request_time 和 $upstream_response_time 的 JSON 格式;给高流量站点的 access_log 加 buffer 和 flush;确认 logrotate 触发后 nginx 收到 USR1 信号、新日志正常落进新文件。这三件事做完,下一次深夜排障,你在日志里看到的将是「慢在哪一环、多大、从哪来」,而不是一行只能确认「失败了」的 combined。