Tideways 在 PHP 生产环境需编译安装并手动启用Web追踪，确认加载需用 php --ri tideways 验证运行时配置，Web请求无数据因默认仅CLI自动追踪，须在入口文件顶部调用 tideways_enable()，FPM下需显式 tideways_disable() 防污染，采样应按响应时间条件触发并及时调用 tideways_get_trace() 上报。
Tideways 在 PHP 生产环境里不能直接“装完就用”，它依赖内核级扩展，必须编译安装，且默认不采集 HTTP 请求上下文——你看到的“慢请求”可能根本没进采样队列。
怎么确认 Tideways 扩展已正确加载
光看 php -m | grep tideways 不够，得验证运行时状态。很多部署失败是因为 .so 文件路径错、PHP 版本不匹配，或被 opcache 缓存了旧配置。
- 执行
php --ri tideways，输出里必须有tideways.enable => On和tideways.sample_rate => 100（或其他非零值） - 如果报
Extension 'tideways' not present，检查extension=行是否写在php.ini主配置里（不是 conf.d 下某个被注释的文件） - Apache 用户要确认改的是
apache2/php.ini而非 CLI 的/etc/php/*/cli/php.ini，两者常混用
为什么 Web 请求没数据，但 CLI 脚本能采到
Tideways 默认只对 CLI 模式启用自动追踪，Web 模式（如 Apache、FPM）需手动触发。这是最常被忽略的配置断点。
- 在入口文件（如
index.php）顶部加：if (extension_loaded('tideways')) { tideways_enable(TIDEWAYS_FLAGS_NO_SPANS | TIDEWAYS_FLAGS_MEMORY); } - 不要放在框架路由之后——Laravel 的
public/index.php可以，但 ThinkPHP 的start.php若延迟加载，就可能漏掉引导阶段耗时 - FPM 场景下，
tideways_disable()必须显式调用，否则可能污染后续请求（尤其长连接场景）
如何让采样真正覆盖关键请求
默认 tideways.sample_rate = 100 是每 100 个请求采 1 个，但实际业务中，你更关心“慢请求”而非“随机请求”。得靠条件采样。
立即学习“PHP免费学习笔记（深入）”；
- 在请求开始前判断响应时间预期：
if (isset($_SERVER['REQUEST_TIME_FLOAT'])) { $elapsed = microtime(true) - $_SERVER['REQUEST_TIME_FLOAT']; if ($elapsed > 0.5) { // 超过 500ms 强制采样 tideways_enable(TIDEWAYS_FLAGS_DEFAULT); } } - 避免在
try/catch外围无差别开启——异常堆栈会大幅增加开销，建议只在catch块里临时启用 - 采样后务必调用
tideways_get_trace()并发往 collector，否则数据留在内存里，PHP 进程重启就丢
真正难的不是装上 Tideways，而是让它在高并发下稳定吐出可定位的 trace 数据——比如 FPM 子进程复用时未清理 trace 上下文，会导致前后请求数据串扰；又比如 collector 服务响应慢，而 Tideways 默认同步发送，会拖慢整个请求。这些细节不调，监控就成了盲区。
