ThinkPHP怎样集成Skywalking链路_Skywalking链路追踪配置【全链】

ThinkPHP集成SkyWalking：从弃用归档Agent到OpenTelemetry手动埋点全指南

在ThinkPHP项目中集成SkyWalking进行链路追踪，有一个核心前提需要明确：框架本身并不提供自动埋点能力。而过去常用的SkyWalking PHP Agent，其官方支持已相当有限，并且项目已经归档停止维护。因此，当前的主流技术路线，是转向使用OpenTelemetry SDK进行手动埋点，再结合中间件来控制全链路的上下文透传。下面，我们就来拆解具体的实施步骤。

一、禁用 SkyWalking PHP Agent 并切换至 OpenTelemetry 手动埋点

首先需要正视一个现状：SkyWalking官方的PHP Agent（skywalking-php）自2023年起就已归档，不再更新。更重要的是，它的自动注入机制很容易与ThinkPHP中间件的采样逻辑产生冲突，导致链路追踪信息（trace）泄露或者上下文丢失。所以，第一步就是停用这个旧Agent，转而采用更可控的OpenTelemetry PHP SDK进行手动埋点。

具体操作分几步走：

1. 设置环境变量 SW_AGENT_DISABLE=1，确保原有的Agent不会被加载。

2. 通过Composer安装OpenTelemetry SDK：执行命令 composer require open-telemetry/sdk。

立即学习“PHP免费学习笔记（深入）”；

3. 在 app/middleware/TraceMiddleware.php 这个中间件的handle方法开头，添加初始化的代码。这样做的好处是避免在多个控制器中重复进行初始化操作。

4. 确认 opentelemetry/exporter-otlp 这个包也已安装，并配置OTLP HTTP的端点（endpoint），指向SkyWalking OAP服务的地址：http://skywalking-oap:11800/v1/traces。

二、在中间件中完成 TraceContext 解析与 Span 创建

这是保证链路不断裂的关键环节。请求入口处必须正确解析上游服务传递过来的 traceparent 头部信息，否则，跨服务调用就会生成全新的trace_id，整个链路也就断开了。OpenTelemetry要求我们在中间件中显式地调用 Propagator::extract() 方法，然后根据解析结果来决定是创建根span（root span）还是子span（child span）。

流程如下：

1. 从 $_SERVER[‘HTTP_TRACEPARENT’] 中提取出traceparent字符串。

2. 调用 TraceContextPropagator::getInstance()->extract($carrier) 来恢复上下文。

3. 使用 TracerProvider::builder()->setSampler(…)->build() 来构建一个带有采样策略的Tracer实例。

4. 调用 $tracer->startSpan($request->url(), […]) 来创建span。如果没有父上下文，就创建root span；如果有，就创建child span。

5. 将这个span设置为一个全局可访问的对象，方便后续数据库操作、HTTP调用等其他中间件复用。

三、注入 HTTP 调用透传逻辑（关键跨服务环节）

ThinkPHP默认的Http类或者常用的Guzzle客户端，并不会自动携带traceparent头部。因此，必须在发起远程请求前手动注入这个信息，否则下游服务就无法延续同一个trace_id。这个操作务必要在业务逻辑调用之前完成，不能延迟到响应阶段。

具体实施要点：

1. 在你封装的HTTP请求方法里（比如放在 app/common/HttpHelper.php），检查当前是否存在活跃的span。

2. 如果存在，就调用 $propagator->inject($spanContext, $headers)，将traceparent信息写入请求头。

3. 确保 headers[‘traceparent’] 被正确地附加到Guzzle或者内置curl的请求选项中。

4. 对于所有第三方SDK（比如对Redis、MySQL PDO的封装），同样需要注入span context，避免子链路缺失。

四、过滤非业务流量以降低数据噪音

如果不对流量进行过滤，那么像Eureka心跳、健康检查、静态资源请求这类高频的非业务接口，就会大量涌入SkyWalking，挤占宝贵的存储和查询资源。所以，必须在中间件里根据URI、Header或者请求特征，进行白名单或黑名单的拦截，只对核心的业务接口启用追踪。

可以这样实现：

1. 定义一个业务路径的白名单数组，例如 [‘/api/v1/user’, ‘/api/v1/order’, ‘/pay/notify’]。

2. 在TraceMiddleware中，判断请求的URL是否以白名单中的路径开头，可以使用类似 Str::startsWith($request->url(), $whitelist) 的方法。

3. 对于不匹配的请求，直接 return $next($request)，跳过span创建和上下文管理这一套流程。

4. 对于那些包含了 X-Skip-Trace: true 这类特殊头部的请求，也执行跳过逻辑，便于在灰度发布或调试时临时关闭追踪。

五、验证链路完整性与上下文一致性

全部集成完成后，验证工作必不可少。核心是验证trace_id是否在跨服务时保持一致，parent_span_id是否正确嵌套，以及各个span的耗时是否真实反映了业务逻辑。如果验证失败，问题通常出在中间件的执行顺序错误，或者上下文没有正确绑定，而不是SDK本身的配置问题。

验证步骤建议如下：

1. 启动你的ThinkPHP应用和SkyWalking UI界面，然后发起一次包含跨服务调用的请求（例如，调用订单服务，订单服务内部再调用支付服务）。

2. 在SkyWalking UI的「Trace List」中，搜索对应的trace_id，确认链路中间出现了不少于3个服务节点。

3. 点击具体的trace查看详情，核对每个segment（段）的 service.name 和 endpoint.name 是否准确无误。

4. 检查每个span的 parent_span_id 是否非空，并且与上一级span的id能够匹配上。

5. 最后确认HTTP请求对应的span中，包含了 http.url 和 http.status_code 这类关键标签信息。