README

Sentry Logger for Craft CMS

Pushes Craft CMS logs to Sentry through a real Yii 2 log target.

Features

Updated to the latest and official Sentry SDK
Native Yii 2 log target that is fully customisable
All errors and warnings for each request are sent
Plugin settings can be defined in the CP or with a config file
Options passed when Sentry SDK initializes can be customized
Calls for Craft::error() and Craft::warning() are sent and categorized
Anonymous option to prevent sensitive visitors and users data from being sent to Sentry

Additional data pushed to Sentry

Request type (web, ajax or console)
Request method, headers and body
Request route including query string
Script executed including parameters (console request)
User ID, email, username and groups (sensitive data)
Visitor IP address (sensitive data)
Visitor cookies (sensitive data)
Database driver type and version
Image driver type and version
Craft edition, licence, schema and version
Craft devMode status taken from general config
Craft current environment taken from CRAFT_ENVIRONMENT
Twig template path and line number for exceptions in compiled templates

Requirements

This plugin requires PHP 8.2 or later and Craft CMS 5.0 or later.

Installation

To install this plugin, search for Sentry Logger on the Craft Plugin Store and click Install or run the following terminal commands in your Craft project folder to install it with Composer:

composer require diginov/craft-sentry-logger
php craft plugin/install sentry-logger

Basic configuration

You can configure the plugin settings directly in the CP or you can create a config/sentry-logger.php config file with the following contents. Make sure to update your .env environment file accordingly with the correct values.

<?php

use craft\helpers\App;

return [

    '*' => [
        'enabled' => false,
        'anonymous' => false,
        'dsn' => App::env('SENTRY_DSN'),
        'release' => App::env('SENTRY_RELEASE'),
        'environment' => App::env('SENTRY_ENVIRONMENT'),
        'levels' => ['error', 'warning'],
        'exceptCodes' => [403, 404],
        'exceptPatterns' => [],
    ],

    'staging' => [
        'enabled' => true,
    ],

    'production' => [
        'enabled' => true,
    ],

];

Advanced configuration

This is a better method because it adds this Sentry log target to the existing log component before loading any Craft plugins or modules. This way you are assured that all logs are sent to Sentry.

Please note that this method override the basic configuration method.

To activate the advanced configuration, extend the log component in your existing config/app.php config file:

<?php

use craft\helpers\App;
use diginov\sentrylogger\log\SentryTarget;

return [

    'components' => [
        'log' => [
            'targets' => [
                'sentry' => function() {
                    if (!class_exists(SentryTarget::class)) {
                        return null;
                    }

                    return Craft::createObject([
                        'class' => SentryTarget::class,
                        'enabled' => App::env('CRAFT_ENVIRONMENT') !== 'dev',
                        'anonymous' => false,
                        'dsn' => App::env('SENTRY_DSN'),
                        'release' => App::env('SENTRY_RELEASE'),
                        'environment' => App::env('SENTRY_ENVIRONMENT'),
                        'levels' => ['error', 'warning'],
                        'exceptCodes' => [403, 404],
                        'exceptPatterns' => [],
                    ]);
                },
            ],
        ],
    ],

];

Configuration parameters

This plugin adds a native Yii 2 log target that is an instance of the yii\log\Target class. See the Yii 2 API Documentation for all available properties.

`enabled`

This required parameter is a boolean that indicates whether this log target is enabled.

`anonymous`

This optional parameter is a boolean that indicates, when enabled, that this log target will NOT send sensitive visitors and users data to Sentry.

`userPrivacy`

This optional parameter is an array of sensitive user data that will be sent to Sentry if the anonymous parameter is set to false. Available values are id, email, username, ip_address, cookies and permissions. Defaults to all sensitive user data.

`dsn`

This required parameter is a string that contain the Client Key (DSN) that Sentry gave you in your project settings.

`release`

This optional parameter is a string that contain the version of your application that is deployed to an environment. See more information about releases in Sentry documentation.

`environment`

This optional parameter is a string that contain the environment tag that designate where your application is deployed. Defaults to CRAFT_ENVIRONMENT. See more information about environment in Sentry documentation.

`options`

This optional parameter is an array of client options that will be passed to the Sentry SDK when it initializes. See more information about available options in Sentry documentation.

`levels`

This required parameter is an array of log level names that this log target is interested in. Defaults to error and warning. We have intentionally disabled reporting info, profile and debug log levels to Sentry because Craft generates a lot of messages for these log levels.

`categories`

This optional parameter is an array of message categories that this log target is interested in. Defaults to empty, meaning all categories. You can use an asterisk at the end of a category so that the category may be used to match those categories sharing the same common prefix. For example, yii\db* will match categories starting with yii\db\, such as yii\db\Connection.

`except`

This optional parameter is an array of message categories that this log target is NOT interested in. Defaults to empty, meaning no uninteresting categories. If this property is not empty, then any category listed here will be excluded from the categories parameter. You can use an asterisk at the end of a category so that the category can be used to match those categories sharing the same common prefix. For example, yii\db* will match categories starting with yii\db\, such as yii\db\Connection.

`exceptCodes`

This optional parameter is an array of HTTP status codes that this log target is NOT interested in. This is a shortcut for the except parameter to make it easier. Defaults to 403 and 404, meaning that yii\web\HttpException:403 and yii\web\HttpException:404 categories will be excluded from the categories parameter.

`exceptPatterns`

This optional parameter is an array of text search patterns that this log target is NOT interested in. Defaults to empty, meaning no uninteresting text search patterns. These text search patterns are matched on the text of an exception message, error or warning. This is useful for filtering out text messages sent without an exception code such as those sent by the Craft::error() and Craft::warning() methods.

Credits

Inspired by the olegtsvetkov/yii2-sentry package and by official sentry/sentry-symfony and sentry/sentry-laravel packages.

diginov / craft-sentry-logger

Maintainers

Details