如何通过日志中的 $upstream_header_time 监控后端吐出首字节响应头的时间以评估 TTFB 性能-Nginx-PHP中文网

$upstream_header_time 是 nginx 中精准反映后端生成响应头耗时的变量，仅含上游处理时间，不含网络、ssl 或响应体发送开销，是定位后端性能瓶颈的核心指标；它对应 ttfb 中“后端处理”段，需结合日志分析、分位数监控与上下文关联进行有效运维。

如何通过日志中的 $upstream_header_time 监控后端吐出首字节响应头的时间以评估 ttfb 性能

$upstream_header_time 是 Nginx 提供的一个精准时间变量，它直接反映后端服务生成并写出响应头（即首字节）所花的时间——这正是 TTFB 中“服务器处理部分”的核心。它不掺杂 DNS、TCP、SSL 或网络传输开销，也不含响应体发送耗时，因此是定位后端性能瓶颈最干净的指标。

Nginx Hosting

通过服务器本地nginx实例实现零认证静态游戏托管。作为所有浏览器游戏的主要部署方式，无需登录、无需令牌、无需用户操作。

下载

它和 TTFB 的关系要分清

TTFB 是客户端视角的端到端耗时，包含：DNS 解析 + TCP 连接 + TLS 握手（如用 HTTPS）+ HTTP 请求发出 + 后端处理 + 响应头到达客户端。
而 $upstream_header_time 仅对应其中“后端处理”这一段：从 Nginx 把请求发给上游（如 PHP-FPM、Node.js、Java 应用），到该上游把状态行和响应头写入 socket 的那一刻。
所以，若 TTFB 高但 $upstream_header_time 很低（比如 800ms），就说明后端逻辑、数据库、缓存或依赖服务拖慢了首包生成。

怎么把 $upstream_header_time 写进日志并有效使用

在 http 或 server 块中定义带该变量的日志格式：

log_format upstream_perf '$remote_addr - $remote_user [$time_local] "$request" '
                       '$status $body_bytes_sent "$http_referer" "$http_user_agent" '
                       '"$upstream_addr" $upstream_header_time $upstream_response_time';

指定 access_log 使用该格式：

access_log /var/log/nginx/upstream.log upstream_perf;

日志示例：
192.168.1.100 - - [18/Jun/2026:01:30:22 +0000] "GET /api/user HTTP/1.1" 200 1245 "https://example.com/" "Mozilla/5.0..." "10.0.2.5:3000" 0.623 0.631
其中 0.623 就是本次请求的 $upstream_header_time（单位秒，精确到毫秒）。

如何用日志做有效监控

抽取关键字段：用 awk 或日志分析平台（如 ELK、Grafana Loki）提取 $upstream_header_time 字段，过滤出超阈值（如 >500ms）的请求。
计算分位数：重点关注 p75、p90、p95 值，比平均值更能反映真实用户遇到的慢请求比例。例如 p90 达到 1.2s，说明 10% 的请求后端首包生成已严重延迟。
关联上下文：结合 $upstream_addr（后端地址）、$request（路径）、$status（状态码）交叉分析——是否某接口、某节点、某错误码下该值集中偏高？
设置告警：当 p90 $upstream_header_time 连续 5 分钟超过 800ms，触发告警，提示后端服务需介入排查。