README

Yii Sentry

此包为 Yii 框架提供 Sentry 集成

安装

此包需要 PSR 兼容的 HTTP 客户端和工厂，因此需要额外安装此包

composer require httpsoft/http-message
composer require php-http/guzzle7-adapter
composer require webvork/yii-sentry

前两个可以替换为您选择的其它包。

处理控制台错误需要额外的 yii-console 和 yii-event 包

composer require yiisoft/yii-console
composer require yiisoft/yii-event

配置 HTTP 工厂和客户端（通常是 config/common/sentry.php）

<?php

declare(strict_types=1);

use GuzzleHttp\Client as GuzzleClient;
use Http\Adapter\Guzzle7\Client as GuzzleClientAdapter;
use Http\Client\HttpAsyncClient;
use Http\Client\HttpClient;
use HttpSoft\Message\RequestFactory;
use HttpSoft\Message\ResponseFactory;
use HttpSoft\Message\StreamFactory;
use HttpSoft\Message\UriFactory;
use Psr\Http\Message\RequestFactoryInterface;
use Psr\Http\Message\ResponseFactoryInterface;
use Psr\Http\Message\StreamFactoryInterface;
use Psr\Http\Message\UriFactoryInterface;
use Psr\Log\LoggerInterface;
use Psr\Log\NullLogger;
use Yiisoft\Definitions\Reference;

return [
    // HTTP Factories
    StreamFactoryInterface::class => StreamFactory::class,
    RequestFactoryInterface::class => RequestFactory::class,
    LoggerInterface::class => NullLogger::class,
    UriFactoryInterface::class => UriFactory::class,
    ResponseFactoryInterface::class => ResponseFactory::class,
    // HTTP Client
    HttpClient::class => GuzzleClient::class,
    HttpAsyncClient::class => [
        'class' => GuzzleClientAdapter::class,
        '__construct()' => [
            Reference::to(HttpClient::class),
        ],
    ],
];

如果您想跟踪 Guzzle 请求并添加 Sentry 标头到外部查询，请添加以下内容

GuzzleHttp\Client::class => static function (ContainerInterface $container) {
    $stack = new HandlerStack();
    $stack->setHandler(new CurlHandler());
    $factory = $container->get(GuzzleMiddlewareFactory::class);
    $middleware = static function (callable $handler) use ($factory): callable {
        return $factory->factory($handler);
    };

    $stack->push($middleware);

    return new GuzzleHttp\Client([
        'handler' => $stack,
    ]);
},

配置

将以下代码块添加到您的 params.php 并定义 DSN。您还可以设置 "环境" 和 "发布"。使用 gitlab.ci 的 TAG 作为例子是一个好主意。

'yiisoft/yii-sentry' => [
    'options' => [
        'dsn' => '',
        'environment' => 'local', //SENTRY_ENVIRONMENT, //YII_ENV,
        'release' => 'dev',  //SENTRY_RELEASE, //TAG
        // https://docs.sentry.io/platforms/php/configuration/options/#send-default-pii
        'send_default_pii' => true,
        'traces_sample_rate' => 1.0,
    ],
    'handleConsoleErrors' => true,
    'log_level' => 'warning',
    'tracing' => [
        // Indicates if the tracing integrations supplied by Sentry should be loaded
        'default_integrations'   => true,
        'guzzle_max_body' => 200,
    ],
]

将 APP_START_TIME 常量添加到 index.php 和 yii.php

define('APP_START_TIME', microtime(true));

将日志目标添加到 app/config/common/logger.php 或另一个具有日志设置的配置文件中，用于面包屑和跟踪

return [
    LoggerInterface::class => static function (
        /** your_another_log_target $your_log_target */
        \Yiisoft\Yii\Sentry\SentryBreadcrumbLogTarget $sentryLogTarget,
        Yiisoft\Yii\Sentry\Tracing\SentryTraceLogTarget $sentryTraceLogTarget
    ) {
        return new Logger([
        /** $your_log_target */
            $sentryLogTarget,
            $sentryTraceLogTarget
        ]);
    }
];

注意：如果您想在 Sentry 时间线中看到日志，您需要在日志上下文数组中使用键 (float)'time' 和 (float)'elapsed'。

将 DB 日志装饰器添加到 app/config/params.php 中以跟踪数据库查询（目前仅适用于 postgres，它将与其他数据库一起工作，但不能正确区分系统查询和用户查询）

'yiisoft/yii-cycle' => [
    // DBAL config
    'dbal' => [
        // SQL query logger. Definition of Psr\Log\LoggerInterface
        // For example, \Yiisoft\Yii\Cycle\Logger\StdoutQueryLogger::class
        'query-logger' => \Yiisoft\Yii\Sentry\PostgresLoggerDecorator::class,
        /**
         * ...
         * your another db settings 
         **/
    ]
]

将 SetRequestIpMiddleware 添加到 app/config/params.php 的 "middleware" 部分

    'middlewares' => [
        ErrorCatcher::class,
        \Yiisoft\Yii\Sentry\Http\SetRequestIpMiddleware::class, //add this
        Router::class,
    ],

将 SentryTraceMiddleware 添加到 app/config/common/router.php

  RouteCollectionInterface::class => static function (RouteCollectorInterface $collector) use ($config) {
        $collector
            ->middleware(FormatDataResponse::class)
            ->middleware(JsonParseMiddleware::class)
            ->middleware(ExceptionMiddleware::class)
            ->middleware(\Yiisoft\Yii\Sentry\Tracing\SentryTraceMiddleware::class) // add this
            ->addGroup(
                Group::create('')
                    ->routes(...$config->get('routes'))
            );

        return new RouteCollection($collector);
    },

如果您的交易太重，您可以通过清除日志缓冲区将其分割成几个交易。使用 SentryConsoleTransactionAdapter 或 SentryWebTransactionAdapter。例如

/** some code with default transaction */
/** commit default transaction and send data to sentry server */
$sentryTraceString = $this->sentryTransactionAdapter->commit();
while ($currentDate <= $endDate) {
    $this->sentryTransactionAdapter->begin($sentryTraceString)
        ->setName('my_heavy_operation/iteration')
        ->setData(['date' => $currentDate->format('Y-m-d')]);

    $this->process($currentDate, $sentryTraceString);
    $this->sentryTransactionAdapter->commit();
}

$this->sentryTransactionAdapter->begin($sentryTraceString)
    ->setName('my_heavy_operation done, terminating application');
/** transaction will commit when application is terminated */

在这个例子中，所有新的交易都将与具有 $sentryTraceString 的交易相关联。

在 options 中，您还可以传递额外的 Sentry 配置。有关键和值的详细信息，请参阅 官方 Sentry 文档。

单元测试

该包使用 PHPUnit 进行测试。要运行测试

./vendor/bin/phpunit

变异测试

该包的测试使用 Infection 变异框架进行检查。要运行它

./vendor/bin/infection

静态分析

代码使用 Psalm 进行静态分析。要运行静态分析

./vendor/bin/psalm