Hyperf 的 tracer 组件默认不启用 Jaeger，需显式配置 driver 为 'jaeger' 并正确设置 agent_host、agent_port（6831）、service_name；Jaeger 使用 UDP 上报，无重试机制，CLI 场景无自动上下文传递。
Hyperf 里 tracer 组件默认不启用 Jaeger，必须显式配置
Hyperf 的 tracer 组件开箱只支持 Zipkin 和 OpenTracing 协议，Jaeger 虽然也基于 OpenTracing（v1）或 OpenTelemetry（v2），但它的 UDP 上报方式、agent 地址格式、采样策略默认值都和 Zipkin 不同，直接复用 Zipkin 配置会静默失败——没有报错，但 Jaeger UI 里完全看不到 span。
- 必须在
config/autoload/tracer.php中将driver显式设为'jaeger'，不能留空或写'zipkin' - Jaeger agent 默认监听
localhost:6831（compact thrift over UDP），不是 HTTP 端口；如果用的是 Jaeger Collector 的 HTTP 接口（如http://localhost:14268/api/traces），得换用zipkindriver 或自定义 reporter -
endpoint配置项对 Jaeger driver 无效，真正起作用的是agent_host和agent_port
Jaeger driver 的关键参数只有三个：host、port、service_name
Hyperf 的 Jaeger driver 封装较薄，不支持动态采样、tag 过滤、TLS 等高级特性。它只认以下三个核心配置，其余字段会被忽略：
-
agent_host：Jaeger Agent 的 IP，容器内常为'jaeger'（对应 docker-compose service 名），本地开发写'127.0.0.1'；千万别写'localhost'—— 在 Docker 容器里它指向容器自身，不是宿主机 -
agent_port：固定是6831（compact thrift），不是5775（deprecated）、14267（collector gRPC）或14268（HTTP） -
service_name：必须设置，且建议与 Hyperf 服务名一致（如'user-api'），否则所有 span 都归到'unknown-service'下，无法按服务筛选
示例配置片段（config/autoload/tracer.php）：
'driver' => 'jaeger',
'jaeger' => [
'agent_host' => '127.0.0.1',
'agent_port' => 6831,
'service_name' => 'user-api',
],
UDP 丢包会导致 span 完全丢失，无重试、无日志提示
Jaeger client 默认走 UDP 发送 span，轻量但不可靠。Hyperf tracer 的 Jaeger driver 没有内置重试、缓冲队列或错误回调，一旦网络不通、agent 崩溃或单包超长（>65KB），span 就彻底消失，且 Hyperf\Tracer\Tracer 不会抛异常、也不打 warning 日志——你只能在 Jaeger UI 里发现数据断层。
立即学习“PHP免费学习笔记（深入）”；
- 开发环境可用
docker run -d --name jaeger -p 6831:6831/udp -p 16686:16686 jaegertracing/all-in-one快速验证，但别依赖它做生产上报 - 生产环境强烈建议改用 Jaeger Collector 的 HTTP 接口 +
zipkindriver，或升级到 Hyperf 3.x + OpenTelemetry SDK 自行对接 OTLP - 可通过
netstat -uapn | grep :6831或tcpdump -i lo udp port 6831确认 UDP 包是否发出
HTTP 请求的 trace_id 不会自动透传到 CLI 命令或定时任务
Hyperf 的 tracer 中间件只对 HTTP/Swoole Request 生效，CLI 命令（如 php bin/hyperf.php my:command）和 crontab 任务默认没有父上下文，Tracer::getTracer()->getCurrentSpan() 返回 null，所有 span 都是 root span，无法串联调用链。
- 手动启动 span 需调用
Tracer::getTracer()->startRootSpan()，并在 finally 中finish()，否则内存泄漏 - 若命令需继承上游 HTTP 的 trace_id（比如异步发消息后回调处理），得从环境变量、Redis 或 MQ header 里手动提取
uber-trace-id或traceparent，再用Tracer::extract()注入上下文 - Hyperf 2.2+ 提供了
Hyperf\Tracer\Aspect\TraceAnnotationAspect，可在方法上加@Trace注解，但它仍不解决跨进程上下文传递问题
