nginx 精准捕获上游隐蔽报错需 error_log 与 access_log 协同：通过 proxy_intercept_errors、自定义 log_format 记录 $upstream_status 等变量、map + lua 提取响应体错误码、透传 x-request-id，并规避 if 日志、$status 误判等陷阱。
要让 Nginx 在统一日志监控中精准捕获并还原上游接口的隐蔽报错，核心不是“记录更多”，而是让 error_log 和 access_log 协同输出可归因、可关联、可追溯的上下文信息——尤其针对那些不返回标准 HTTP 错误码、或错误被静默吞掉、或仅在响应头/体中埋线索的上游异常。
让 error_log 主动暴露上游真实错误线索
Nginx 默认的 error_log 对上游问题往往只记“upstream timed out”或“connection refused”，丢失后端语义。需主动增强：
- 启用 proxy_intercept_errors on，配合 error_page 500 502 503 504 = /_err5xx，把上游错误拦截到内部 location，再通过 add_header X-Backend-Error $upstream_http_x_backend_error 将后端透出的原始错误头写入响应，同时该 header 会自动落进 $upstream_http_x_backend_error 变量，可在 log_format 中引用
- 在 log_format 中显式记录关键上游变量：$upstream_addr（实际连接地址）、$upstream_status（上游返回状态码）、$upstream_response_time（上游耗时）、$upstream_http_x_request_id（若后端透传了链路 ID）
- 对非 2xx/3xx 响应，在 error_log 中强制打点：用 log_subrequest on + error_log ... notice 级别，配合 map 指令标记异常响应，例如：
map $upstream_status $is_upstream_err { ~^[45] 1; default 0; }
log_format main '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" $upstream_addr $upstream_status $upstream_response_time $upstream_http_x_backend_error';
access_log /var/log/nginx/access.log main if=$is_upstream_err;
用 access_log 还原“看似成功”的隐蔽失败
很多上游错误不触发 5xx，而是返回 200 + 错误体（如 JSON {"code":5001,"msg":"DB timeout"}），或 4xx 但被前端忽略。这时需靠 access_log 主动识别：
- 用 map 提取响应体中的业务错误码（需搭配 ngx_http_lua_module 或 OpenResty）：
set $biz_code "";
header_filter_by_lua_block {
local h = ngx.header["Content-Type"]
if h and string.find(h, "application/json") then
local body = ngx.ctx.response_body
if body and type(body) == "string" then
local c = string.match(body, '"code"%s*:%s*(%d+)')
if c and tonumber(c) > 4000 then ngx.var.biz_code = c end
end
end
}
再将 $biz_code 写入 log_format - 若无法用 Lua，退而求其次：用 proxy_hide_header 屏蔽上游的 X-Status 或 X-Error-Code 类自定义头，并用 add_header 统一注入标准化错误标识，确保该 header 必然出现在 access_log 的 $sent_http_x_error_code 字段中
打通日志与可观测性的关键字段对齐
统一监控平台（如 ELK、Grafana Loki）依赖结构化字段做聚合分析。Nginx 日志必须输出与后端服务一致的 trace 上下文：
- 强制透传并记录 $http_x_request_id（客户端发起）和 $upstream_http_x_request_id（上游回传），两者对比可判断是否发生链路断裂或 ID 覆盖
- 在 upstream 块中配置 keepalive_requests 1000 和 keepalive_timeout 60s，避免因连接复用导致 request_id 混淆；同时开启 proxy_buffering off（仅调试期）可确保响应体完整被捕获用于内容解析
- 为每个 upstream server 添加 zone 参数（如 zone=api_backend 64k），配合 stub_status 或 nginx-module-vts 模块，将实时健康状态、失败计数等指标导出为 Prometheus metrics，与日志时间戳对齐做根因分析
规避常见日志失真陷阱
以下配置看似合理，实则会让日志失去诊断价值：
- 禁用 log_not_found off 在 healthz 接口上——否则 404 健康检查失败会被计入 error_log，淹没真实故障
- 避免在多个 location 中重复定义相同 log_format，尤其当使用 if 判断写日志时，Nginx 的 if 是伪指令，易导致变量未初始化而输出空值
- 不要依赖 $status 判断上游是否出错：它只是 Nginx 返回给客户端的状态码，可能已被 error_page 或 return 覆盖，真正反映上游的是 $upstream_status
