DOCSEARCHbyAlgolia
Submit Docs

Sentry Symfony SDK

repository·master·Indexed 20 days ago

https://github.com/getsentry/sentry-symfony

The official Sentry SDK for Symfony provides error tracking and performance monitoring. It includes a specialized Monolog handler via Sentry\SentryBundle\Monolog\LogsHandler, a test command (sentry:test) for configuration verification, and support for manual exception reporting using captureException(). The SDK integrates with Symfony's service architecture and provides configuration options for excluded exceptions and PII handling.

Tokens
1.5K
Snippets
7
Records
9
Agent score
73%

What's inside sentry-symfony

  1. Understand service changes and event handling in 3.x

    master

    The bundle's service architecture has been updated to follow Symfony best practices:

    • Private Services: All services are now private. Use public aliases if you need to access them directly. Alternatively, use Sentry SDK global functions for manual message capture.
    • Listener Changes: The ExceptionListener is replaced by ErrorListener, RequestListener, SubRequestListener, and ConsoleListener. These listeners are final; to override behavior, you must append your own listeners.
    • Listener Priority: Listeners are registered with a priority of 1, allowing custom listeners with priority 0 to run after them and modify the Scope.
    • Dropped Events: SentrySymfonyEvents::PRE_CAPTURE and SentrySymfonyEvents::SET_USER_CONTEXT have been removed. To inject data into events, implement a custom listener (similar to RequestListener) that interacts with the Hub and Scope.

  2. Migrate Sentry configuration from 2.x to 3.x

    master

    When upgrading to version 3.0, several configuration keys have changed to align with the underlying Sentry PHP SDK 2.0:

    • Excluding Exceptions: The skip_capture option has been removed. Move your values to sentry.options.excluded_exceptions. This option works with instanceof checks against exception classes.
    • Default Exceptions: Symfony internal exceptions (like 404 or 403) are no longer ignored by default. To ignore them, add them to sentry.options.excluded_exceptions.
    • PII (Personally Identifiable Information): For GDPR compliance, send_default_pii is now false by default. To include the user's username and IP address in events (matching 2.x behavior), set sentry.options.send_default_pii: true.
    • DSN: The sentry.dsn key remains the way to configure the DSN, even though the underlying SDK uses server to dsn mapping.
    sentry:
    options:
        excluded_exceptions: ['Symfony\Component\HttpKernel\Exception\NotFoundHttpException']
        send_default_pii: true
    dsn: 'YOUR_DSN'

  4. Install HTTP client implementations for Sentry 3.x

    master

    Sentry SDK 2.0 (used in this bundle) is transport-agnostic and requires an implementation of php-http/async-client-implementation and http-message-implementation.

    While the sentry/sdk metapackage handles this by requiring Curl and Guzzle's message factories, you can manually require specific implementations if you prefer a different client. For example, to use Guzzle 6 components, run:

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

  5. Configure the Sentry DSN

    master

    To enable error reporting, add your Sentry DSN (Data Source Name) to your project's .env file using the SENTRY_DSN environment variable.

    ###> sentry/sentry-symfony ###
SENTRY_DSN="https://public@sentry.example.com/1"
###< sentry/sentry-symfony ###

  6. Capture exceptions manually with captureException()

    master

    You can manually report exceptions to Sentry by using the Sentry\captureException function within a try-catch block.

    use function Sentry\captureException;

try {
    $this->functionThatMayFail();
} catch (\Throwable $exception) {
    captureException($exception);
}

  7. Reference the core Sentry 3.x services

    master

    The following services are registered by the bundle and are used to interact with the SDK:

    • Sentry\State\HubInterface: The central root of the SDK. The bundle instantiates this at startup.
    • Sentry\ClientInterface: The primary client for the SDK. It is bound to the Hub.
    • Sentry\ClientBuilderInterface: A factory used to build customized clients by configuring settings and dependencies.
    • Sentry\Options: Holds the configuration used by the client and other SDK components, populated from the bundle configuration.

  8. Use LogsHandler for Monolog integration

    master

    The Sentry\SentryBundle\Monolog\LogsHandler class is a specialized Monolog handler designed to send logs to Sentry. It extends the base Sentry\Monolog\LogsHandler to provide better compatibility with Symfony configuration (YAML/XML) by allowing the use of Monolog constants or PSR log levels instead of Sentry-specific log level objects.

    Constructor Parameters

    • $level: The minimum logging level that will trigger a Sentry event. It accepts int, string, Monolog\Level (for Monolog 3+), or Psr\Log\LogLevel constants. If an invalid level is provided, it defaults to MonologLogger::INFO.
    • $bubble: A boolean indicating whether the event should bubble up to the next handler in the Monolog stack. Defaults to true.
    // Example of how this might be configured in a Symfony service definition (YAML)
// Sentry\SentryBundle\Monolog\LogsHandler:
//     arguments:
//         $level: 'info'
//         $bubble: true

  9. Test the Sentry integration with sentry:test

    master

    Use the sentry:test command to verify that your Sentry SDK is correctly configured and able to send messages to Sentry. The command checks if a Sentry client exists, if a DSN is configured, and attempts to send a test message.

    If the command fails, it provides specific guidance:

    • No client found: Your DSN is likely missing from your configuration.
    • No DSN configured: Check your configuration using bin/console debug:config sentry.
    • Message not sent: Check your DSN or any before_send callbacks you may have implemented.
    php bin/console sentry:test