Nginx 结构化日志配置实战:JSON 与请求 ID

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 是唯一能拿来说清事实的证据。