如何利用 log_subrequest 开启日志追踪负载均衡内部的 SSI 与转发请求细节-Nginx-PHP中文网

log_subrequest默认关闭，需在http或server块中显式配置on才能记录SSI、auth_request等子请求日志，配合$request_id可精准追踪完整请求链。

如何利用 log_subrequest 开启日志追踪负载均衡内部的 ssi 与转发请求细节

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 # 查看版本
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