Sentry Symfony Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require sentry/sentry-symfony
   

   Add to config/packages/sentry.yaml (auto-generated on first run):

   sentry:
       dsn: 'https://<key>@<project>.ingest.sentry.io/<project_id>'
       options:
           traces_sample_rate: 1.0
   

2. First Use Case:

   • Exception Handling: No extra code needed—it auto-captures unhandled exceptions in Symfony’s kernel.
   • Manual Events: Trigger a test event in a controller:

     use Sentry\SentrySdk;
     
     public function testSentry()
     {
         SentrySdk::captureMessage('This is a test event');
         return new Response('Event sent!');
     }
     

3. Where to Look First:

   • Symfony Integration Docs
   • config/packages/sentry.yaml (auto-generated config)
   • src/Sentry/ExceptionListener.php (kernel exception listener)

Implementation Patterns

Core Workflows

1. Exception Handling:

   • Auto-captures exceptions thrown in controllers, services, or middleware.
   • Extend default behavior by overriding the ExceptionListener:

     // config/services.yaml
     Sentry\Symfony\ExceptionListener:
         tags: [kernel.event_listener]
         arguments:
             $level: 'error' // Override default 'critical'
     

2. Manual Event Capture:

   • Errors: SentrySdk::captureException($exception)
   • Messages: SentrySdk::captureMessage('User logged in', ['user_id' => 123])
   • Transactions: Wrap business logic in a transaction:

     SentrySdk::startTransaction('checkout.process_payment', 'checkout');
     try {
         // Payment logic
     } finally {
         SentrySdk::finishTransaction();
     }
     

3. Middleware Integration:

   • Attach context (e.g., user ID) to all events:

     use Sentry\State\Scope;
     
     public function onKernelRequest(RequestEvent $event)
     {
         $scope = SentrySdk::getScope();
         $scope->setUser(['id' => $event->getRequest()->get('user_id')]);
     }
     

4. Performance Monitoring:

   • Auto-instruments Symfony’s HTTP layer for traces.
   • Manually instrument long-running tasks:

     SentrySdk::startSpan('slow_operation', ['op' => 'database_query']);
     // ... execute query ...
     SentrySdk::finishSpan();
     

Integration Tips

• Laravel Bridge: Use sentry-laravel/sentry alongside this package for Laravel-specific features (e.g., Eloquent models).
• Environment-Specific DSN: Load DSN from .env:

  # config/packages/sentry.yaml
  sentry:
      dsn: '%env(SENTRY_DSN)%'
  

• Debug Mode: Disable in config/packages/sentry.yaml:

  sentry:
      options:
          debug: false
  

Gotchas and Tips

Pitfalls

1. DSN Leaks:

   • Never commit config/packages/sentry.yaml to version control if it contains a real DSN.
   • Use .env or environment variables for production DSNs.

2. Performance Overhead:

   • Disable in development/staging:

     # config/packages/sentry.yaml
     sentry:
         enabled: '%kernel.debug% ? false : true%' # Disable in debug mode
     

   • Reduce traces_sample_rate in production to avoid high cardinality.

3. Context Overwriting:

   • Be cautious with SentrySdk::configureScope()—it replaces the entire scope. Use SentrySdk::getScope()->setTag() for incremental updates.

4. Symfony Cache Warmup:

   • If using cache, clear it after changing sentry.yaml:

     php bin/console cache:clear
     

Debugging

1. Local Testing:

   • Use SentrySdk::captureException() with a dummy exception to verify setup:

     throw new \RuntimeException('Test exception');
     

   • Check Sentry’s "Issues" tab for the event.

2. Logging:

   • Enable debug logs in config/packages/sentry.yaml:

     sentry:
         options:
             debug: true
     

   • Check Symfony’s var/log/dev.log for Sentry-related entries.

3. Common Errors:

   • "DSN Invalid": Verify the DSN format and ensure it’s not URL-encoded.
   • Events Not Appearing: Check enabled: true in config and network/firewall rules.
   • Duplicate Events: Ensure SentrySdk::init() is called only once (handled automatically in Symfony).

Extension Points

1. Custom Event Processors:

   • Filter or modify events before sending:

     use Sentry\Event\EventInterface;
     use Sentry\EventProcessorInterface;
     
     class CustomProcessor implements EventProcessorInterface
     {
         public function __invoke(EventInterface $event): EventInterface
         {
             if ($event->getLevel() === 'debug') {
                 return null; // Drop debug events
             }
             return $event;
         }
     }
     

     Register in config/services.yaml:

     Sentry\Symfony\EventProcessor:
         arguments:
             $processors: ['@custom_processor']
     

2. Breadcrumbs:

   • Add manual breadcrumbs for debugging:

     SentrySdk::addBreadcrumb([
         'category' => 'navigation',
         'message' => 'User clicked "Submit"',
         'level' => 'info',
     ]);
     

3. Release Tracking:

   • Auto-set release version via Git tag:

     sentry:
         options:
             release: '%env(APP_VERSION)%'
     

   • Or manually:

     SentrySdk::setRelease('my-app@1.0.0');
     

4. Ignoring Exceptions:

   • Skip specific exceptions (e.g., HttpException):

     sentry:
         options:
             ignore_exceptions: [Symfony\Component\HttpKernel\Exception\HttpException]