ThinkPHP需手动集成Jaeger实现分布式追踪：一、中间件透传trace_id；二、用jukylin/jaeger-php直连Agent；三、Db::listen与HttpHook自动埋点；四、对接Agent控制面动态采样；五、自建HTTP上报层提升可靠性。
如果您在ThinkPHP项目中需要实现跨服务的请求链路可视化与性能分析，则必须手动集成外部分布式追踪系统。ThinkPHP本身不提供OpenTracing/OpenTelemetry兼容能力，也无内置Trace上下文透传机制，所有埋点、span生命周期管理、采样控制及上报逻辑均需开发者自主实现。以下是可行的集成路径：
一、通过中间件注入全局trace_id并透传
该方法用于建立跨HTTP请求的链路上下文基础，确保下游服务能延续同一trace。需在入口中间件中解析并生成trace_id、span_id，并写入响应头供下游提取。
1、创建中间件类App\Middleware\JaegerContextMiddleware，实现handle方法。
2、从请求头X-B3-TraceId、X-B3-SpanId、X-B3-ParentSpanId中提取已有上下文；若不存在，则生成新的trace_id（如uniqid()）和span_id（如dechex(crc32(microtime(true)))）。
立即学习“PHP免费学习笔记（深入）”；
3、将trace_id、span_id、parent_span_id、sampled标志（默认true）存入ThinkPHP容器：Container::getInstance()->bind('jaeger_context', $context)。
4、向响应头写入X-B3-TraceId、X-B3-SpanId、X-B3-ParentSpanId、X-B3-Sampled，确保下游服务可读取。
二、使用jukylin/jaeger-php客户端直连Agent
该方案绕过框架封装，直接调用轻量级Jaeger PHP SDK，适用于对上报可控性要求高的场景，支持UDP compact thrift协议，适配Jaeger Agent默认端口6831。
1、执行composer require jukylin/jaeger-php安装客户端库。
2、在应用初始化阶段（如common.php或AppServiceProviders中），调用Config::getInstance()->initTracer('thinkphp-api', '127.0.0.1:6831')。
3、从容器中获取jaeger_context，调用$tracer->startSpan($operationName, ['child_of' => $spanContext])启动根span。
4、在控制器方法结束前，显式调用$span->finish()关闭span，触发UDP上报。
5、关键提示：务必确认Jaeger Agent运行在127.0.0.1:6831且防火墙放行UDP流量，否则span将静默丢失。
三、基于Db::listen与HttpHook进行自动埋点扩展
该方法用于在SQL执行与HTTP远程调用环节自动注入span，减少业务代码侵入，但需配合手动span生命周期管理使用。
1、在Db::listen回调中，检查当前是否存在活跃span，若有，则创建子span，标签设为db.query、sql.type、sql.statement（截断至256字符）。
2、监听ThinkPHP的http_request_begin与http_request_end事件，在发起HTTP请求前创建client span，设置tag为http.url、http.method、http.status_code（暂设为0），并在收到响应后更新status_code并finish。
3、为每个子span设置reference类型为CHILD_OF，引用父span上下文。
4、注意：Db::listen仅捕获查询，不捕获事务开启/提交/回滚，需在事务方法中手动打点。
四、配置动态采样率并对接Jaeger Agent控制面
该方法利用Jaeger Agent的远程采样策略接口，使采样率可在运行时调整，避免重启服务，适用于高流量生产环境。
1、启动Jaeger Agent时启用采样控制服务：--sampling.strategies-file=/path/to/sampling.json。
2、编写sampling.json，定义按服务名、endpoint路径匹配的采样规则，例如对/api/v1/order/*路径设置probabilistic采样率为0.05。
3、在jukylin/jaeger-php初始化时，将sampler.type设为remote，而非const或probabilistic。
4、客户端会定期（默认1分钟）向Agent的http://127.0.0.1:5778/sampling?service=thinkphp-api发起GET请求获取最新采样策略。
5、重要提醒：若Agent未启用5778端口或策略文件格式错误，客户端将回退至默认const=1采样，可能导致性能陡增。
五、自建上报中间层规避UDP丢包风险
该方法用HTTP方式替代UDP向Jaeger Collector直传数据，牺牲少量性能换取可靠性，适用于无法容忍span丢失的关键业务线。
1、禁用jukylin/jaeger-php的UDP reporter，改用自定义HTTP reporter类，继承Jaeger\Reporters\ReporterInterface。
2、实现report方法，将span序列化为JSON格式，POST至Jaeger Collector的http://127.0.0.1:14268/api/traces端点，Content-Type设为application/x-thrift。
3、添加重试机制（最多3次）、失败日志记录（写入runtime/log/jaeger_fail.log）及内存缓冲队列（限制100条未发送span）。
4、在容器绑定时替换默认reporter：$config->setReporter(new HttpReporter(...))。
5、特别注意：Collector HTTP端口14268需明确启用，且thrift序列化必须使用compact协议，否则Collector将拒绝接收。
