Nginx 代理超时怎么记录详细的超时错误日志-Nginx-PHP中文网

nginx可通过配置access_log和error_log联动诊断超时问题：定义含upstream耗时字段的log_format，确保error_log级别≥warn，并用x-request-id串联nginx与后端日志；临时调试可关闭proxy_intercept_errors和proxy_buffering。

nginx 代理超时怎么记录详细的超时错误日志

Nginx 本身不记录“详细堆栈”，但可以通过配置让 error_log 和 access_log 联动输出足够诊断超时问题的关键上下文。重点不是加日志量，而是让每条日志带准确定位信息。

启用带 upstream 细节的 access_log

在 http 块中定义日志格式，包含代理链路各阶段耗时和后端行为：

log_format proxy_debug '$remote_addr - $remote_user [$time_local] '
                        '"$request" $status $body_bytes_sent '
                        'upstream:$upstream_addr '
                        'upstream_status:$upstream_status '
                        'request_time:$request_time '
                        'upstream_connect_time:$upstream_connect_time '
                        'upstream_header_time:$upstream_header_time '
                        'upstream_response_time:$upstream_response_time '
                        'upstream_http_x_request_id:$upstream_http_x_request_id';
access_log /var/log/nginx/access.log proxy_debug;

$upstream_addr 显示实际转发到的后端 IP:Port（如 10.20.30.40:8080）
$upstream_status 是后端返回的真实状态码（比如 500 或 -）
$upstream_response_time 若为 -，说明 Nginx 根本没收到响应（大概率卡在 connect 或 read 阶段）
若该值接近 proxy_read_timeout（如设了 60s，日志里是 59.987），基本可判定是后端慢，不是 Nginx 配置错

确保 error_log 记录足够级别和上下文

默认 error_log 已含关键信息，但需确认两点：

日志级别至少为 warn（避免 notice 级别漏掉超时提示）
不要关闭 error_log 的客户端 IP 和请求 URI 输出（Nginx 默认开启）

典型超时 error_log 行：

2026/10/01 12:15:22 [error] 12345#0: *7890 upstream timed out (110: Connection timed out) while reading response header from upstream, client: 192.168.5.100, server: api.example.com, request: "POST /report/export HTTP/1.1", upstream: "http://10.20.30.40:8080/report/export", host: "api.example.com"

这行已自带：

Nginx Config Linter

对 Nginx 配置文件进行语法检查、验证和安全、性能审计。

下载

具体超时阶段（while reading response header → 对应 proxy_read_timeout）
客户端 IP、请求路径、上游地址
错误编号 (110) 表示系统级连接超时

用 request_id 实现跨层日志对齐

在 Nginx 配置中透传唯一请求 ID：

map $request_id $req_id { "" $request_id; }
proxy_set_header X-Request-ID $req_id;

同时确保后端应用也记录并回传 X-Request-ID（如 Spring Boot 中配置 server.error.include-message=always 并在拦截器中打印）。这样就能把 Nginx 的 error_log、access_log 和后端应用日志用同一个 ID 串起来，快速定位是数据库卡住、线程池满，还是 GC 暂停导致响应延迟。

不推荐但可临时启用的调试手段

仅限排查阶段，勿长期开启：