Sentry Enhanced Tracing Laravel Package

Technical Evaluation

Architecture Fit

• Symfony Native: The package is a Symfony Bundle, making it a perfect fit for Laravel applications using Symfony components (e.g., Symfony HTTP Foundation, Doctrine DBAL, or Symfony Messenger). For pure Laravel, integration would require adapters (e.g., wrapping Laravel’s DB, Cache, and EventDispatcher in Symfony equivalents).
• Tracing Hierarchy: The automatic child span capture (DB, Cache, HTTP, Twig) aligns well with Laravel’s need for distributed tracing (e.g., Lumen, Octane, or Laravel Horizon workers).
• JWT Integration: While Laravel uses tymon/jwt-auth, the package’s event-based user context can be adapted via Laravel’s auth.jwt events.

Integration Feasibility

• High for Symfony-based Laravel: If using Laravel with Symfony components (e.g., Symfony UX, Messenger, or API Platform), integration is straightforward.
• Moderate for Pure Laravel: Requires custom adapters for:
  • Laravel’s Illuminate\Database → Symfony DBAL
  • Laravel’s Cache → Symfony Cache
  • Laravel’s Events → Symfony EventDispatcher
  • Laravel’s Blade → Twig (or mock spans for Blade)
• Messenger Support: If using Laravel Queues, the package’s queue monitoring can be adapted via SentryTraceStamp (similar to Symfony’s TraceableStamp).

Technical Risk

Key Questions

1. Is Symfony integration acceptable?
   • If yes → Proceed with Symfony Bridge.
   • If no → Assess adapter effort (DBAL, Cache, Events).
2. Do we use JWT auth?
   • If yes → Adapt auth.jwt events to trigger EnhancedUserInterface.
   • If no → Disable user context or use Laravel’s auth events.
3. Need queue monitoring?
   • If using Laravel Queues → Adapt SentryTraceStamp for Illuminate\Queue.
4. Blade vs. Twig?
   • If using Blade → Decide between:
     • Mocking Twig spans.
     • Using Laravel’s stack:trace for manual spans.
5. Sentry DSN Management
   • How is SENTRY_DSN configured? (Laravel’s .env vs. Symfony’s %env(SENTRY_DSN)%)

Integration Approach

Stack Fit

Migration Path

1. Phase 1: Core Tracing (High Priority)

   • Install Symfony components:

     composer require symfony/http-foundation symfony/cache doctrine/dbal
     

   • Wrap Laravel’s DB and Cache in Symfony interfaces.
   • Register the bundle in config/bundles.php (if using Symfony).

2. Phase 2: Event Listeners (Medium Priority)

   • Replace Laravel’s Event facade with Symfony’s EventDispatcher.
   • Adapt kernel.* events to Laravel’s Illuminate\Events.

3. Phase 3: User Context (Low Priority)

   • Extend Laravel’s User model with EnhancedUserInterface.
   • Listen to auth.jwt events to populate Sentry user context.

4. Phase 4: Blade/Twig (Optional)

   • If using Twig, proceed with automatic spans.
   • If using Blade, implement manual spans via Sentry\startSpan().

Compatibility

Sequencing

1. Step 1: Install Dependencies

   composer require amarc-sudo/sentry-enhanced-tracing symfony/cache doctrine/dbal
   

2. Step 2: Configure Sentry Add to .env:

   SENTRY_DSN=your_dsn
   SENTRY_TRACES_SAMPLE_RATE=0.1
   

3. Step 3: Register Bundle If using Symfony:

   // config/bundles.php
   AmarcSudo\SentryEnhancedTracing\SentryEnhancedTracingBundle::class => ['all' => true],
   

4. Step 4: Wrap Laravel Services Example for DBAL:

   // app/Providers/AppServiceProvider.php
   use Doctrine\DBAL\Connection;
   use Illuminate\Support\Facades\DB;
   
   public function register()
   {
       $db = DB::connection();
       $dbalConnection = new Connection($db->getPdo(), $db->getConfig());
       $this->app->singleton(Connection::class, fn() => $dbalConnection);
   }
   

5. Step 5: Test Tracing Call an endpoint and verify Sentry dashboard shows:
   • Database queries as child spans.
   • Cache operations nested under kernel.controller.
6. Step 6: Adapt Auth Listen to auth.jwt and populate EnhancedUserInterface.
7. Step 7: Optional - Queue Monitoring Extend Illuminate\Queue\Events\JobProcessed to inject SentryTraceStamp.

Operational Impact

Maintenance

Support

Scaling

• Performance Overhead:
  • Development: traces_sample_rate=1.0 (full tracing).
  • Production: traces_sample_rate=0.1 (10% sampling).
• High-Traffic Endpoints:
  • Exclude from tracing via middleware:

    if (request()->is('api/heavy-endpoint*')) {
        Sentry\configureScope(fn($scope) => $scope->setSpan(null));
    }
    

• Database Load:
  • Sentry spans are not stored in DB (only sent to Sentry).

Failure Modes

| Failure Scenario | Impact