Nginx 日志格式改造：从 Combined 到结构化 JSON（Nginx 系列第 2 期）

Nginx 系列：第 1 期：源码编译安装 · 第 3 期：FancyIndex 文件服务器

1. 为什么需要 JSON 格式日志？

1.1 Nginx 默认日志长什么样

Nginx 默认的 combined 日志格式：

192.168.1.100 - - [16/Jul/2026:14:30:00 +0800] "GET /api/users HTTP/1.1" 200 1234 "https://example.com/" "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"

这条日志包含 7 个字段，用空格和引号分隔。看起来挺整齐——直到你发现 User-Agent 里有个空格：

... "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/120.0"

那个 Chrome/120.0 不在引号里——因为 Nginx log 中 $http_user_agent 没有被引号包裹时，浏览器名称里的空格会破坏字段边界。

或者 Referer 里包含查询参数：

... "https://example.com/search?q=iphone 16 pro max&sort=price"

q=iphone 16 pro max 中的空格又一次破坏了正则解析。

1.2 不改造的前后果

你用 Logstash 写了复杂的 Grok 正则来解析：

grok {
  match => { "message" => '%{IPORHOST:remote_addr} - %{DATA:remote_user} \[%{HTTPDATE:time_local}\] "%{WORD:method} %{DATA:request} HTTP/%{NUMBER:http_version}" %{INT:status} %{INT:body_bytes_sent} "%{DATA:http_referer}" "%{DATA:http_user_agent}"' }
}

Grok 解析本身是 CPU 密集操作——对于每秒几万条日志的 Nginx 实例，解析开销会在 Logstash 或 Fluentd 上形成瓶颈。

改成 JSON 之后：

• Logstash：不需要 Grok，直接 json { source => "message" } 解析，CPU 开销降低 80% 以上（Grok 是 Logstash 中最耗 CPU 的过滤器之一——Elastic 官方文档 明确指出 Grok 是第一个要优化的目标）
• Loki：原生支持 JSON parsing pipeline
• ClickHouse：直接映射到 JSONEachRow 格式，无需预处理

2. 实验环境

如果你还没完成 Nginx 1.30.3 的源码编译，请先阅读第 1 期。本文中的所有配置都基于第 1 期的编译路径和目录结构。

3. JSON 日志格式配置

3.1 基本配置

在你的 nginx.conf 的 http 块中添加：

log_format json escape=json '{'
    '"time_local":"$time_local",'
    '"remote_addr":"$remote_addr",'
    '"remote_user":"$remote_user",'
    '"request":"$request",'
    '"status":$status,'
    '"body_bytes_sent":$body_bytes_sent,'
    '"http_referer":"$http_referer",'
    '"http_user_agent":"$http_user_agent",'
    '"http_x_forwarded_for":"$http_x_forwarded_for",'
    '"request_time":$request_time,'
    '"upstream_response_time":"$upstream_response_time"'
'}';

access_log /var/log/nginx/access.log json;

关键点：

• escape=json：告诉 Nginx 对所有动态变量内容做 JSON 转义——所有 "、\、换行符等会自动转换为合法的 JSON 字符串。没有这个参数，包含特殊字符的 User-Agent 或 Referer 会破坏整个 JSON 结构。（Nginx 1.11.8+ 支持，2016 年引入）
• 数字类型不加引号：$status 和 $body_bytes_sent 是整数，不加双引号——日志平台可以直接将其解析为数字，方便做聚合查询（AVG(request_time)、MAX(body_bytes_sent) 等）
• 字符串类型加引号：$request、$http_user_agent 等可能包含空格和特殊字符，必须用 JSON 字符串包裹

配置后执行平滑重载：

nginx -t && systemctl reload nginx

3.2 输出示例

重载后，发送一条请求：

curl -s -o /dev/null -w "%{http_code}" http://localhost/

查看新日志：

tail -1 /var/log/nginx/access.log | python3 -m json.tool

输出：

{
    "time_local": "16/Jul/2026:14:30:01 +0800",
    "remote_addr": "127.0.0.1",
    "remote_user": "-",
    "request": "GET / HTTP/1.1",
    "status": 200,
    "body_bytes_sent": 612,
    "http_referer": "-",
    "http_user_agent": "curl/8.12.1",
    "http_x_forwarded_for": "-",
    "request_time": 0.000,
    "upstream_response_time": "-"
}

4. 逐字段详细解读

这一节不是贴文档——每个字段的说明是基于实际运维场景的。只有理解字段的含义和使用场景，才知道哪些字段必须保留、哪些可以裁剪。

4.1 $time_local — 本地时间

"time_local": "16/Jul/2026:14:30:01 +0800"

'"time_iso8601":"$time_iso8601",'

4.2 $remote_addr — 客户端 IP

"remote_addr": "203.0.113.42"

如果 Nginx 前面有 CDN 或反向代理（Cloudflare、阿里云 CDN、腾讯云 CDN），$remote_addr 是代理的 IP，不是真实用户的 IP。这时需要配合 $http_x_forwarded_for 使用——见下文 4.8 节。

4.3 $remote_user — HTTP Basic Auth 用户名

"remote_user": "admin"

绝大多数面向公众的网站不使用 HTTP Basic Auth，所以这个字段 99% 的时间里是 -。保留它只是为了与 Nginx Combined 日志格式保持兼容——方便从旧日志格式迁移时字段对齐。

4.4 $request — 原始请求行

"request": "GET /api/users?page=1&limit=20 HTTP/1.1"

这是 Nginx 日志中信息密度最高的字段——一条字段包含 HTTP 方法、请求路径、查询参数和协议版本。

如果你需要单独统计 HTTP 方法分布或 API 路径热度，可以使用更细粒度的变量：

4.5 $status — HTTP 状态码

"status": 200

{job="nginx"} | json | status >= 500

{
  "aggs": {
    "by_status": {
      "terms": { "field": "status" }
    }
  }
}

4.6 $body_bytes_sent — 响应体字节数

"body_bytes_sent": 1234

注意区分：

一般用 $body_bytes_sent 就够了——带宽通常针对 Body，Headers 的字节数相对固定且很小。但如果你需要做精确的出口流量成本核算（CDN 带宽按完整响应计费），建议同时记录 $bytes_sent。

4.7 $http_referer — 来源页面

"http_referer": "https://www.google.com/search?q=nginx+json+log"

4.8 $http_x_forwarded_for — 真实客户端 IP（CDN/代理后）

"http_x_forwarded_for": "203.0.113.42, 10.0.0.1"

这是CDN 和反向代理场景下最容易被忽略但最重要的字段。当你的 Nginx 前面有 Cloudflare、阿里云 CDN 或自建反向代理时：

• $remote_addr = 代理的 IP（如 10.0.0.1 或 CDN 边缘节点 IP）
• $http_x_forwarded_for = 真实用户 IP 的链（用户IP, CDN边缘IP, CDN中间节点IP）

取第一个 IP 通常是真实用户 IP——但前提是你信任代理写入的值。X-Forwarded-For 不是标准 HTTP 头，它可以被伪造。在 nginx.conf 中通过 set_real_ip_from 指定信任的代理 IP 范围（详见 第 1 期：Stream 四层 PROXY Protocol 的第 4 节）。

如果你使用 Cloudflare，替代方案是使用 $http_cf_connecting_ip：

'"cf_connecting_ip":"$http_cf_connecting_ip",'

Cloudflare 保证这个字段不会被客户端伪造（只在 Cloudflare 边缘节点注入）。

4.9 $http_user_agent — 用户代理

"http_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36"

在 escape=json 的保护下，User-Agent 中的所有特殊字符都会被自动转义，不必担心它破坏 JSON 结构。

如果 User-Agent 太长（包含大量插件信息，可达 500+ 字节），可以考虑在日志平台做截断或提取关键信息：

Loki 提取浏览器名称：

{job="nginx"} | json | line_format "浏览器: {{ regexReplaceAll `(\\w+)/.*` .http_user_agent `$1` }}"

4.10 $request_time — 请求处理时间

"request_time": 0.234

这是 SRE 视角下最重要的 Nginx 变量。一个极慢的请求（request_time > 5s）可以说明：

• 后端响应慢（看 upstream_response_time 对比确定）
• 客户端网络慢（request_time 大但 upstream_response_time 小 → Nginx 送完数据但客户端迟迟不收，即 TCP 窗口小）
• 请求体太大（上传大文件的慢速连接）

histogram_quantile(0.99, sum(rate({job="nginx"} | json | unwrap request_time [$__rate_interval])) by (le))

4.11 $upstream_response_time — 后端响应时间

"upstream_response_time": "0.198"

区分 request_time 和 upstream_response_time 是定位问题的关键：

这就是为什么 JSON 日志必须同时包含这两个变量——没有对比，你就不知道慢在哪里。

5. 进阶优化

5.1 按域名分日志

如果你的 Nginx 同时服务多个域名（a.example.com 和 b.example.com），把所有日志混到一个文件里会让后续分析变得困难。按域名分文件：

http {
    log_format json escape=json '...';

    # 对每个 server 块分别指定日志文件
    server {
        server_name api.example.com;
        access_log /var/log/nginx/api_access.log json;
    }

    server {
        server_name admin.example.com;
        access_log /var/log/nginx/admin_access.log json;
    }
}

5.2 条件日志

不对健康检查、静态资源（CSS/JS/图片）记录日志，降低日志量 40%-60%：

map $request_uri $loggable {
    /healthcheck  0;
    ~*\.(css|js|png|jpg|jpeg|gif|ico|woff2|svg)$ 0;
    default 1;
}

access_log /var/log/nginx/access.log json if=$loggable;

5.3 日志缓冲

高并发场景下，每一条请求都 write() 系统调用到磁盘会浪费大量 I/O。启用缓冲：

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

5.4 扩展字段：根据需求定制

你的 JSON 日志不限于上述变量。根据业务需求添加：

log_format json escape=json '{'
    '"time_iso8601":"$time_iso8601",'
    '"remote_addr":"$remote_addr",'
    '"request_method":"$request_method",'
    '"request_uri":"$request_uri",'
    '"server_protocol":"$server_protocol",'
    '"status":$status,'
    '"body_bytes_sent":$body_bytes_sent,'
    '"bytes_sent":$bytes_sent,'
    '"http_referer":"$http_referer",'
    '"http_user_agent":"$http_user_agent",'
    '"request_time":$request_time,'
    '"upstream_response_time":"$upstream_response_time",'
    '"upstream_addr":"$upstream_addr",'
    '"ssl_protocol":"$ssl_protocol",'
    '"ssl_cipher":"$ssl_cipher",'
    '"gzip_ratio":"$gzip_ratio",'
    '"host":"$host",'
    '"connection":"$connection",'
    '"connection_requests":"$connection_requests"'
'}';

新增字段说明：

6. 日志轮转

JSON 日志照样需要 logrotate——格式化不影响日志轮转配置：

cat > /etc/logrotate.d/nginx << 'EOF'
/var/log/nginx/*.log {
    daily
    missingok
    rotate 30
    compress
    delaycompress
    notifempty
    create 640 www-data adm
    sharedscripts
    postrotate
        [ -f /run/nginx.pid ] && kill -USR1 $(cat /run/nginx.pid)
    endscript
}
EOF

kill -USR1 通知 Nginx 重新打开日志文件——与第 1 期 Systemd 章节中的信号速查表一致。

7. 最佳实践总结

7.1 字段选择原则

7.2 日志平台适配速查

7.3 性能影响

你可能担心 JSON 格式比纯文本更重——日志体积会大吗？Logstash/Fluentd 解析 JSON 真的比 Grok 快吗？

以下是来自 Elastic 官方性能调优指南和 Nginx 社区的数据：

结论：log_format 设为 JSON 后，单条日志体积增加 ~75% 但不压缩时，gzip 压缩后差距缩至 ~25%。与此同时，Logstash 处理 Grok 的 CPU 开销是处理 JSON 的 3-5 倍。对于每秒数万条日志的 Nginx 实例，牺牲 25% 的磁盘空间换取 3-5x 的解析性能提升是极其划算的交易。

8. FAQ

Q1: JSON 日志会不会丢失字段信息？比如 Combined 格式里有的东西 JSON 里没有了？

不会。JSON 格式只是把同样的信息重新组织了结构——信息没有丢失，只是不再依赖空格来分隔字段。你完全可以把 Combined 格式中所有字段映射到 JSON 中，见第 4 节的逐字段对比。

Q2: escape=json 对性能有影响吗？

Nginx 的 escape=json 是用 C 实现的短路字符串扫描——对每个日志变量做一次检查：如果全是 ASCII 可打印字符（大部分场景），直接拷贝；只有遇到 "、\、控制字符时才转义。对于典型的 User-Agent 和 Referer（>95% 是 ASCII 可打印字符），这个检查是接近 O(n) 且很快。

Elastic 官方的生产环境基准测试显示：escape=json 带来的 Nginx 额外 CPU 开销 < 1%。

Q3: 可以把 Nginx 日志直接发到 syslog 吗？

可以。替换 access_log 目标：

access_log syslog:server=127.0.0.1:514 json;

然后由 rsyslog/syslog-ng 转发到日志平台。但这引入了 syslog 作为中间人——syslog 协议（RFC 5424）本身有 2 KB 的消息长度限制（虽然可以配大）。对于巨型 User-Agent 和长 URL 的请求，syslog 可能截断日志。建议优先走本地文件 + Filebeat / Promtail 采集，不必绕 syslog 这一步。

Q4: JSON 日志太大了，磁盘扛不住怎么办？

三条路：

1. 条件日志（见 5.2 节）：不记录静态资源和健康检查——日志量减少 40%-60%
2. 采样：在同一个 Nginx http 块中定义两个 log_format——一个完整的（记录所有请求），一个采样的（if=$loggable 加随机采样）
3. 日志存储分层：本地 disk 只保留 7 天（rotate 7），满 7 天通过 gzip 压缩后传对象存储（S3/COS/OSS）做长期冷存储

推荐阅读

• 📄 Nginx 第 1 期：源码编译安装 — FHS 目录规范、configure 参数解析、Systemd 管理
• 📄 Nginx 第 3 期：FancyIndex 文件服务器 — 解决 autoindex 长文件名截断
• 🔧 Linux 服务器初始化完全指南 — 安全加固与网络优化
• 🌐 中国三大运营商精品线路指南 — CN2 GIA / 9929 / CMIN2 一篇搞懂