trace_connect() 返回值可能为 false，需立即检查；若为 false，应调用 trace_get_last_error() 获取具体错误原因，如“Connection refused”。
查 trace_connect() 返回值是否为 false
Trae 平台（注意不是主流的 “Trace” 或 “Jaeger”，而是国内某 APM 厂商定制平台）的 PHP SDK 通常用 trace_connect() 初始化连接，但这个函数不抛异常，只返回布尔值。很多开发者直接调用后没检查返回值，导致后续所有上报静默失败。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 必须在
trace_connect()后立即加判断：if (false === trace_connect(['host' => '127.0.0.1', 'port' => 9090'])) { error_log('Trae connect failed: ' . trace_get_last_error()); } -
trace_get_last_error()是唯一能拿到具体错误原因的函数，比如"Connection refused"或"Invalid host format"，不调它等于盲调 - 某些旧版 SDK 中，
trace_connect()在超时后仍返回true，实际连接未建立——此时需配合trace_is_connected()双重校验
确认 Trae Agent 监听地址和协议是否匹配
Trae 的 PHP SDK 默认走 UDP 发送数据，但 Agent 端可能只监听 TCP，或绑定了非 0.0.0.0 地址。本地 telnet 或 nc 测不通，不代表 SDK 没发——UDP 不会报错，只是丢包。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 先用
netstat -tuln | grep :9090（Linux）或Get-NetTCPConnection -LocalPort 9090（Windows PowerShell）确认 Agent 确实在监听且是0.0.0.0:9090，而非127.0.0.1:9090 - PHP SDK 配置中若显式设了
'protocol' => 'tcp'，但 Agent 没开 TCP 模式，连接必然失败；反之亦然。默认无该配置项即走 UDP - Docker 环境下注意：PHP 容器里写的
host: 'localhost'实际连的是容器自身，不是宿主机——得换成host: 'host.docker.internal'（Docker Desktop）或宿主机真实 IP
检查 PHP 进程是否被禁用 socket 扩展或限制了 outbound UDP
部分生产环境出于安全策略，会禁用 sockets 扩展，或通过 iptables/nftables 拦截 UDP 出向流量。这时 trace_connect() 返回 false，但 trace_get_last_error() 可能只报 "Unknown error"。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 运行
php -m | grep sockets确认扩展已启用；若无输出，需在php.ini中取消;extension=sockets的注释并重启 PHP 进程 - 用最简 UDP 测试脚本验证网络通路：
$fp = socket_create(AF_INET, SOCK_DGRAM, SOL_UDP); if ($fp === false) { var_dump(socket_strerror(socket_last_error())); } - SELinux 启用时，PHP 进程可能被禁止创建 UDP socket，临时放行：
setsebool -P httpd_can_network_connect 1（Apache）或对应服务名
SDK 版本与 PHP 版本不兼容导致静默失效
Trae 官方 PHP SDK 2.x 仅支持 PHP 7.2–7.4；3.x 开始要求 PHP 8.0+。用 PHP 8.1 跑 2.x SDK，trace_start_span() 可能不报错但也不生效——因为内部用了已被废弃的 create_function() 或反射调用方式。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 执行
php --ri trace查看已加载 SDK 版本；再核对php -v输出的主版本号 - 升级 SDK 前，先确认 Trae Agent 版本是否兼容新 SDK 协议（尤其 v3 SDK 默认启用了压缩和 batch 上报，老 Agent 可能无法解析）
- 若无法升级 SDK，可在
php.ini中加error_reporting = E_ALL并开启display_errors = On，部分致命兼容问题会在error_log中留下Deprecated或Warning级提示
真正卡住人的，往往是 UDP 连接失败却不报错、Agent 绑定地址写成 127.0.0.1 却跑在容器里、还有那个藏得极深的 sockets 扩展开关——这三处不逐个排除，光看日志和代码只会循环怀疑人生。
