$upstream_header_time 测量 nginx 发起请求至接收后端响应头结束的时间，精确反映后端首包生成耗时（即 ttfb 的后端部分），涵盖请求路由、业务逻辑、db 访问、响应头写出等全过程。
$upstream_header_time 是 Nginx 内置的时间变量，单位为秒（精度到毫秒，如 0.042），它精确记录从 Nginx 向后端服务发起请求开始，到接收到后端响应的**第一个字节（即响应头结束）**所经过的时间。它不包含 Nginx 自身处理请求头或响应头的开销，也不含响应体传输耗时，因此是衡量后端应用“真实首包生成速度”的关键指标，对应业内常说的 TTFB（Time To First Byte）中属于后端侧的部分。
它到底在测什么
这个变量聚焦于后端服务内部的处理链路：包括接收请求、路由分发、业务逻辑执行、数据库/缓存访问、模板渲染（如适用）、构造并写出 HTTP 响应头等全部动作。只要后端进程把状态行和响应头写入 socket 缓冲区，Nginx 就会记录下这一刻的时间差。
注意两点：
- 如果后端使用 HTTPS，该时间包含 TLS 握手完成后的加密开销；
- 若发生重试（例如第一次连接失败后换节点），变量值会被最后一次成功请求的 header 时间覆盖，原始慢请求可能被“掩盖”。
怎么把它用起来
最直接有效的方式是写入 access_log，便于后续聚合分析：
在 http 或 location 块中定义日志格式：
'$status $body_bytes_sent "$http_referer" "$http_user_agent" '
'"$upstream_addr" $upstream_header_time $upstream_response_time';
再启用该格式：
access_log /var/log/nginx/perf.log upstream_perf;日志行末尾会出现类似 10.0.1.5:8000 0.042 0.047 的字段，其中 0.042 就是本次请求的 $upstream_header_time。
看懂它和其它时间变量的关系
单看一个数字意义有限，必须结合上下文对比：
- 若
$upstream_connect_time ≈ $upstream_header_time，说明后端几乎瞬间返回了响应头，瓶颈大概率在网络连接层（如 DNS 解析慢、防火墙策略、目标端口未就绪）； - 若
$upstream_header_time显著大于$upstream_connect_time，但又远小于$upstream_response_time，说明后端生成响应头耗时长，问题在业务逻辑或依赖服务（如慢 SQL、阻塞 I/O）； - 若
$upstream_header_time和$upstream_response_time都高且差值很小，说明后端处理快，但响应体传输慢——此时应检查是否启用了 gzip、响应体是否过大、或网络带宽受限。
常见陷阱与注意事项
这个变量在实际监控中容易被误读，需特别留意：
- 失败请求（超时、连接拒绝、502/504）中该值常为空或
-，做统计前务必过滤掉无效值； - 它反映的是“后端发出首字节”的时间，并非客户端真正看到首字节的时间（后者还受 Nginx 到客户端网络影响）；
- 不能替代应用层 APM 工具，它无法告诉你具体哪一行代码慢，只能确认“后端整体首包慢”，是缩小排查范围的第一步。
