开启 log_subrequest 可让 Nginx 在 access log 中记录子请求和内部重定向，需 Nginx ≥1.19.1（推荐 ≥1.21.0），并配合 log_format 中 $request_completion 等字段及 $request_id 实现父子请求链路追踪。
开启 log_subrequest 可以让 Nginx 在 access log 中记录子请求（subrequest）和内部重定向（internal redirect）的执行过程，这对调试缓存逻辑、代理转发链路、以及理解 auth_request、echo_exec、try_files 等触发的内部请求非常有用。
确认 Nginx 版本与模块支持
该指令自 Nginx 1.19.1 起正式引入（此前为实验性），需确保使用较新稳定版（推荐 ≥1.21.0）。它不依赖额外模块，但需编译时启用 --with-http_subrequest_module（默认已开启）。
- 运行
nginx -V 2>&1 | grep -o '1\.[1-9][0-9]*\.[0-9]*'查看版本 - 执行
nginx -V 2>&1 | grep -i subrequest确认模块存在 - 若输出为空或版本过低，需升级或重新编译
在日志格式中启用 subrequest 标识
log_subrequest on 本身不产生日志，它只是“允许” access_log 指令中的 $request_id、$request_length 等变量在子请求上下文中正确展开。真正起作用的是日志格式中是否包含能区分主/子请求的字段。
- 推荐在
log_format中加入$request_completion（值为OK或空）或$request_length（子请求通常更短） - 更直接的方式是使用
$connection_requests或自定义变量配合map判断是否为子请求上下文 - 典型做法：添加一个标记字段，如
'sub:$request_completion'，主请求该值为空，子请求为OK
配置示例：追踪缓存未命中后的内部代理子请求
例如你用 try_files + proxy_pass 实现缓存兜底，希望看清哪些请求走了缓存、哪些触发了后端子请求：
log_format trace '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent" '
'req="$request_id" sub="$request_completion"';
<p>log_subrequest on;</p><p>server {
location /api/ {</p><h1>尝试读取缓存，失败则发起子请求到 upstream</h1><pre class="brush:php;toolbar:false;"> try_files /cache/$uri @proxy_backend;
location @proxy_backend {
proxy_pass http://backend;
proxy_set_header X-Original-URI $request_uri;
}
}
}
此时 access.log 中，主请求（如 GET /api/data）会记录一次，而 try_files 内部发起的 GET /cache/xxx 子请求也会被单独记录，且 sub 字段为 OK，便于过滤分析。
结合 $request_id 串联完整请求链路
单靠 log_subrequest 不足以关联父子请求，必须配合唯一请求 ID。建议在 server 块顶层设置：
map $request_id $parent_id {
"" $connection; # 初始请求无 request_id 时用连接号临时标识
}
<h1>或更稳妥地用第三方模块 ngx_http_request_id（推荐）</h1><h1>然后在子请求中透传：proxy_set_header X-Request-ID $request_id;</h1>
再配合日志格式中的 $request_id 和 $parent_id，就能在 ELK 或 grep 中按 ID 分组，还原出「一次客户端请求 → 多次内部子请求」的完整调用树。
不复杂但容易忽略：log_subrequest 是开关，不是日志项；真正要看到子请求细节，得靠日志格式设计 + 请求 ID 传递 + 合理的 location 分层。
