PHP error_log集成Sentry

PHP 的错误日志机制本身存在一个致命缺陷：它是被动且离散的。当你的应用抛出 Warning 或 Notice 时，error_log() 仅仅把一行文本写进服务器的某个文件里。这行文本很快就会被淹没在成百上千条日志中，除非你手动去 grep 或者等到用户投诉，否则你根本不知道线上正在发生什么。更糟糕的是，在微服务或多节点架构下，日志分散在不同容器里，排查一个问题可能需要登录好几台机器。把 PHP 的 error_log 直接集成到 Sentry，本质上就是把这种被动的、离散的文本流，变成结构化、上下文丰富且主动推送的异常追踪系统。你不需要重写代码去替换所有的 error_log，只需要一个自定义的错误处理器，把原生错误捕获并转换成 Sentry 能理解的异常对象，就能实现无缝升级。

理解 PHP 的错误体系是集成 Sentry 的前提。PHP 里有三个核心概念：错误（Error）、异常（Exception）和日志（Log）。错误是引擎层面的问题，比如除以零、调用未定义函数，这些会触发 E_WARNING 或 E_ERROR 级别。异常是面向对象的错误处理机制，用 try-catch 捕获。而 error_log 是过程式的日志记录函数，它不区分级别，只是简单地把字符串写入文件或 syslog。Sentry 的 PHP SDK 默认只捕获未被处理的异常（Unhandled Exception），对于原生错误和手动调用的 error_log 是视而不见的。所以集成的关键就在于，用 set_error_handler 把原生错误转换为 ErrorException 抛出，同时用一个自定义的 Sentry 集成器去接管 error_log 的调用，把它们作为 Sentry 的事件上报。

在开始写代码之前，先把 Sentry SDK 引入项目。假设你用的是 Composer 管理的现代 PHP 项目，执行 composer require sentry/sdk 即可，这会同时安装 sentry/sentry 和相关的 HTTP 客户端。初始化通常在项目的入口文件（比如 index.php 或 bootstrap.php）的最顶部完成，确保在发生任何错误之前 Sentry 就已经就位。

require_once __DIR__ . '/vendor/autoload.php';

\Sentry\init([
    'dsn' => 'https://examplePublicKey@o0.ingest.sentry.io/0',
    'environment' => 'production',
    'traces_sample_rate' => 0.5,
    'error_types' => E_ALL,
]);

这里的 dsn 从 Sentry 项目设置里获取，environment 用来区分开发、测试和生产环境，traces_sample_rate 控制性能追踪的采样率。error_types 设置为 E_ALL 是故意为之，目的是让 PHP 报告所有级别的错误，这样我们后续的自定义错误处理器才能完整捕获。初始化完成后，任何未捕获的异常都会自动上报 Sentry，但原生错误和 error_log 仍然需要额外处理。

PHP 的 set_error_handler 可以注册一个自定义函数来处理运行时错误。这个函数必须接收错误级别、消息、文件路径和行号四个参数。最佳实践是在这个处理器里抛出一个 ErrorException，然后让 Sentry 的异常处理机制去接管。注意，致命错误（E_ERROR）无法被 set_error_handler 捕获，需要用 register_shutdown_function 来兜底。

set_error_handler(function ($severity, $message, $file, $line) {
    if (!(error_reporting() & $severity)) {
        // 如果该错误级别被 error_reporting 屏蔽，则不处理
        return false;
    }
    throw new \ErrorException($message, 0, $severity, $file, $line);
});

这段代码把所有未被屏蔽的原生错误都转换成了异常。当 Sentry 初始化后，它会自动注册自己的异常处理器，捕获这些 ErrorException 并上报。这样一来，像 file_get_contents 失败触发的 E_WARNING，或者数组下标未定义触发的 E_NOTICE，都会变成 Sentry 里一条带有完整堆栈和上下文的事件。但这里有个细节需要注意：如果你在代码里用了 @ 错误抑制符，error_reporting() 会临时返回 0，此时上述代码会跳过该错误，保持 PHP 的默认行为，避免把被开发者主动忽略的警告也上报。

很多老旧项目或者快速开发的脚本里，开发者习惯用 error_log('something wrong') 来记录问题。这些调用不会触发 set_error_handler，因为它们不是错误，而是主动的日志记录。要让这些日志也进入 Sentry，需要利用 Sentry SDK 提供的 captureMessage 方法，并结合自定义的日志处理逻辑。最简单的方案是封装一个全局函数替换掉 error_log，但更优雅的做法是利用 PHP 的 error_log 支持自定义错误处理机制的特性，或者直接在 Sentry 初始化时配置 before_send 回调来过滤和增强事件。

不过，error_log 本身不支持直接重定向到第三方服务。一个务实的方案是写一个自定义的日志包装器，在项目中统一使用这个包装器代替原生的 error_log。这个包装器内部同时调用 Sentry 的 captureMessage 和原生的 error_log，保证既有本地文件备份，又有 Sentry 的实时告警。

function sentry_error_log($message, $level = 'error') {
    // 保留原生 error_log 行为，写入服务器日志文件
    error_log($message);
    
    // 上报到 Sentry
    \Sentry\withScope(function (\Sentry\State\Scope $scope) use ($message, $level) {
        $scope->setLevel($level === 'warning' ? \Sentry\Severity::warning() : \Sentry\Severity::error());
        $scope->setExtra('source', 'error_log_wrapper');
        \Sentry\captureMessage($message);
    });
}

这个包装器做了几件重要的事：它保留了原生 error_log 的调用，确保本地日志不丢失；它用 Sentry 的 captureMessage 上报消息，而不是抛出异常，因为日志本身可能只是记录一个状态，不应该中断程序执行；它通过 withScope 设置了日志级别和额外的上下文信息，方便在 Sentry 里区分这些事件是来自 error_log 还是真正的异常。如果你的项目里 error_log 调用散布在各处，可以用 IDE 的全局搜索替换功能，把 error_log( 替换成 sentry_error_log(，几分钟就能完成迁移。

PHP 的致命错误（E_ERROR、E_PARSE、E_CORE_ERROR 等）会导致脚本立即终止，set_error_handler 无法捕获它们。这时候需要 register_shutdown_function 在脚本结束前做最后的检查。通过 error_get_last 获取最后一个错误，判断其类型是否为致命级别，然后手动上报到 Sentry。

register_shutdown_function(function () {
    $lastError = error_get_last();
    if ($lastError && in_array($lastError['type'], [E_ERROR, E_PARSE, E_CORE_ERROR, E_COMPILE_ERROR], true)) {
        \Sentry\withScope(function (\Sentry\State\Scope $scope) use ($lastError) {
            $scope->setLevel(\Sentry\Severity::fatal());
            $scope->setExtra('shutdown', true);
            \Sentry\captureMessage(
                sprintf('Fatal Error: %s in %s:%d', $lastError['message'], $lastError['file'], $lastError['line'])
            );
        });
    }
});

这段代码在脚本终止时运行，检查最后一个错误是否为致命类型。如果是，就用 captureMessage 上报，并打上 fatal 级别和 shutdown 标记。注意这里没有抛出异常，因为脚本已经要结束了，抛出异常也没有意义。同时，Sentry SDK 内部也有类似的 shutdown 处理逻辑，但显式地加上这段代码可以确保在 SDK 初始化失败或配置有误的情况下，仍然有一个兜底的捕获机制。另外，E_PARSE 语法错误通常发生在脚本编译阶段，如果入口文件有语法错误，整个脚本根本不会执行，所以这种错误实际上无法在运行时捕获，需要依赖部署流程中的语法检查或者 Sentry 的 Release 集成来发现。

光有错误消息和堆栈还不够，Sentry 的强大之处在于它可以携带丰富的上下文。在错误发生时，当前请求的 URL、用户 ID、请求参数、服务器环境变量等信息，对于快速定位问题至关重要。Sentry SDK 默认会自动附加 HTTP 请求信息和用户 IP，但业务层面的上下文需要手动设置。最佳实践是在错误处理器或者 Sentry 的 before_send 回调里，把这些信息注入到事件的 extra 或 tags 字段中。

\Sentry\configureScope(function (\Sentry\State\Scope $scope) {
    // 设置用户信息，如果用户已登录
    if (isset($_SESSION['user_id'])) {
        $scope->setUser([
            'id' => $_SESSION['user_id'],
            'email' => $_SESSION['user_email'] ?? null,
        ]);
    }
    
    // 设置标签，用于在 Sentry 里快速筛选
    $scope->setTag('php_version', PHP_VERSION);
    $scope->setTag('module', 'payment');
    
    // 设置额外信息
    $scope->setExtra('request_body', file_get_contents('php://input'));
    $scope->setExtra('server_ip', $_SERVER['SERVER_ADDR'] ?? 'unknown');
});

标签（tags）和额外信息（extra）的区别在于，标签是索引字段，可以用来在 Sentry 界面里做筛选和聚合，而额外信息只是附加数据，不参与索引。合理使用标签可以让你快速定位某个模块、某个用户或某个 PHP 版本下的特定问题。注意，敏感信息（如密码、信用卡号）绝对不要放到 Sentry 里，可以在 before_send 回调里对请求体做脱敏处理，用正则替换掉敏感字段。

如果你的项目已经使用了 Monolog 作为日志库，那么集成 Sentry 会更加优雅。Monolog 有一个官方的 Sentry Handler，可以把特定级别的日志直接推送到 Sentry。这种方式比手动封装 error_log 更灵活，因为它支持日志级别过滤、批量处理和异步发送。配置也很简单，在 Monolog 的 Logger 实例上添加一个 SentryHandler 即可。

use Monolog\Logger;
use Monolog\Handler\SentryHandler;

$log = new Logger('app');
$log->pushHandler(new SentryHandler(
    \Sentry\SentrySdk::getCurrentHub(),
    Logger::WARNING // 只上报 WARNING 及以上级别的日志
));

// 现在用 Monolog 记录日志，WARNING 及以上会自动进入 Sentry
$log->error('Payment failed', ['order_id' => 12345]);
$log->debug('This will not be sent to Sentry');

这种方案的好处是，你可以继续使用 Monolog 的所有功能，比如不同的 Handler 写入文件、发送邮件、推送 Slack 等，同时把 WARNING 和 ERROR 级别的日志同步到 Sentry。而且 Monolog 的日志记录本身就包含上下文数组，这些数据会原样出现在 Sentry 事件的 extra 字段里。如果你的项目已经在用 Laravel 或 Symfony 等框架，它们底层就是 Monolog，只需要在配置文件中添加一个 Sentry 的 Handler 就能完成集成，无需修改任何业务代码。

在生产环境中，如果错误发生频率很高，或者你的应用流量巨大，每条 error_log 都上报 Sentry 可能会产生不小的性能开销和事件配额消耗。Sentry SDK 提供了采样率配置，但那是针对性能追踪的，对于错误事件，默认是全量上报。你可以在 before_send 回调里实现自定义的采样逻辑，比如对某些频繁发生的低级别错误做降频处理。

\Sentry\init([
    'dsn' => '...',
    'before_send' => function (\Sentry\Event $event) {
        // 如果是 Notice 级别的错误，且消息包含特定模式，随机丢弃 90%
        if ($event->getLevel() === \Sentry\Severity::info()) {
            $message = $event->getMessage();
            if (strpos($message, 'Undefined index') !== false && mt_rand(1, 100) > 10) {
                return null; // 返回 null 表示不上报
            }
        }
        return $event;
    },
]);

这段代码对 Undefined index 这类常见的 Notice 做了 90% 的丢弃。注意，这不是最佳实践，理想情况下你应该在代码里修复这些 Notice，而不是在 Sentry 层面过滤它们。但在遗留系统里，修复所有 Notice 可能需要大量时间，这种采样策略可以作为过渡方案。另外，Sentry 本身也有速率限制，如果你的应用短时间内产生大量相同错误，Sentry 服务端会自动合并和限流，不会无限量计费。

在本地开发时，你通常不希望把错误上报到 Sentry 的生产项目里，这会造成数据污染和配额浪费。Sentry SDK 支持通过 environment 配置来区分环境，你可以在开发环境中把 DSN 设置为 null 或者一个专门的开发项目。更简单的做法是，在 .env 文件里配置 SENTRY_DSN，开发环境留空，这样 SDK 初始化后实际上不会发送任何数据。同时，你可以利用 Sentry 的本地开发服务器或者直接查看日志文件来调试。

// 开发环境示例：根据环境变量决定是否初始化 Sentry
$sentryDsn = getenv('SENTRY_DSN');
if ($sentryDsn) {
    \Sentry\init(['dsn' => $sentryDsn, 'environment' => 'production']);
} else {
    // 开发环境：只记录到本地文件，不上报
    ini_set('log_errors', 1);
    ini_set('error_log', __DIR__ . '/../logs/php_errors.log');
}

这种条件初始化的方式让同一套代码在不同环境有不同行为，既保证了生产环境的监控能力，又避免了开发时的干扰。同时，开发环境仍然保留了本地错误日志，方便开发者即时看到错误信息。你还可以在开发环境里使用 Sentry 的 captureMessage 但不发送，而是用 var_dump 输出到屏幕，不过这需要自己实现一个简单的 mock 客户端。

现代 PHP 框架如 Laravel、Symfony 都有官方的 Sentry 集成包，它们已经处理好了上述大部分细节。以 Laravel 为例，安装 sentry/sentry-laravel 后，框架会自动注册错误处理器、配置 Monolog Handler，并且把请求上下文、用户信息、队列任务等数据自动附加到 Sentry 事件里。你甚至不需要手动调用任何 Sentry 方法，Laravel 的 Log Facade 在记录 error 级别日志时就会自动上报。但理解底层的原理仍然重要，因为当集成出现问题，或者你需要定制某些行为时，知道 set_error_handler 和 Monolog Handler 的工作方式能让你快速定位问题。

对于没有官方集成包的框架或自研框架，你可以参照上述步骤手动集成。核心流程不变：入口初始化 Sentry、注册错误处理器、注册 shutdown 函数、配置上下文信息。把这些逻辑封装成一个服务提供者或者中间件，就能实现与框架生命周期的无缝对接。

把 PHP 的 error_log 集成到 Sentry，本质上不是简单的日志转发，而是把离散的文本记录升级为结构化的事件追踪系统。通过 set_error_handler 捕获原生错误，通过自定义包装器接管 error_log 调用，再配合 Monolog 的 SentryHandler 实现灵活的日志级别过滤，你可以在不大量修改业务代码的前提下，获得完整的错误监控能力。加上合理的上下文配置和采样策略，这套方案既能保证问题发现的速度，又能控制成本和噪音。