README

CakePHP 集成 Sentry。

要求

PHP 7.2+
CakePHP 4.0+
以及 Sentry 账户

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

安装

使用 composer install。

composer require connehito/cake-sentry:^3.0

使用方法

设置配置文件。

写入您的 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 和门面 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');
    }
}

贡献

非常欢迎拉取请求和反馈 :)
在 GitHub 上 https://github.com/connehito/cake-sentry .

许可证

该插件以开源方式提供，符合 MIT 许可证的条款。

androideo / cake-sentry

维护者

详细信息