Sentry Laravel Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require sentry/sentry-laravel
   

2. Configure DSN:

   php artisan sentry:publish --dsn=YOUR_DSN_HERE
   

   This auto-generates config/sentry.php and updates .env with SENTRY_LARAVEL_DSN.

3. Enable Exception Handling: Modify bootstrap/app.php to integrate Sentry:

   ->withExceptions(function (Exceptions $exceptions) {
       Integration::handles($exceptions);
   })
   

4. First Use Case: Capture an exception in a controller:

   use function Sentry\captureException;
   
   try {
       // Risky operation
   } catch (\Throwable $e) {
       captureException($e);
   }
   

Key First Steps

• Verify Sentry events appear in your dashboard.
• Check .env for SENTRY_LARAVEL_DSN and APP_ENV (should be local/production).
• Test with SENTRY_TRACES_SAMPLE_RATE=1.0 to ensure all traces are captured.

Implementation Patterns

Core Workflows

1. Exception Handling:

   • Automatic: Uncaught exceptions are auto-captured via Integration::handles().
   • Manual: Use captureException($e) or Sentry\captureMessage() for custom events.
   • Async: Wrap queue:work in Sentry\startTransaction() for job tracing.

2. Transaction Tracing:

   • HTTP Requests: Auto-instrumented via middleware. Override transaction name:

     Sentry\configureScope(function ($scope) {
         $scope->setTransaction('custom-transaction-name');
     });
     

   • Background Jobs: Use Sentry\startTransaction('job:name') in job handles.

3. Performance Monitoring:

   • Views: Auto-traced. Customize via Sentry\ViewEngineDecorator.
   • Database: Enable SQL instrumentation in config/sentry.php:

     'sql_bindings' => true,
     

4. Logging:

   • Configure as a log channel:

     LOG_CHANNEL=stack
     LOG_STACK=sentry_logs,single
     SENTRY_ENABLE_LOGS=true
     

   • Filter logs by level:

     SENTRY_LOG_LEVEL=warning
     

5. User Context:

   • Attach user data to events:

     Sentry\configureScope(function ($scope) {
         $scope->setUser(['id' => auth()->id(), 'email' => auth()->user()->email]);
     });
     

Integration Tips

• Livewire: Auto-captures component interactions. Preserve root component with:

  Sentry\configureScope(function ($scope) {
      $scope->setTransaction('livewire:component-name');
  });
  

• Queue Jobs: Use SentryTracesSampleRate middleware to control sampling:

  public function handle(ShouldQueue $job, Closure $next) {
      return $next($job)->middleware(SentryTracesSampleRate::class);
  }
  

• Metrics: Track custom metrics:

  Sentry\trace_metrics()->count('api.calls', 10, ['endpoint' => 'users']);
  

Gotchas and Tips

Pitfalls

1. DSN Configuration:

   • Issue: Events not appearing? Verify SENTRY_LARAVEL_DSN is correct and not empty.
   • Fix: Use php artisan config:clear after DSN changes.

2. Environment Mismatch:

   • Issue: Sentry captures local/dev events in production.
   • Fix: Set SENTRY_TRACES_SAMPLE_RATE=0.0 in non-production environments.

3. Transaction Naming:

   • Issue: Overlapping transaction names (e.g., Livewire + API routes).
   • Fix: Explicitly set transaction names or use Sentry\configureScope.

4. Log Level Conflicts:

   • Issue: SENTRY_LOG_LEVEL ignored if LOG_LEVEL is stricter.
   • Fix: Use SENTRY_LOG_LEVEL=debug to override globally.

5. SQL Bindings:

   • Issue: Large queries slow down requests.
   • Fix: Disable with 'sql_bindings' => false or limit to critical queries.

Debugging

• Check Initialization:

  php artisan sentry:check
  

  Validates DSN, environment, and integrations.

• Disable Integrations: Temporarily disable auto-instrumentation in bootstrap/app.php:

  Integration::handles($exceptions, false); // Disable auto-capture
  

• Manual Event Testing:

  Sentry\captureException(new \Exception('Test event'));
  Sentry\captureMessage('Test message', 'test-level');
  

Extension Points

1. Custom Integrations:

   • Extend Sentry\Integration for framework-specific hooks (e.g., Livewire, Octane).
   • Example: Override getSessionKey() for custom session storage.

2. Scope Modifiers:

   • Add context dynamically:

     Sentry\configureScope(function ($scope) {
         $scope->setTag('custom_tag', 'value');
     });
     

3. Before/After Hooks:

   • Use Sentry\beforeSendEvent() to modify payloads:

     Sentry\beforeSendEvent(function ($event) {
         $event['extra']['custom_data'] = 'value';
         return $event;
     });
     

4. Metrics Sampling:

   • Adjust SENTRY_METRICS_SAMPLE_RATE (0.0–1.0) to balance performance and data volume.

Pro Tips

• Environment-Specific Config: Use config/sentry.php to override settings per environment:

  'sample_rate' => env('SENTRY_SAMPLE_RATE', config('sentry.sample_rate', 1.0)),
  

• Release Tracking: Auto-set release version via SENTRY_RELEASE in .env or:

  Sentry\setRelease('v1.0.0');
  

• Ignored Exceptions: Exclude specific exceptions from reporting:

  Sentry\configureScope(function ($scope) {
      $scope->ignoreException(function (\Throwable $e) {
          return $e instanceof \Some\IgnoredException;
      });
  });