PHP网站分布式链路追踪失效时，可选SkyWalking PHP SDK（v4.2.0）实现无侵入追踪、Zipkin PHP客户端（HTTP上报）实现轻量级追踪、ThinkPHP中间件动态控制采样率、Workerman长连接场景下Trace ID透传方案。
如果您正在为PHP网站构建分布式链路追踪能力，但请求调用链路无法串联、跨服务Span丢失或UI中无数据展示，则可能是由于客户端配置不匹配、协议不兼容或上下文透传缺失所致。以下是针对PHP网站集成SkyWalking与Zipkin的多种可行方案：
一、使用SkyWalking PHP SDK（v4.2.0）实现无侵入式追踪
SkyWalking PHP Agent采用字节码增强机制，在不修改业务代码前提下采集cURL、PDO、Redis等组件调用数据，适用于Swoole及传统FPM环境，依赖gRPC通信，需预编译扩展。
1、安装gRPC C++依赖：执行yum install -y boost-devel，随后克隆并编译gRPC源码至/var/local/git/grpc目录。
2、下载并解压SkyWalking PHP SDK v4.2.0：运行wget https://github.com/SkyAPM/SkyAPM-php-sdk/archive/refs/tags/v4.2.0.tar.gz && tar -zxvf v4.2.0.tar.gz。
立即学习“PHP免费学习笔记（深入）”；
3、编译安装扩展：进入解压目录，依次执行phpize、./configure --with-grpc=/var/local/git/grpc、make && sudo make install。
4、启用扩展并配置参数：在php.ini中添加以下内容：
extension=skywalking.so
skywalking.enable=1
skywalking.version=8
skywalking.app_code=your_php_website。
5、启动Collector服务并确保PHP进程能通过gRPC连接至collector:11800（默认地址），注意：v4.2.0不支持认证，禁止将collector暴露于公网。
二、使用Zipkin PHP客户端（HTTP上报）实现轻量级追踪
Zipkin客户端基于OpenTracing规范，通过HTTP POST向Zipkin Server发送JSON格式Span数据，具备连接池、重试与错误反馈机制，适合对上报可靠性要求较高的PHP网站。
1、通过Composer安装Zipkin库：执行composer require zipkin/zipkin。
2、初始化Tracer实例时指定阿里云或自建Zipkin Endpoint：将Config::TRACE_URL设为https://tracing.aliyuncs.com/api/v2/spans或http://zipkin:9411/api/v2/spans。
3、在请求入口中间件中创建Server Span：调用$tracing->getTracer()->nextSpan($extractedContext)，并设置setName("Server:/" . $request->path())与setKind(SERVER)。
4、在HTTP客户端调用前注入traceparent头：使用$injector($span, $tmpHeaders)将W3C Trace Context写入请求头，必须确保所有下游服务均支持traceparent解析。
5、在响应返回后调用$span->finish()并显式执行$tracer->flush()，避免因长连接复用导致Span滞留内存未上报。
三、在ThinkPHP框架中动态控制采样率
为降低生产环境性能开销，可在ThinkPHP中通过中间件读取运行时配置实现采样开关，避免全量埋点。该方式不依赖SDK内置采样器热替换能力，而是在每次请求初始化时构造新Sampler。
1、在app/middleware/TraceMiddleware.php的handle()方法开头读取Redis中的采样率：$rate = (float) cache()->get('trace:sampling_rate', 0.01);。
2、使用OpenTelemetry PHP SDK构建带概率采样的TracerProvider：$sampler = new ProbabilitySampler($rate);，并传入TracerProvider::builder()->setSampler($sampler)。
3、将生成的Tracer绑定至Request对象或容器实例，供后续控制器与服务层调用：$this->app->bind('Tracer', $provider->getTracer());。
4、在全局异常处理中补全Span生命周期：捕获未完成的Span并强制调用$span->finish()，防止因异常中断导致trace_id孤立、链路断裂。
5、验证采样开关效果：在Redis中临时设置trace:sampling_rate为0，确认Zipkin UI中无新增Span；恢复为0.1后观察数据回归。
四、Workerman长连接场景下的Trace ID透传方案
Workerman常驻进程特性导致传统HTTP Header透传失效，需在连接建立阶段即生成并维护Trace上下文，确保同一TCP连接内多个请求共享或隔离Trace ID。
1、在onConnect回调中为新连接生成唯一connection_id，并创建初始Span：$span = $tracer->newTrace()->start();。
2、将$span->getContext()->getTraceId()存入Connection上下文：$connection->trace_id = $traceId;。
3、当收到业务请求时，优先从连接上下文中提取Trace ID，再结合当前操作生成子Span：$childSpan = $tracer->nextSpan($parentId);。
4、对外发起HTTP请求时，手动注入traceparent头：$request = $request->withHeader('traceparent', $childSpan->getContext()->getTraceParent());。
5、在onClose回调中调用$span->finish()并触发$tracer->flush()，避免连接关闭后Span丢失，造成链路截断。
