必须集成New Relic PHP Agent探针：一、安装newrelic.so扩展并验证PHP非ZTS模式；二、在中间件中调用newrelic_name_transaction()手动命名事务；三、启用newrelic.transaction_tracer.detail=1及newrelic.capture_params=true；四、在异常处理器中调用newrelic_notice_error()上报错误。
如果您正在使用 ThinkPHP 框架开发 Web 应用，并希望在生产环境中实现全链路性能监控，则必须正确集成 New Relic PHP Agent 探针。该探针无法通过 Composer 安装生效，必须依赖 newrelic.so 扩展完成底层字节码注入，且需结合 ThinkPHP 的生命周期手动命名事务以避免所有请求归类为 OtherTransaction/PHP/。以下是具体实施步骤：
一、确认环境兼容性并安装 newrelic.so 扩展
New Relic PHP Agent 仅支持 Linux/macOS 系统，不兼容 Windows；要求 PHP 版本为 7.2–8.3 且为非 ZTS（线程安全）模式。ThinkPHP 运行于 Apache 或 Nginx + PHP-FPM 架构时，必须确保 newrelic.so 已被正确编译加载，否则探针无法启动。
1、执行 php -i | grep "Thread Safety"，确认输出为 disabled；
2、运行 php -v 验证 PHP 主版本在支持范围内；
立即学习“PHP免费学习笔记（深入）”；
3、执行 uname -m 检查系统架构是否为 x86_64 或 aarch64；
4、使用官方脚本安装扩展：curl -Ls https://download.newrelic.com/install/newrelic-php5.sh | bash -s -- -y -k YOUR_LICENSE_KEY；
5、确认 newrelic.ini 已写入 PHP 配置扫描目录（如 /etc/php/8.1/fpm/conf.d/），且其中包含 newrelic.license 和 newrelic.app_name；
6、重启 PHP-FPM 服务：systemctl restart php8.1-fpm；
7、验证扩展是否启用：php -m | grep newrelic 应返回 newrelic。
二、在 ThinkPHP 入口或中间件中手动命名事务
ThinkPHP 默认不被 New Relic 自动识别为标准框架，若不显式设置事务名，所有 HTTP 请求将统一显示为 OtherTransaction/PHP/，导致路由级性能数据不可见。必须在请求分发早期调用 newrelic_name_transaction()，确保事务与实际业务路径绑定。
1、打开 ThinkPHP 的全局中间件文件，例如 app/middleware.php 或新建自定义中间件类；
2、在 handle() 方法开头添加判断逻辑：if (extension_loaded('newrelic')) { newrelic_name_transaction($request->rule() ?: 'unknown'); }；
3、若使用 ThinkPHP 6.x 的多应用模式，需在每个应用的入口 app/{name}/middleware.php 中分别配置；
4、对于 API 路由，可进一步细化命名：newrelic_name_transaction('api/v1/users/index');；
5、保存后清除 ThinkPHP 运行缓存：php think clear。
三、启用 SQL 查询参数追踪与错误捕获增强
New Relic 默认对 SQL 查询参数进行脱敏处理，若需定位慢查询中的具体条件值，必须启用详细事务追踪；同时 ThinkPHP 的异常未被捕获时可能绕过 New Relic 错误上报机制，需主动注册异常处理器。
1、编辑 newrelic.ini，在对应段落中添加：newrelic.transaction_tracer.detail = 1；
2、重启 PHP-FPM 使配置生效；
3、在 ThinkPHP 的全局异常处理类（如 app/exception/Handle.php）中，在 report() 方法内插入：if (function_exists('newrelic_notice_error')) { newrelic_notice_error($exception->getMessage()); }；
4、确保 newrelic.capture_params = true 已在 newrelic.ini 中启用；
5、检查日志目录权限，确保 newrelic.log 可写，便于排查探针初始化失败原因。
四、验证探针是否上报有效事务数据
集成完成后，需通过真实请求触发数据上报，并在 New Relic UI 中确认事务名称、响应时间、数据库调用等指标是否正常显示，排除因配置覆盖或 SAPI 类型识别错误导致的数据缺失。
1、使用 curl 发起一次测试请求：curl -I http://your-domain.com/index.php?s=/index/index；
2、等待 2–3 分钟，登录 New Relic APM 页面，查看 Applications 列表中对应 app_name 是否出现绿色健康状态图标；
3、点击进入应用详情页，在 Transactions 标签页中搜索是否出现形如 WebTransaction/ThinkPHP/v1/users/index 的事务条目；
4、在 Databases 子页中确认是否有 PDO 查询记录及平均响应时间；
5、若仍显示 OtherTransaction/PHP/，检查 newrelic.ini 是否被其他 .ini 文件覆盖，或是否存在多个 PHP SAPI（CLI/FPM）加载了不同配置。
