ThinkPHP 8 可原生接入 OpenTelemetry PHP SDK，但需手动初始化 TracerProvider、在中间件中提取并激活 trace context、重写数据库/Redis驱动以注入 Span，并通过 Request Header 或 Context 透传 trace_id 实现日志关联。
ThinkPHP 8 如何接入 OpenTelemetry PHP SDK
直接说结论：ThinkPHP 8（基于 Laravel 风格的容器和中间件机制）可以原生接入 open-telemetry/sdk，但必须绕过其自动加载器冲突，并手动注册全局 TracerProvider。官方 opentelemetry-php-contrib 尚未提供 ThinkPHP 专用扩展包，不能直接 composer require opentelemetry/opentelemetry-contrib 后开箱即用。
常见错误现象是：Class 'OpenTelemetry\SDK\Trace\TracerProvider' not found，或请求链路中断在中间件之后——本质是 SDK 初始化时机早于应用容器启动，导致上下文无法绑定到 Request/Response 生命周期。
- 先执行
composer require open-telemetry/sdk open-telemetry/exporter-otlp-http（推荐 HTTP exporter，兼容性优于 gRPC） - 在
app/bootstrap.php或public/index.php顶部（require __DIR__.'/../vendor/autoload.php';之后、think\App实例化之前）初始化 SDK - 务必调用
GlobalTracerProvider::set()，否则后续trace_get_active_span()始终返回 null - 避免在
config/tracer.php中使用闭包配置——ThinkPHP 的 config 缓存机制会序列化失败
如何在中间件中注入 Span 并关联 Request ID
ThinkPHP 的中间件是链路埋点的核心位置，但默认不透传 trace context，需手动从 HTTP Header 提取 traceparent 并激活上下文。否则所有 Span 都是孤立的 root span，无法形成调用链。
典型场景：用户发起一个 POST 请求，后端调用 Redis + MySQL + 第三方 HTTP 接口，但 Jaeger 页面只看到三个平级 Span，没有父子关系。
立即学习“PHP免费学习笔记（深入）”；
- 新建中间件
app/middleware/TraceMiddleware.php，在handle()开头调用Propagation::extract($request->header()) - 用
Tracer::spanBuilder('http.request')->setParent(...)->startSpan()显式设置 parent context - 将生成的
trace_id注入$request->withHeader('X-Trace-ID', $span->getContext()->getTraceId())，供下游日志记录使用 - 注意：不要在
__destruct()中 finish span——中间件对象可能被复用，应严格在finally块中 close
MySQL 和 Redis 操作如何自动采集 Span
ThinkPHP 的数据库和缓存操作封装较深，opentelemetry-php-contrib 提供的 pdo 和 redis instrumentations 无法直接 hook 到 think\db\Connection 或 think\Cache 实例上，必须重写驱动或包装方法。
性能影响明显：若对每条 SQL 都新建 Span，高并发下会产生大量小 Span，拖慢 exporter 上报速度，甚至触发 OTLP 限流（默认单次最多 500 条 span）。
- 推荐方案：在
think\db\Connection::query()和think\db\Connection::execute()方法前后插入手动 Span —— 通过 AOP 或继承重写驱动类 - Redis 同理，在
think\cache\driver\Redis::get()等关键方法里 wrap 调用，Span 名建议设为redis.get/redis.set而非泛化的cache.operation - 务必设置
span->setAttribute('db.statement', $sql)，但要截断过长 SQL（如 > 512 字符），避免撑爆 collector 内存 - 禁用
db.connection_string属性（含密码），改用db.name+db.system: mysql安全标识
日志与 Trace 如何通过 TraceID 关联
ThinkPHP 默认日志不携带 trace_id，导致排查问题时需来回切换 Jaeger 和日志平台，无法一键下钻。OpenTelemetry 不强制日志集成，必须主动桥接。
容易踩的坑是：在 LogWriter 中直接调用 trace_get_active_span()，结果返回 null——因为日志可能发生在异步队列、定时任务或 CLI 命令中，此时没有活跃 Span。
- 最佳实践：在
app/common/Log.php或自定义think\Log扩展中，优先从当前 Request 对象读取X-Trace-IDheader；若无，则 fallback 到context_get('trace_id')（需提前在中间件中写入 Context） - 使用
think\facade\Log::info('user login success', ['trace_id' => $tid])显式传参，比依赖自动注入更可靠 - ELK 或 Loki 中配置日志解析规则，提取
trace_id字段并建立与 Jaeger 的 trace_id 索引映射 - 避免在日志 message 字符串里拼接 trace_id（如
"[{$tid}] login ok"），不利于结构化检索
全链路不是堆功能，而是确保每个环节的 context 不丢失、不伪造、不跨生命周期误用。最常被忽略的是 CLI 命令和队列任务的 Span 初始化——它们没有 HTTP header，必须靠环境变量或配置显式传入 parent context，否则整条链就断在第一个异步节点。
