Nginx 结构化日志是把 access_log 从半结构化的空格文本改成 JSON 对象,并让每个请求带上唯一 request_id,使一次访问在 Nginx、上游应用、WAF 三方日志里能用同一个 ID 串联起来。默认的 combined 格式看似规整,实际解析起来极其脆弱:User-Agent 里只要有一个空格或双引号,按空格切分就会整体错位,后面的状态码、字节数全部对不上号。结构化日志解决的就是这个问题,本文给出可直接套用的 log_format、request_id 贯穿配置与逐项验证命令。
适用场景
以下情况都应当把日志改成结构化输出,而不是继续用正则去啃 combined 格式:
- 日志已经接入 ELK、Loki、Clickhouse 等平台,但 Grok 或正则表达式经常解析失败,字段时有时无;
- 站点前面有 CDN、WAF,后面有 Java/PHP 应用,出现攻击告警时无法证明「WAF 拦的那条」和「应用报错的那条」是同一个请求;
- CC 攻击排查需要按 IP、UA、URI、响应时间做聚合统计,而文本日志只能靠 awk 临时拼;
- 上游响应时间、缓存命中状态需要落到日志里做容量分析,combined 格式根本不记录;
- 日志要长期留存做审计,字段含义必须自解释,不能依赖运维人员记忆列位置。
前置条件
- Nginx 版本不低于 1.11.8(
escape=json参数自该版本引入),$request_id需不低于 1.11.0; - 具备修改
nginx.conf的 sudo 权限,改动前先备份:cp -a /etc/nginx /etc/nginx.bak.$(date +%F); - 磁盘预留空间:JSON 字段比 combined 长约 1.5 至 2 倍,需同步核对 logrotate 策略与分区余量;
- 安装
jq用于验证 JSON 合法性:apt install -y jq或yum install -y jq; - 若上游是 Java/PHP 应用,需确认其能够读取并记录自定义请求头
X-Request-ID。
原理说明
Nginx 的 log_format 本质是一个以变量拼装的模板。escape=json 参数会让 Nginx 在写入前对变量值做 JSON 转义:双引号变成 \",反斜杠变成 \\,控制字符变成 \u0000 形式的 Unicode 转义。这样即使 UA 里塞入引号和换行,整行仍然是一个合法的 JSON 对象,解析器不会因为一个特殊字符就把后续所有记录读乱。这是结构化日志能被稳定消费的前提。
$request_id 是 Nginx 为每个请求生成的一个 16 字节随机十六进制串,在请求进入时确定、全生命周期不变。它本身不会自动传给上游,必须显式用 proxy_set_header 或 fastcgi_param 透传;上游应用把它记进自己的业务日志后,一次「客户端 → WAF → Nginx → 应用 → 数据库」的调用链才具备可关联的主键。相比之下用 IP 加时间戳去猜关联,在 NAT 与高并发场景下基本不可行。
还有两个参数决定了日志能不能用于性能分析:$request_time 是 Nginx 从读到第一个字节到发完响应的总耗时,$upstream_response_time 只统计后端处理时间。两者相减可以判断慢在网关还是慢在应用,这是排查「网站慢」时最直接的一刀。JSON 化之后这两个值可以直接被聚合查询,不需要再写解析脚本。
操作步骤
第一步:确认模块与版本能力
先确认当前版本支持所需参数,避免改完 nginx -t 直接报 unknown parameter:
# 查看版本与编译参数
nginx -v
nginx -V 2>&1 | tr ' ' '\n' | grep -E 'auth_request|http_v2|http_ssl'
# 确认 escape=json 可用(1.11.8 及以上)
nginx -V 2>&1 | grep -o 'nginx/[0-9.]*'
# 备份现有配置
cp -a /etc/nginx /etc/nginx.bak.$(date +%F)
版本低于 1.11.8 时 escape=json 会直接导致 reload 失败,此时要么升级,要么退回到手工转义方案,不建议在旧版本上勉强拼 JSON。确认版本后再往下走。
第二步:定义日志格式
把 log_format 单独放进一个文件,便于后续统一维护。log_format 必须写在 http 上下文,因此该文件要在 nginx.conf 的 http 块内被 include:
# /etc/nginx/conf.d/00-log-format.conf
# 放在 http 上下文内,文件名以 00 开头保证被先加载
log_format json_access escape=json
'{'
'"ts":"$time_iso8601",'
'"remote_addr":"$remote_addr",'
'"xff":"$http_x_forwarded_for",'
'"host":"$host",'
'"request_id":"$request_id",'
'"method":"$request_method",'
'"uri":"$uri",'
'"args":"$args",'
'"status":$status,'
'"body_bytes":$body_bytes_sent,'
'"request_time":$request_time,'
'"upstream_time":"$upstream_response_time",'
'"upstream_addr":"$upstream_addr",'
'"scheme":"$scheme",'
'"ssl_protocol":"$ssl_protocol",'
'"ssl_cipher":"$ssl_cipher",'
'"referer":"$referer",'
'"ua":"$http_user_agent",'
'"cache_status":"$upstream_cache_status"'
'}';
# 健康检查、探针请求不写访问日志,用变量控制
map $uri $loggable {
default 1;
~^/healthz$ 0;
~^/favicon\.ico$ 0;
}
注意两处细节:status、body_bytes、request_time 故意不加引号,让它们在 JSON 里就是数值类型,聚合查询时才不需要 CAST;upstream_time 加了引号,因为后端超时时它会输出成由逗号连接的多段字符串甚至空串,强转数值会出错。这种「该是数字的别写成字符串」的处理,直接决定了后面能不能在 Kibana 里做 avg(request_time)。
第三步:在 server 与 location 中启用
# /etc/nginx/conf.d/site.conf 片段
server {
listen 443 ssl;
server_name www.example.com;
# 引用上面定义的格式,if= 用于过滤探针请求
access_log /var/log/nginx/access_json.log json_access if=$loggable;
error_log /var/log/nginx/error.log warn;
# 把 request_id 透传给后端,key 名保持全站统一
proxy_set_header X-Request-ID $request_id;
location / {
proxy_pass http://127.0.0.1:8080;
}
# PHP-FPM 场景改用 fastcgi_param 透传
location ~ \.php$ {
include fastcgi_params;
fastcgi_param HTTP_X_REQUEST_ID $request_id;
fastcgi_pass unix:/run/php/php-fpm.sock;
}
location /healthz {
access_log off;
return 200 'ok';
}
}
如果站点前面还有一层 Nginx 或 WAF,希望沿用上游已生成的 ID 而不是重新生成,可以用 map 做「有则继承、无则新建」:
# http 上下文中定义:上游带了 X-Request-ID 就沿用,否则用本机的
map $http_x_request_id $req_id {
default $http_x_request_id;
"" $request_id;
}
# 日志与透传统一使用 $req_id
log_format json_access escape=json
'{' '"request_id":"$req_id",' '"status":$status,' '"request_time":$request_time,'
'"uri":"$uri",' '"ua":"$http_user_agent",' '"remote_addr":"$remote_addr"' '}';
proxy_set_header X-Request-ID $req_id;
这里有一个安全细节必须说明:直接继承客户端传来的 X-Request-ID 会让攻击者有能力伪造关联 ID,把恶意请求故意塞进某个正常请求的链路里。稳妥做法是只在请求确实来自可信前置节点时继承——用 geo 或 map 判断 $remote_addr 是否属于 CDN 回源网段,不属于则强制使用本地生成的 $request_id。
第四步:reload 并验证格式合法
配置改完不要直接 reload,先测语法再平滑加载,然后用真实请求验证日志行能被 JSON 解析器接受:
# 1. 语法检查,任何 error 都不要 reload
nginx -t
# 2. 平滑加载
nginx -s reload
# 3. 发一个带特征 UA 的请求,验证特殊字符不破坏 JSON
curl -s -o /dev/null -w '%{http_code}\n' \
-A 'Mozilla/5.0 "quoted" \\ backslash' \
-H 'X-Forwarded-For: 203.0.113.9' \
https://www.example.com/
# 4. 取最后一行,确认是合法 JSON 且能取到字段
tail -n 1 /var/log/nginx/access_json.log | jq .
tail -n 1 /var/log/nginx/access_json.log | jq -r '.status, .request_time, .request_id'
# 5. 全量校验:统计非 JSON 行数,应为 0
grep -vc '^{' /var/log/nginx/access_json.log
第 5 步是关键验收项。grep -vc '^{' 返回非零,说明日志里混入了 error_log 内容、旧格式行或者被截断的半行,必须查清楚再上生产。常见原因是同一个文件被两个不同 log_format 写入,或者 reload 之后旧 worker 仍在用旧格式追加。
第五步:按 request_id 串联全链路
结构化日志真正的价值在关联查询。下面这条命令可以一次性取出某个可疑 IP 在指定时间段内的全部请求,并按状态码与耗时排序,是排查 CC 攻击与慢请求的标准动作:
# 按 IP 聚合:请求数、5xx 数、平均耗时
jq -r 'select(.remote_addr=="203.0.113.9")
| [.status, .request_time, .uri] | @tsv' \
/var/log/nginx/access_json.log \
| awk '{n++; s+=$2; if($1>=500) e++} END {printf "req=%d 5xx=%d avg=%.3fs\n", n, e, s/n}'
# 找出最慢的 20 条请求
jq -r '[.request_time, .request_id, .uri, .upstream_time] | @tsv' \
/var/log/nginx/access_json.log | sort -rn | head -20
# 用 request_id 反查同一请求在上游应用日志里的记录
RID=$(tail -n 1 /var/log/nginx/access_json.log | jq -r .request_id)
grep -F "$RID" /var/log/app/application.log
最后一条命令是整篇文章的目的所在:只要上游应用也记录了 X-Request-ID,一条 grep 就能把「Nginx 看到什么」和「应用做了什么」对齐,省掉过去靠时间戳猜半天的功夫。
第六步:日志轮转与采集对接
JSON 日志体积更大,轮转策略要同步调整,否则容易出现单文件过大导致采集端读取超时:
# /etc/logrotate.d/nginx-json
/var/log/nginx/access_json.log {
daily
rotate 14
size 512M
missingok
notifempty
compress
delaycompress
sharedscripts
postrotate
[ -f /run/nginx.pid ] && kill -USR1 $(cat /run/nginx.pid)
endscript
}
采集侧不需要再写正则:Filebeat 用 json.keys_under_root: true,Promtail 用 pipeline_stages: - json: {expressions: ...},日志进库时字段已经是结构化的,Kibana 里可以直接对 request_time 做百分位聚合。这也是结构化日志相对文本日志最实际的收益——分析侧零解析成本。
配置验证
上线前按下面清单逐项确认,缺一项都可能在事后排查时掉链子:
nginx -t通过,reload 后ps aux | grep nginx的 worker 已全部更换;- 新日志文件确实在被写入,且
grep -vc '^{'结果为 0; - 带引号、反斜杠、中文的 UA 请求写入后
jq .仍能解析,说明转义生效; - 日志中
request_id为 32 位十六进制串,且同一请求在应用日志里能grep到; status字段类型为数值:jq '.status|type'应输出number;upstream_time在后端超时时输出为空串而不报错,说明加了引号的处理正确;- 探针路径
/healthz不出现在访问日志中,map过滤生效; - logrotate 手动执行一次
logrotate -d无报错,USR1 信号能正常触发重开文件。
常见问题
Q1:改成 JSON 后日志里的中文全变成 \u4e2d 这样的转义,正常吗?
正常,这是 escape=json 的既定行为:为保证输出是合法 JSON,非 ASCII 字符会被转成 Unicode 转义序列。日志本身没有损坏,用 jq -r 或采集端解析后都会还原成中文。如果希望日志文件里直接是中文,只能放弃 escape=json 手工拼装,但那会重新引入引号转义不全的风险,不建议这么做。真正需要直读中文时,用 jq -r '.ua' 查看即可。
Q2:request_id 在 Nginx 日志里有,在上游应用日志里却是空的?
按顺序排查三处。第一,确认 proxy_set_header X-Request-ID $request_id 写在了真正生效的 location 里,写在 server 块被后面的 location 覆盖是常见失误。第二,PHP 场景必须用 fastcgi_param HTTP_X_REQUEST_ID,写 proxy_set_header 对 FastCGI 完全无效。第三,确认应用读取的 header 名大小写与框架约定一致,部分框架会把 X-Request-ID 规范成 HTTP_X_REQUEST_ID 环境变量,需要在代码里显式取。改完后重启应用而非只 reload Nginx。
Q3:日志体积翻倍,磁盘撑不住怎么办?
三个手段按优先级用:一是用 map 关掉静态资源与探针的访问日志,图片站与站群场景通常能砍掉 六成以上;二是把 body_bytes、referer、ssl_cipher 这类低价值字段从格式里删掉;三是把访问日志改为写 syslog 由远端集中收集,本机只留 error_log。不建议通过缩短保留天数来省空间,审计留存往往有合规要求,压字段比压天数安全。
总结
结构化日志的落地成本很低,收益却很确定:一个 log_format 加一个 $request_id 透传,就把「日志是一堆文本」变成「日志是可查询的数据集」。实施顺序建议是——先加 escape=json 保证不被特殊字符破坏,再补 request_id 打通链路,最后才去调整采集与轮转。三步分开上、每步验证,比一次性全改更容易定位问题。对于已经上了 WAF 和 CDN 的站点,这套改造还有一个额外好处:当 WAF 判定与业务日志不一致时,request_id 是唯一能拿来说清事实的证据。