README

Yii Sentry

The package provides Sentry integration for Yii Framework

Installation

The package needs PSR-compatible HTTP client and factories so require it additionally to this package:

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

The first two can be replaced to other packages of your choice.

For handling console errors yii-console and yii-event packages are required additionally:

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

Configure HTTP factories and client (usually that is 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),
        ],
    ],
];

If you want to trace Guzzle requests and add Sentry headers to external queries, add the following:

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,
    ]);
},

Configure:

Add the following code block to your params.php and define DSN. Also you can set "environment" and "release". Good example is to use TAG from gitlab.ci for it.

'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,
    ],
]

Add APP_START_TIME constant into index.php and yii.php:

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

Add log targets for breadcrumbs and tracing to app/config/common/logger.php or another config file with logger settings:

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
        ]);
    }
];

Note: If you want to see your logs in sentry timeline, you need to use keys (float)'time' and (float)'elapsed' in log context array.

Add DB log decorator for tracing db queries in app/config/params.php: (now it is available only for postgres, it will work with another db, but can't separate system queries from user queries correctly)

'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 
         **/
    ]
]

Add SetRequestIpMiddleware to app/config/params.php, "middleware" section:

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

Add SentryTraceMiddleware to 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);
    },

If your transaction is too heavy, you can slice it to several transactions with clearing log buffer. Use SentryConsoleTransactionAdapter or SentryWebTransactionAdapter. For example:

/** 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 */

In this example all new transactions will linked to transaction with $sentryTraceString.

In options you can also pass additional Sentry configuration. See official Sentry docs for keys and values.

Unit testing

The package is tested with PHPUnit. To run tests:

./vendor/bin/phpunit

Mutation testing

The package tests are checked with Infection mutation framework. To run it:

./vendor/bin/infection

Static analysis

The code is statically analyzed with Psalm. To run static analysis:

./vendor/bin/psalm