sentry-symfony

Symfony integration for Sentry.

Benefits

Use sentry-symfony for:

A fast sentry setup
Easy configuration in your Symfony app
Automatic wiring in your app. Each event has the following things added automatically to it:
- user
- Symfony environment
- app path
- excluded paths (cache and vendor)

Installation

Step 1: Download the Bundle

You can install this bundle using Composer:

composer require sentry/sentry-symfony:^3.0

Optional: use custom HTTP factory/transport

Note: this step is optional

Since SDK 2.0 uses HTTPlug to remain transport-agnostic, you need to have installed two packages that provides php-http/async-client-implementation and http-message-implementation.

This bundle depends on sentry/sdk, which is a metapackage that already solves this need, requiring our suggested HTTP packages: the Curl client and Guzzle's message factories.

If instead you want to use a different HTTP client or message factory, you'll need to require manually those additional packages:

composer require sentry/sentry-symfony:^3.0 sentry/sentry:^2.0 php-http/guzzle6-adapter guzzlehttp/psr7

The sentry/sentry package is required directly to override sentry/sdk, and the other two packages are up to your choice; in the current example, we're using both Guzzle's components (client and message factory).

TODO: Flex recipe

Step 2: Enable the Bundle

Then, enable the bundle by adding it to the list of registered bundles in the app/AppKernel.php file of your project:

<?php
// app/AppKernel.php

// ...
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = [
            // ...
            new Sentry\SentryBundle\SentryBundle(),
        ];

        // ...
    }

    // ...
}

Note that, unlike before in version 3, the bundle will be enabled in all environments; event reporting, instead, is enabled only when providing a DSN (see the next step).

Step 3: Configure the SDK

Add your Sentry DSN value of your project to app/config/config_prod.yml. Leaving this value empty (or undeclared) in other environments will effectively disable Sentry reporting.

sentry:
    dsn: "https://public:secret@sentry.example.com/1"
    options:
        environment: '%kernel.environment%'
        release: '%env(VERSION)%' #your app version
        excluded_exceptions: #exclude validation errors
            - App\Exception\UserNotFoundException
            - Symfony\Component\Security\Core\Exception\AccessDeniedException

The parameter options allows to fine-tune exceptions. To discover more options, please refer to the Unified APIs options and the PHP specific ones.

Optional: use monolog handler provided by `sentry/sentry` (available since 3.2.0)

Note: this step is optional

If you're using monolog for logging e.g. in-app errors, you can use this handler in order for them to show up in Sentry.

First, enable & configure the Sentry\Monolog\Handler; you'll also need to disable the Sentry\SentryBundle\EventListener\ErrorListener to avoid having duplicate events in Sentry:

sentry:
    register_error_listener: false # Disables the ErrorListener
    monolog:
        error_handler:
            enabled: true
            level: error

Then enable it in monolog config:

monolog:
    handlers:
        sentry:
            type: service
            id: Sentry\Monolog\Handler

Additionally, you can register the PsrLogMessageProcessor to resolve PSR-3 placeholders in reported messages:

services:
    Monolog\Processor\PsrLogMessageProcessor:
        tags: { name: monolog.processor, handler: sentry }

Maintained versions

3.x is actively maintained and developed on the master branch, and uses Sentry SDK 2.0;
2.x is supported only for fixes; from this version onwards it requires Symfony 3+ and PHP 7.1+;
1.x is no longer maintained; you can use it for Symfony < 2.8 and PHP 5.6/7.0;
0.8.x is no longer maintained.

Upgrading to 3.0

The 3.0 version of the bundle uses the newest version (2.x) of the underlying Sentry SDK. If you need to migrate from previous versions, please check the UPGRADE-3.0.md document.

Customization

The Sentry 2.0 SDK uses the Unified API, hence it uses the concept of Scopes to hold information about the current state of the app, and attach it to any event that is reported. This bundle has three listeners (RequestListener, SubRequestListener and ConsoleListener) that adds some easy default information.

Those listeners normally are executed with a priority of 1 to allow easier customization with custom listener, that by default run with a lower priority of 0.

Those listeners are final so not extendable, but you can look at those to know how to add more information to the current Scope and enrich you Sentry events.

Services configuration

Services registered by the bundle (the ClientBuilder in the example below) can be configured in several ways, one of them is by using a compiler pass:

final class SentryCustomizationCompilerPass implements CompilerPassInterface
{
    public function process(ContainerBuilder $containerBuilder): void
    {
        // Example - setting own serializer to Sentry\ClientBuilder
        $containerBuilder->getDefinition(ClientBuilderInterface::class)
            ->addMethodCall('setSerializer', [
                new Reference(MyCustomSerializer::class),
            ]);
    }
}

lushc/sentry-symfony