ThinkPHP 6.1 本身不内置分布式链路追踪能力，必须集成 OpenTelemetry/SkyWalking 等外部 APM SDK，通过 TraceMiddleware 在请求入口动态构建 Sampler、透传 traceparent、手动桥接 DB/Cache/Log 上下文实现全链路追踪。
ThinkPHP 6.1 本身不提供开箱即用的分布式链路追踪能力，它需要你主动集成外部 APM 工具（如 OpenTelemetry、SkyWalking 或 Zipkin 的 PHP SDK），再通过中间件+配置驱动的方式，在请求入口完成 trace 初始化与上下文透传。核心不是“加个扩展就能用”，而是把采样、span 创建、header 注入/提取、跨服务传递这些环节全部串起来。
必须在中间件中初始化 Tracer 并控制采样逻辑
链路追踪的起点必须落在请求最开始的位置，否则 span 缺失、parent_id 断连、trace_id 不一致等问题必然出现。不能在控制器里补救，也不能靠 config 文件静态配置完事。
- 在
app/middleware/TraceMiddleware.php的handle()方法开头读取实时采样率（例如从 Redis 或环境变量） - 根据该值构造新的
ProbabilitySampler，再用它创建独立的TracerProvider实例 - 确保每次请求都走这一套流程，避免复用全局单例导致采样策略失效
HTTP header 必须双向透传 traceparent 和 tracestate
跨服务调用时，上下游 trace 能否串联，取决于 traceparent（格式：00-<traceid>-<spanid>-01）是否被正确注入与解析。
- 出站请求（如调用其他微服务）需在 Guzzle 或 curl 封装层自动注入
traceparent头 - 入站请求需在中间件中调用
Propagation::extract($request->header())恢复上下文 - 若使用 OpenTelemetry PHP，推荐搭配
open-telemetry/propagator-b3或w3c标准，避免自定义头引发兼容问题
日志、数据库、缓存等操作要手动挂载 span 上下文
ThinkPHP 的 Db、Cache、Log 等组件不会自动关联当前 span，必须显式桥接。
- 使用
Span::getCurrent()获取活跃 span，在 SQL 执行前后记录db.statement、db.instance等属性 - 对于 Redis 操作，可在
think\cache\driver\Redis的get()/set()方法前后打点，标注cache.key和cache.hit - 日志建议统一走
Logger::info('db_query', ['trace_id' => $span->getContext()->getTraceId()])，便于 ELK 或 Grafana 关联分析
避免常见断链陷阱
很多团队配完发现 trace_id 每跳都变、parent_span_id 为空、跨服务看不到完整调用图——这不是 SDK 没生效，而是上下文没接住。
- Nginx 或 SLB 必须透传
traceparent，禁止过滤或重写该 header - CLI 命令行任务（如
php think queue:work）默认无 HTTP 上下文，需手动初始化RootSpan或跳过追踪 - 异步任务（如队列消费、定时任务）若需链路延续，必须把
traceparent作为 payload 字段随任务一起序列化传递，并在消费者端重新 extract
不复杂但容易忽略
