PHP集成Jaeger实现链路追踪教程

本文深入剖析了在 Hyperf 框架中集成 Jaeger 实现链路追踪的实战要点与常见陷阱：从必须显式配置 `driver => 'jaeger'` 及正确的 `agent_host`（禁用 `localhost`，推荐 `127.0.0.1` 或容器服务名）、`agent_port => 6831`（UDP compact thrift）和 `service_name`，到直面 Jaeger UDP 上报无重试、无日志、易丢包的“静默失效”风险；同时揭示了 CLI 和定时任务中上下文缺失的根源，并给出手动启停 Root Span、跨进程透传 trace ID 的关键方案——这不是简单的配置切换，而是一场需结合抓包验证、环境隔离与协议细节把控的精准排障之旅。

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），得换用 zipkin driver 或自定义 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 里发现数据断层。

• 开发环境可用 docker run -d --name jaeger -p 6831:6831/udp -p 16686:16686 jaegertracing/all-in-one 快速验证，但别依赖它做生产上报
• 生产环境强烈建议改用 Jaeger Collector 的 HTTP 接口 + zipkin driver，或升级到 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 注解，但它仍不解决跨进程上下文传递问题

Hyperf 的 Jaeger 集成表面简单，实际卡点都在协议细节和运行时环境上——UDP 的不可见性、Docker 网络的 host 解析、CLI 场景的上下文真空，这些地方不亲手抓包、不看 agent 日志、不对比 span 数量，很容易以为“配置好了”，其实 trace 数据早被 silently 丢弃了。

以上就是《PHP集成Jaeger实现链路追踪教程》的详细内容，更多关于的资料请关注golang学习网公众号！