Sentry Async Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require andersundsehr/sentry-async
   

2. Configure Sentry to use the async transport in config/packages/sentry.yaml:

   sentry:
     options:
       transport: AUS\SentryAsync\Transport\QueueTransport
   

3. Verify the queue directory is writable (default: %kernel.cache_dir%/sentry_async/).

First Use Case: Fire-and-Forget Errors

Replace synchronous Sentry calls (e.g., Sentry\captureException()) with the same method calls—they’ll now queue asynchronously:

try {
    // Risky operation
} catch (\Exception $e) {
    \Sentry\captureException($e); // Queued for async processing
}

Implementation Patterns

Core Workflow

1. Queue-Based Processing:

   • Errors/exceptions are serialized and stored in a queue (default: file-based).
   • A background process (e.g., Symfony’s messenger or a custom script) flushes the queue to Sentry.
   • Example flush command:

     php bin/console sentry:async:flush
     

2. Custom Queue Integration:

   • Replace the default file queue with a Symfony Messenger or Doctrine Queue:

     # config/services.yaml
     AUS\SentryAsync\Transport\QueueTransport:
       $queue: '@messenger.default_bus'
     

   • Implement AUS\SentryAsync\Queue\QueueInterface for custom backends.

3. Batch Processing:

   • Configure batch limits in sentry_async.file_queue.limit (default: 200 entries).
   • Enable compression (sentry_async.file_queue.compress: true) to reduce I/O overhead.

Integration Tips

• For Laravel: Use Symfony’s HttpKernel or adapt the queue logic to Laravel’s queue system (e.g., database or redis).
• For CLI Jobs: Schedule the flush command via cron or Laravel’s task scheduler:

  * * * * * cd /path-to-project && php artisan sentry:async:flush >> /dev/null 2>&1
  

• Testing: Mock the queue interface in tests to avoid real Sentry calls:

  $this->app->instance(QueueInterface::class, new MockQueue());
  

Gotchas and Tips

Pitfalls

1. Queue Directory Permissions:

   • Ensure %kernel.cache_dir%/sentry_async/ is writable by the web server (e.g., chmod -R 755 var/cache/sentry_async).
   • Debug Tip: Check for Permission denied errors in Sentry’s logs or Symfony’s var/log/dev.log.

2. DSN Configuration:

   • The package dynamically resolves the DSN from Sentry’s existing config (no duplicate sentry.dsn needed in sentry_async).

3. Background Process Reliability:

   • If using a custom queue (e.g., Redis), ensure the worker process is always running. For file queues, verify the flush command runs periodically.

4. Entry Data Limits:

   • Large payloads (e.g., huge stack traces) may hit file size limits. Adjust limit or switch to a more scalable queue (e.g., database).

Debugging

• Flush Command Output:

  • Run with -v for verbose logs:

    php bin/console sentry:async:flush -v
    

  • Check for skipped entries due to validation errors (e.g., malformed DSN).

• Queue Inspection:

  • List queued entries (file queue):

    ls -la var/cache/sentry_async/
    

  • For custom queues, implement a QueueInterface::peek() method.

Extension Points

1. Custom Entry Data:

   • Extend AUS\SentryAsync\Entry\Entry to include metadata (e.g., user context):

     sentry_async:
       entry_factory:
         entry_class: 'App\SentryAsync\CustomEntry'
     

   • Implement __toString() to serialize additional fields.

2. Transport Overrides:

   • Replace QueueTransport entirely by binding a custom class to AUS\SentryAsync\Transport\QueueTransport in services.yaml.

3. Event Listeners:

   • Hook into SentryAsyncEvents::ENTRY_ADDED to filter or modify entries before queuing:

     use AUS\SentryAsync\Event\SentryAsyncEvents;
     
     $eventDispatcher->addListener(SentryAsyncEvents::ENTRY_ADDED, function ($entry) {
         $entry->setExtra('custom_key', 'value');
     });
     

Performance Tips

• Compression: Enable compress: true for high-volume queues to reduce disk usage.
• Batch Size: Increase limit for high-throughput apps (test impact on memory usage).
• Queue Workers: For non-file queues, use Symfony’s messenger:consume for parallel processing:

  php bin/console messenger:consume sentry-async -vv