README

Yii2 integration for Sentry using Sentry PHP SDK v3(.3.7).

Inspired by official sentry/sentry-simfony and sentry/sentry-laravel packages.

Installation

The preferred way to install this package is through composer:

composer require php-http/curl-client:^2.1
composer require http-interop/http-factory-guzzle:^1.0
composer require devnullius/yii2-sentry:^1.0

Basic Usage

Add "sentry" component to application's config and to bootstrapping, then configure log target as follows:

<?php

return [
    'id' => 'my-app',
    
    'bootstrap' => [
        'sentry',
        'log',
    ],
    
    'components' => [
        'sentry' => [
            'class' => devnullius\yii2\sentry\Component::class,
            'dsn' => 'https://abcdefghijklmnopqrstuvwxyz123456@sentry.io/0000000',
        ],
        
        'log' => [
            'targets' => [
                [
                    'class' => devnullius\yii2\sentry\LogTarget::class,
                    'levels' => ['error', 'warning'],
                    'except' => [
                        'yii\web\HttpException:40*',
                    ],
                ],
            ],
        ],
    ],
];

Don't forget to change DSN to your own.

After this all exceptions (except blacklisted), PHP errors and calls for Yii::error() and Yii:warning() will be logged to Sentry.

It is highly recommended blacklisting all Yii's exceptions for 40x responses, because they are used for handling requests and doesn't indicate about problems of any kind.

Out of the box component provides detailed information about request, such as:

Request Method
Request URL (including query string)
Request Headers
Request Body
Resolved route (goes to tags)
User ID for logged in
Visitor's IP address
Visitor's Cookies (with send default PII enabled)
App environment (taken from YII_ENV)
Stack trace for exception

The important nuance about LogTarget

Bundled in Log Target will send only one message to Sentry per request. This message will be based on the log entry with the highest severity level. All other entries will go to the extra field "logs" of message.

Advanced usage

Sentry client configuration

Component provides out-of-box configuration for Sentry client. It can be overridden and extend using Component::$sentrySettings property. Use options from Sentry PHP SDK as-is.

Also, Sentry's ClientBuilder is being created using Yii's container, which allows custom builder injection.

Personally identifying information (PII) handling

By default, Sentry provides PII handling on it's side, but it doesn't give full control over PII stripping process. Because of this, Yii2 Sentry package is able to strip PPI from both request headers and request body.

Example of component configuration with a complete list of PII-related settings:

<?php

[
    'class' => devnullius\yii2\sentry\Component::class,
    'dsn' => 'https://abcdefghijklmnopqrstuvwxyz123456:abcdefghijklmnopqrstuvwxyz123456@sentry.io/0000000',
    'integrations' => [
        [
            'class' => devnullius\yii2\sentry\Integration::class,
            // Headers that should not be send to Sentry at all
            'stripHeaders' => ['cookie', 'set-cookie'],
            // Headers which values should be filtered before sending to Sentry
            'piiHeaders' => ['custom-token-header', 'authorization'],
            // Body fields which values should be filtered before sending to Sentry
            'piiBodyFields' => [
                'controller/action' => [
                    'field_1' => [
                        'field_2',
                    ],
                    'field_2',
                ],
                'account/login' => [
                    'email',
                    'password',
                ],
            ],
            // Text to replace PII values with
            'piiReplaceText' => '[Filtered PII]',
        ],
        Sentry\Integration\ErrorListenerIntegration::class,
    ],
]

Improver

Aram Harutyunyan, e-mail: aram.ds@gmail.com

devnullius / yii2-sentry

Maintainers

Details