nginx 通过 $request_time 和 $upstream_response_time 精确记录请求总耗时与上游响应耗时，配合 log_format 定义日志格式并写入 access_log，可定位性能瓶颈；需注意精度限制、变量开销及调试验证方法。

在 Nginx 中，通过 log_format 结合内置变量可以精确记录每个请求的处理时间，最常用的是 $request_time 和 $upstream_response_time。

使用 $request_time 记录总处理时间

$request_time 表示从接收到客户端第一个字节开始，到向客户端发送完最后一个字节为止的总耗时（单位：秒，精度为毫秒）。它包含 Nginx 自身处理、上游响应、网络传输等全部环节。

• 在 http 块中定义日志格式，例如：

log_format main '$remote_addr - $remote_user [$time_local] "$request" ' '$status $body_bytes_sent "$http_referer" ' '"$http_user_agent" "$http_x_forwarded_for" ' '$request_time $upstream_response_time';

• 然后在 access_log 中引用该格式：

access_log /var/log/nginx/access.log main;

日志行末尾会追加两个浮点数，如 0.023 0.021，分别表示整个请求耗时和上游响应耗时。

区分不同阶段的耗时变量

除了 $request_time，还可搭配其他时间变量定位瓶颈：

Nginx Config Linter

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

下载

• $upstream_response_time：记录与 upstream（如后端 PHP、Go 服务）交互的耗时，多个 upstream 会以逗号分隔（如 0.012, 0.008）
• $msec：记录日志写入时刻的 Unix 时间戳（秒+毫秒），可用于对齐上下游日志
• $connection_requests：当前连接已处理的请求数，辅助判断长连接影响

若后端是反向代理，$upstream_response_time 通常小于 $request_time；差值可能反映 Nginx 读取/发送响应体、gzip 压缩、日志写入等开销。

注意精度与日志性能平衡

$request_time 和 $upstream_response_time 默认保留 3 位小数（毫秒级），但实际精度受系统时钟和事件循环调度影响，不建议用于微秒级分析。

• 避免在 log_format 中混用高开销变量（如 $request_body 或正则匹配变量），否则会影响吞吐量
• 生产环境建议只记录必要字段，高频接口可单独配置精简日志格式
• 若需更高精度，应在应用层（如后端服务）打点，并通过 $request_id 关联日志

验证与调试技巧

修改配置后务必测试变量是否生效：

• 执行 nginx -t 检查语法
• 重载配置：nginx -s reload
• 发起一次请求后查看日志，确认新增字段有数值输出（非破折号 -）
• 若 $upstream_response_time 显示 -，说明未经过 upstream（如静态文件直出或 4xx/5xx 错误未转发）

可通过添加 add_header X-Request-Time $request_time; 在响应头中临时验证，便于前端或 curl 观察。