ThinkPHP需借助OpenTelemetry等APM SDK，通过中间件在请求入口动态读取Redis/配置的采样率并构建新Sampler实现开关，不能在控制器中修改已创建Span的采样率。
ThinkPHP 接口如何动态控制全链路追踪采样开关
直接说结论：ThinkPHP 本身不内置分布式链路追踪能力，所谓“动态开关”必须依赖外部 APM 工具（如 SkyWalking、Zipkin、OpenTelemetry）的 SDK，并通过中间件 + 配置驱动实现。没有统一的 setSamplingRate() 方法，一切开关逻辑得自己写。
为什么不能直接在控制器里调用 Tracer::setSampling()
因为大多数 PHP APM SDK（比如 open-telemetry/sdk 或 skywalking/php-sdk）的采样决策发生在请求入口（如中间件或 Bootstrapper），一旦 span 创建完成，再改采样率对当前请求无效。常见错误是：在控制器里读配置、调 SDK 方法，结果链路依然被采或没被采——不是代码没跑，而是时机错了。
- 采样判断通常在
RequestSpanMiddleware或Bootstrap阶段完成 - SDK 初始化后，
Tracer实例一般全局单例，但采样器（Sampler）不可热替换 - 想“动态”，只能在每次请求初始化 tracer 时，根据实时配置构造新
Sampler
怎么在 ThinkPHP 中真正实现运行时采样开关
核心思路：把采样率从硬编码/配置文件挪到可运行时读取的位置（如 Redis、数据库、环境变量），并在中间件中按需构建 Sampler。以 OpenTelemetry PHP 为例：
- 在
app/middleware/TraceMiddleware.php的handle()开头，读取cache()->get('trace:sampling_rate')，默认 fallback 到 0.1 - 用
new ProbabilitySampler($rate)构造新采样器，传给TracerProvider::builder()->setSampler(...) - 注意：不能复用已初始化的
TracerProvider，必须为每个请求新建（或至少确保 sampler 可插拔） - 若用 Redis 存开关，建议加本地缓存（如
Runtime::getAppPath() . 'runtime/trace_sampling.php'），避免每请求都打 Redis
示例关键片段：
$rate = (float) cache()->get('trace:sampling_rate', config('trace.default_sampling', 0.1));
$sampler = new ProbabilitySampler($rate);
$provider = TracerProvider::builder()
->setSampler($sampler)
->build();
容易踩的坑：开关生效但链路断掉或数据错乱
这不是开关没起作用，而是上下文传递或生命周期管理出问题。典型现象：parent_span_id 为空、跨服务 trace_id 不一致、HTTP header 里 traceparent 没透传。
- 确认中间件顺序：TraceMiddleware 必须在所有业务中间件之前，且在
SessionMiddleware之后（避免 session 启动干扰 span） - 检查是否漏了
Propagator::extract()：HTTP 请求进来时，要从$_SERVER['HTTP_TRACEPARENT']解析上下文，否则子链路会新建 trace_id - 别在
__destruct()或register_shutdown_function()里 flush span：ThinkPHP 的生命周期可能早于 span 完成，导致上报丢失 - 开启 debug 日志时，
OTEL_LOG_LEVEL=debug会显著拖慢接口，线上务必关掉
最麻烦的点其实不在开关本身，而在「开关只影响本服务」——上游没传 trace context，下游收不到 parent id，整个链路就断成两截。这事跟 ThinkPHP 关系不大，但你得协调好网关和上下游服务的传播协议。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
