README

CakePHP 集成 Sentry。

ℹ️ 这是基于 https://github.com/Connehito/cake-sentry 重构的版本，以去除 CakePHP 4.4 中引入的弃用警告

ℹ️ 如果你正在使用 CakePHP 4.4+，请使用此插件的 1.x 版本

ℹ️ 如果你正在使用 CakePHP 3.x 或 4.0 - 4.3，请使用上文提到的 Connehito 插件

要求

• PHP 8.1+
• CakePHP 5+
• 以及一个 Sentry 账户
  • 如果你使用自托管的 Sentry，确保你的版本至少是 >= v20.6.0

版本表

安装

composer require lordsimal/cakephp-sentry

用法

设置配置文件

// in `config/app.php`
return [
    'Sentry' => [
        'dsn' => '<sentry-dsn-url>',
        'environment' => 'production',
    ]
];

加载插件

在 Application.php 中

public function bootstrap()
{
    parent::bootstrap();

    $this->addPlugin(\CakeSentry\CakeSentryPlugin::class);
}

或者使用 cake CLI。

bin/cake plugin load CakeSentry

这就完了！ 🎉

⚠️️ 如果事件（错误/异常）没有被 Sentry 捕获，请尝试更改插件的加载顺序。

高级用法

忽略特定异常

你可以过滤掉那些不需要进一步调试的嘈杂异常。

// in `config/app.php`
'Error' => [
    'skipLog' => [
        NotFoundException::class,
        MissingRouteException::class,
        MissingControllerException::class,
    ],
]

也请参阅 CakePHP 烹饪书

设置选项

所有在 'Sentry' 配置键内的内容都将传递给 \Sentry\init()。请查阅 Sentry 的官方文档关于 配置 和 php-sdk 的配置。

CakeSentry 还提供了自定义事件钩子来设置动态值。

例如 CakeSentry.Client.afterSetup

use Cake\Event\Event;
use Cake\Event\EventListenerInterface;

class SentryOptionsContext implements EventListenerInterface
{
    public function implementedEvents(): array
    {
        return [
            'CakeSentry.Client.afterSetup' => 'setServerContext',
        ];
    }

    public function setServerContext(Event $event): void
    {
        /** @var \CakeSentry\Http\SentryClient $subject */
        $subject = $event->getSubject();
        $options = $subject->getHub()->getClient()->getOptions();

        $options->setEnvironment('test_app');
        $options->setRelease('3.0.0@dev');
    }
}

在 config/bootstrap.php 中

\Cake\Event\EventManager::instance()->on(new SentryOptionsContext());

例如 CakeSentry.Client.beforeCapture

use Cake\Event\Event;
use Cake\Event\EventListenerInterface;
use Sentry\State\Scope;

use function Sentry\configureScope as sentryConfigureScope;

class SentryErrorContext implements EventListenerInterface
{
    public function implementedEvents(): array
    {
        return [
            'CakeSentry.Client.beforeCapture' => 'setContext',
        ];
    }

    public function setContext(Event $event): void
    {
        if (PHP_SAPI !== 'cli') {
            sentryConfigureScope(function (Scope $scope) use ($event) {
                $request = \Cake\Routing\Router::getRequest();
                $scope->setTag('app_version',  $request->getHeaderLine('App-Version') ?: 1.0);
                $exception = $event->getData('exception');
                if ($exception) {
                    assert($exception instanceof \Exception);
                    $scope->setTag('status', $exception->getCode());
                }
                $scope->setUser(['ip_address' => $request->clientIp()]);
                $scope->setExtras([
                    'foo' => 'bar',
                    'request attributes' => $request->getAttributes(),
                ]);
            });
        }
    }
}

在 config/bootstrap.php 中

\Cake\Event\EventManager::instance()->on(new SentryErrorContext());

例如 CakeSentry.Client.afterCapture

use Cake\Event\Event;

class SentryErrorContext implements EventListenerInterface
{
    public function implementedEvents(): array
    {
        return [
            'CakeSentry.Client.afterCapture' => 'callbackAfterCapture',
        ];
    }

    public function callbackAfterCapture(Event $event): void
    {
        $lastEventId = $event->getData('lastEventId');
    }
}

查询日志（可选）

如果你想使 Sentry 事件也启用查询日志，可以通过你的配置来实现

'CakeSentry' => [
    'enableQueryLogging' => true
]

如果你想在事件中包含与模式反射相关的查询，可以通过以下方式启用

'CakeSentry' => [
    'includeSchemaReflection' => true
]

性能监控（可选）

如果你想使用 Sentry 的性能监控功能，你必须启用这两个设置

'CakeSentry' => [
    'enableQueryLogging' => true,
    'enablePerformanceMonitoring' => true
]

以及设置相应的 Sentry SDK 选项

'Sentry' => [
    'dsn' => '<sentry-dsn-url>',
    'traces_sample_rate' => 1,
]

为了在 Sentry 的性能监控部分查看 SQL 查询执行和持续时间，请确保为所需的数据库启用日志记录，如下所示

'Datasources' => [
    'default' => [
        'sentryLog' => true
    ]
]

从 2 版本升级到 3 版本

从 2.0 到 3.0 之间有几个主要变化

• Sentry PHP SDK 已从 ^3.3 升级到 ^4.0
• CakeSentryMiddleware 已重命名为 CakeSentryQueryMiddleware
• 属性不再以前缀 _ 开头
• 已添加 CakeSentryPerformanceMiddleware 以支持 性能监控功能

许可证

该插件作为开源软件，根据 MIT 许可证 的条款提供。