Web 服务器与网关 / 系统课时

怎样自定义 Nginx 日志格式

怎样自定义 Nginx 日志格式

默认访问日志缺少上游地址和耗时,代理请求变慢时很难分辨尝试了哪个后端。本篇定义逐行 JSON 格式,增加请求标识与上游时间,用直返和代理两类请求验证字段,避免缺失值或未转义文字破坏解析。

学习目标

  • 在 http 上下文定义并在 server 使用日志格式。
  • 记录请求时间、上游地址、状态及响应时间。
  • 正确处理 JSON 转义、缺失值和多次上游尝试。

让每行成为独立 JSON 对象

实验需要 Nginx 1.28、curl、Python 3,空闲本机 8080、9001,以及可由 Master 打开日志的 /tmp/nginx-json-lab 目录。目录仅放本次实验文件;先创建它,再加入以下 http 上下文片段示例:

nginx
log_format timing_json escape=json
    '{"time":"$time_iso8601","id":"$request_id",'
    '"method":"$request_method","uri":"$uri","status":"$status",'
    '"rt":"$request_time","ua":"$upstream_addr","us":"$upstream_status",'
    '"uct":"$upstream_connect_time","uht":"$upstream_header_time",'
    '"urt":"$upstream_response_time"}';
server {
    listen 127.0.0.1:8080;
    server_name json.test;
    access_log /tmp/nginx-json-lab/access.ndjson timing_json;
    add_header X-Request-ID $request_id always;
    location = /health { return 204; }
    location /api/ {
        proxy_set_header X-Request-ID $request_id;
        proxy_pass http://127.0.0.1:9001;
    }
    location / { return 404; }
}
server {
    listen 127.0.0.1:9001;
    server_name backend.test;
    location / { return 200 "backend-ok\n"; }
}

log_format 只能放在 http,不能移进 server。escape=json 负责转义变量里的引号、反斜线和控制字符,仍需自己提供 JSON 键名、引号及标点。本例把时间与状态也记成字符串,使无上游时的空字符串仍为合法 JSON;解析时先处理缺失值,再转换为数值。

比较代理与直接返回的字段

检查并重载后执行:

bash
curl --noproxy '*' --resolve json.test:8080:127.0.0.1 -sS http://json.test:8080/api/health
curl --noproxy '*' --resolve json.test:8080:127.0.0.1 -sS -o /dev/null -w 'status=%{http_code}\n' http://json.test:8080/health

预期输出:

text
backend-ok
status=204

等日志写入后,在 Linux 终端执行以下完整解析命令:

bash
# 每行单独解析,不把整个 NDJSON 文件当作一个 JSON 文档。
python3 - <<'PY'
import json
from pathlib import Path
for line in Path('/tmp/nginx-json-lab/access.ndjson').read_text().splitlines():
    row = json.loads(line)
    print(row['uri'], row['status'], row['ua'], row['urt'])
PY

预期结果:/api/health 的状态为 200、ua 为 127.0.0.1:9001、urt 为非负秒数;本例 /health 为 204,上游地址及时间是空字符串,打印后显示为空白。其他格式也可能用短横线表示缺失,不要假定所有格式相同。时间与 id 动态变化,不要求固定数值。

用统一请求标识连接不同日志

本例产生新的 $request_id,返回给客户端,并传给上游。生产应用还需实际记录收到的 X-Request-ID,才能完成跨层关联;设置头本身不会自动改写应用日志。

客户端自报的标识可能重复或伪造,入口应明确生成或验证策略。关联标识用于观察请求,不应作为认证凭据。uri 使用不带查询参数的当前路径,以减少记录敏感参数;内部重写时它可能已变化。

上游字段可能包含多次尝试

字段 使用方式
rt 请求整体耗时,秒为单位,可含客户端收发影响
ua、us 实际上游地址和对应尝试状态
uct、uht、urt 连接、首部及整个上游响应相关时间,不能直接相加

多次上游尝试时,相关字段可能是逗号分隔的值,内部跳转还可能产生分组分隔;应保留位置关系,不能把整串强行当单个浮点数。字段定义见 Nginx 上游变量。

上线前先解析少量真实记录,检查引号转义、无上游请求与错误状态,再接入日志采集。不要为了记录更多信息而默认增加 Cookie、认证头或完整参数。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

怎样自定义 Nginx 日志格式

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通