接口超时的深夜打开 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_user | Basic 认证用户名 | 一般是 - |
$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。