log_subrequest默认关闭，需在http或server块中显式配置on才能记录SSI、auth_request等子请求日志，配合$request_id可精准追踪完整请求链。
log_subrequest 是 Nginx 的一个关键配置指令，用于控制是否将子请求（subrequest）的访问日志写入 access_log。默认情况下，Nginx 不记录子请求（如 SSI include、proxy_pass 内部转发、auth_request 触发的校验请求等），这会导致负载均衡链路中部分关键跳转“消失”在日志里，难以追踪真实请求路径。开启它，是排查 SSI 渲染异常、后端服务调用缺失、多层 proxy 嵌套转发失败等问题的必要手段。
确认 Nginx 版本与模块支持
该指令自 Nginx 1.19.1 起正式稳定支持（此前为实验性）。需确保运行版本 ≥ 1.19.1，且未禁用 ngx_http_log_module（通常默认启用）。可通过以下命令验证：
nginx -V 2>&1 | grep -o 'with-http-log-module' # 确认模块存在
在日志格式与 location 中启用 log_subrequest
仅开启指令本身还不够，需配合日志格式与作用域配置才能生效：
- 在
http或server块中定义含$request_id或$upstream_http_x_request_id的自定义日志格式，便于串联主请求与子请求 - 在涉及 SSI 或 proxy_pass 的
location块中显式设置：log_subrequest on; - 确保该 location 使用了
access_log指令（子请求日志复用同一 access_log 配置）
log_format trace '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" "$http_user_agent" '
'req_id:"$request_id" sub:"$request_completion";
location /api/ {
proxy_pass http://backend;
log_subrequest on;
access_log /var/log/nginx/api.log trace;
}
结合 SSI 与 proxy_chain 追踪完整链路
SSI（Server Side Include）常触发内部子请求加载片段，而 proxy_pass 在负载均衡场景下可能嵌套多次（如 A → B → C）。开启 log_subrequest 后，每条子请求会单独打一行日志，并在 $request_completion 变量中标识 OK（成功）或 FAILED（失败），配合 $request_id 即可还原调用树：
- 主请求日志中
req_id:"abc123"，sub:"OK" - 其 SSI include 的子请求日志同样含
req_id:"abc123"，但request字段显示GET /fragment.html HTTP/1.0，sub:"OK" - 若某次 proxy_pass 转发超时，对应子请求日志中
status:504，sub:"FAILED"，且仍共享同一req_id
注意性能与日志膨胀风险
子请求频次远高于主请求（尤其高并发 SSI 页面），开启后日志量可能激增 3–10 倍。建议：
- 仅在调试阶段或特定 location（如 /debug/、/admin/）启用，生产环境慎用
- 搭配
log_not_found off;避免 404 子请求刷屏 - 使用
if条件限制（如仅记录含特定 header 的请求），但需注意 if 在 location 中的限制 - 定期轮转并监控磁盘用量，避免填满日志分区
