README

CakePHP 对 Sentry 的集成。

需求

PHP 7.2+ / PHP 8.0+
CakePHP 4.0+
以及 Sentry 账户

💡 对于 CakePHP3.x，请使用 2.x 分支。

安装

使用 composer 安装。

composer require connehito/cake-sentry:^3.0

如果您没有安装 php-http/async-client-implementation 包，则需要一起安装。
在这种情况下，您将收到如下消息

Problem 1
- sentry/sentry[3.2.0, ... , 3.3.0] require php-http/async-client-implementation ^1.0 -> could not be found in any version, but the following packages provide it:

然后，您可以使用以下命令提供类似 symfony/http-client 的包。

composer require connehito/cake-sentry symfony/http-client

您可以在 Packagist 上找到可用的包。

使用方法

设置配置文件。

写入您的 Sentry 账户信息。

// in `config/app.php`
return [
  'Sentry' => [
    'dsn' => YOUR_SENTRY_DSN_HERE
  ]
];

加载插件。

在 Application.php 中

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

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

或使用 cake 命令。

bin/cake plugin load Connehito/CakeSentry

这就完了！🎉

注意
如果事件（错误/异常）没有被 Sentry 捕获，请尝试更改插件加载的顺序。
建议在运行 BaseApplication::bootstrap() 和加载其他插件之后加载此插件。

高级使用

忽略嘈杂的异常

您可以过滤掉那些引起骚动且难以确定要解决的问题的异常（如 PageNotFoundException）
在 Error.skipLog 中设置异常不记录。

示例）

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

参考：CakePHP 烹饪书
https://book.cakephp.com.cn/4/en/development/errors.html#error-exception-configuration

设置选项

所有写入 Configure::write('Sentry') 的配置都会传递给 Sentry\init()。
请参阅 Sentry 的官方文档有关配置和有关 php-sdk 的配置。

除此之外，CakeSentry 还提供了事件钩子，以便更容易地设置选项的动态值。
在将错误发送到 Sentry 之前，客户端会触发 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 Client $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());

发送更多上下文

在将错误发送到 Sentry 之前，客户端会触发 CakeSentry.Client.beforeCapture 事件。
您可以使用 EventListener 与 facade sentryConfigureScope() 等，或使用 $event->getContext()->getHub() 来访问和设置上下文。
如果您想要处理服务器请求中的信息，cake-sentry 支持通过 $event->getData('request') 在实现的事件中获取 Request 实例。

请参阅官方文档中的上下文部分。

示例）

use Cake\Event\Event;
use Cake\Event\EventListenerInterface;
use Cake\Http\ServerRequest;
use Cake\Http\ServerRequestFactory;
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') {
            /** @var ServerRequest $request */
            $request = $event->getData('request') ?? ServerRequestFactory::fromGlobals();
            $request->trustProxy = true;

            sentryConfigureScope(function (Scope $scope) use ($request, $event) {
                $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 事件中，您可以获取最后一个事件 ID。
请参阅官方文档。

示例）

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

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

贡献

非常欢迎 Pull requests 和反馈 :)
在 GitHub 上 https://github.com/connehito/cake-sentry .

许可证

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

connehito / cake-sentry

维护者

详细信息