PHP怎样读取cURL连接排队时间

如果一个 PHP 服务并发发起很多 cURL 请求，慢请求不一定是远端接口处理慢，也可能是请求还没有拿到可用连接。PHP 8.5 新增的 CURLINFO_QUEUE_TIME_T 可以在传输结束后读取 libcurl 的连接队列等待时间，单位是微秒。它适合和 DNS、建连、首字节、总耗时一起记录，用来把“客户端资源不够”与“服务端响应慢”分开。

官方地址：https://www.php.net/manual/en/curl.constants.php

libcurl 说明：https://curl.se/libcurl/c/CURLINFO_QUEUE_TIME_T.html

先分清排队时间和接口响应时间

CURLINFO_QUEUE_TIME_T 表示传输在 libcurl 内部等待连接资源的时间，返回值是整数微秒。它通常和多句柄的总连接数、单主机连接数等限制有关；请求还没有真正开始 DNS、TCP 或 TLS 阶段时，就可能已经在队列中等待。

因此，queue_time_us 很大，首先说明客户端连接调度存在等待，不应直接归因于服务端。相反，排队值接近 0 而 starttransfer_time_us 或 total_time_us 很大，才值得继续看 DNS、建连、服务端首字节和响应体读取。

PHP 8.5 需要配合 libcurl 8.6 以上

PHP 手册把这个常量标记为 PHP 8.5.0 可用，同时要求底层 libcurl 至少为 8.6.0。这里有两个版本边界：PHP 扩展是否定义了常量，以及实际加载的 libcurl 是否支持对应信息项。部署在不同发行版或容器中时，不能只看 PHP 镜像标签就假定底层能力一致。

代码里用 defined() 做能力判断即可。能力不存在时，不要把 0 写进监控，因为 0 代表本次传输没有观察到排队，而“没有这个指标”应当保留为 null。

用 curl_getinfo() 读取微秒值

读取时机放在 curl_exec() 返回之后。下面的示例同时读取几个阶段字段，并把总耗时保留为微秒，后续再由指标系统统一换算，避免浮点秒数过早丢失精度。

 true,
    CURLOPT_TIMEOUT => 10,
]);

$body = curl_exec($ch);
$error = curl_error($ch);

if ($body === false) {
    // 请求失败时仍保留错误文本，避免把失败当成合法的耗时样本。
    throw new RuntimeException('cURL 请求失败：' . $error);
}

// 所有 *_TIME_T 值都是微秒；常量不存在时用 null 表示“不支持”。
$info = [
    'queue_time_us' => defined('CURLINFO_QUEUE_TIME_T')
        ? curl_getinfo($ch, CURLINFO_QUEUE_TIME_T)
        : null,
    'namelookup_time_us' => defined('CURLINFO_NAMELOOKUP_TIME_T')
        ? curl_getinfo($ch, CURLINFO_NAMELOOKUP_TIME_T)
        : null,
    'connect_time_us' => defined('CURLINFO_CONNECT_TIME_T')
        ? curl_getinfo($ch, CURLINFO_CONNECT_TIME_T)
        : null,
    'starttransfer_time_us' => defined('CURLINFO_STARTTRANSFER_TIME_T')
        ? curl_getinfo($ch, CURLINFO_STARTTRANSFER_TIME_T)
        : null,
    'total_time_us' => defined('CURLINFO_TOTAL_TIME_T')
        ? curl_getinfo($ch, CURLINFO_TOTAL_TIME_T)
        : null,
];

curl_close($ch);

// 只在有值时换算毫秒，避免把不支持的 null 变成 0。
$info['queue_time_ms'] = $info['queue_time_us'] === null
    ? null
    : $info['queue_time_us'] / 1000;

var_export($info);

这个示例没有人为制造连接限制，因此正常情况下排队值可能为 0；它展示的是读取契约，不代表每次请求都一定会产生排队。真正做并发观测时，应在多句柄或连接上限较紧的业务场景记录样本。

把指标放进慢请求归因

建议至少保留下面几类字段：

例如，排队时间占总耗时的大部分，优先查看并发度、每主机连接限制和多句柄调度；首字节时间明显增加但排队接近 0，则更像是上游处理、代理或网络路径问题。这里的“更像”是观测方向，不是单个字段就能证明完整根因。

旧版本不要伪造 queue_time_us

PHP 8.4 或更早版本，或者底层 libcurl 低于 8.6.0 时，CURLINFO_QUEUE_TIME_T 可能不存在。兼容代码的重点不是找一个同名替代值，而是明确记录指标缺失。可以继续记录已有的总耗时、建连和首字节字段，并在日志中补充运行环境版本。

 $queueTimeUs,
    'total_time_us' => curl_getinfo($ch, CURLINFO_TOTAL_TIME_T),
    'queue_metric_supported' => $queueTimeUs !== null,
];

生产日志还应避免把完整 URL、请求体或鉴权头直接写入样本。对排队指标来说，请求目标的主机、接口模板、运行环境版本和错误类型通常已经足够支撑聚合分析。

落地时记住这三个判断

1. CURLINFO_QUEUE_TIME_T 读的是 libcurl 连接队列等待，不是服务端队列，也不是完整网络耗时。
2. 读取要放在传输结束后，单位是微秒；需要展示时再换算为毫秒。
3. PHP 8.5 与 libcurl 8.6+ 才能稳定获得该指标，旧环境用 null 表示不支持，不要伪造 0。

相关问题

• queue_time_us 为 0 是不是接口一定很快？ 不是，它只说明没有观察到连接队列等待，DNS、建连、服务端处理和响应体仍可能很慢。
• 为什么 total_time_us 比各阶段相加更难解释？ 重定向、连接复用和不同协议阶段会影响时间字段，应该结合请求配置和响应状态一起看。
• 只使用 curl_exec() 能看到排队时间吗？ 可以，前提是扩展和底层 libcurl 支持该信息项，并在执行后调用 curl_getinfo()。