Sentry Enhanced Tracing Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require amarc-sudo/sentry-enhanced-tracing lexik/jwt-authentication-bundle
   

2. Enable Bundle: Add to config/bundles.php:

   AmarcSudo\SentryEnhancedTracing\SentryEnhancedTracingBundle::class => ['all' => true],
   

3. Configure Sentry (ensure traces_sample_rate is set in config/packages/sentry.yaml):

   sentry:
       dsn: '%env(SENTRY_DSN)%'
       options:
           traces_sample_rate: 1.0
   

4. First Use Case: Trigger an HTTP request to your Symfony app. Open Sentry dashboard to see:

   • Automatic event phase spans (e.g., kernel.request, kernel.controller).
   • Nested database/cache/template spans under relevant phases.

Implementation Patterns

Core Workflow

1. Automatic Tracing:

   • No manual span creation needed. The bundle auto-captures:
     • Doctrine DBAL queries (nested under event phases).
     • Cache operations (Redis, APCu, Symfony Cache).
     • Twig template rendering.
     • HTTP client calls.
   • Example:

     // DB query auto-traced under kernel.controller
     $users = $em->getRepository(User::class)->findAll();
     

2. Event Phase Tracking:

   • Symfony kernel events (kernel.request, kernel.controller, etc.) are traced as spans.
   • Useful for debugging slow listeners:

     # config/packages/sentry_enhanced_tracing.yaml
     sentry_enhanced_tracing:
         tracked_events:
             - 'kernel.request'
             - 'kernel.controller'
     

3. User Context:

   • Extend your User entity with EnhancedUserInterface for richer Sentry context:

     class User implements EnhancedUserInterface {
         public function getEnhancedFirstname(): ?string { ... }
         public function getEnhancedLastname(): ?string { ... }
     }
     

   • Automatically captures JWT-authenticated users via lexik_jwt_authentication.on_jwt_authenticated.

4. Messenger Integration:

   • Auto-traces queue messages (producer/consumer linkage via SentryTraceStamp):

     // Dispatch
     $bus->dispatch(new EmailJob($payload));
     
     // Worker (auto-traced)
     php bin/console messenger:consume async
     

Integration Tips

• Sampling: Use traces_sample_rate: 0.1 in production to reduce overhead.
• Performance Thresholds: Customize categorization (fast/normal/slow) in config/packages/sentry_enhanced_tracing.yaml:

  sentry_enhanced_tracing:
      performance_thresholds:
          kernel.controller: 0.1  # 100ms
  

• Exclude Endpoints: Disable tracing for non-critical routes via Sentry\State\HubInterface:

  $hub->configureScope(function (Scope $scope) {
      $scope->setSpan(null); // Disable tracing for this request
  });
  

Gotchas and Tips

Pitfalls

1. Missing Spans:

   • Cause: traces_sample_rate set to 0 or Sentry DSN misconfigured.
   • Fix: Verify sentry.yaml and check Sentry dashboard for transactions.
   • Debug: Enable debug mode and inspect logs for SentryListenerPhasesTracer errors.

2. High Overhead:

   • Cause: Full tracing (traces_sample_rate: 1.0) on high-traffic endpoints.
   • Fix: Use sampling or exclude routes:

     # config/packages/sentry_enhanced_tracing.yaml
     sentry_enhanced_tracing:
         excluded_routes:
             - '^/api/health'
     

3. PII Leakage:

   • Cause: Accidental inclusion of sensitive data (e.g., capture_email: true).
   • Fix: Disable PII capture in user_context:

     sentry_enhanced_tracing:
         user_context:
             capture_email: false
     

4. Listener Conflicts:

   • Cause: Other bundles overriding Sentry listener priorities.
   • Fix: Ensure ChangeSentryListenerPriorityPass runs early (priority 99999-99995).

Debugging Tips

• Log Spans: Enable debug logging for the bundle:

  # config/packages/dev/sentry_enhanced_tracing.yaml
  sentry_enhanced_tracing:
      debug: true
  

• Manual Span Creation: Override auto-tracing for specific logic:

  $hub->startSpan('custom_operation', [
      'op' => 'custom',
      'description' => 'Manual span example',
  ]);
  

• Messenger Issues: Verify SentryTraceStamp and SentryUserStamp are registered:

  use AmarcSudo\SentryEnhancedTracing\Messenger\SentryTraceStamp;
  use AmarcSudo\SentryEnhancedTracing\Messenger\SentryUserStamp;
  

Extension Points

1. Custom Integrations:

   • Extend SentryListenerPhasesTracer to add support for new services (e.g., Elasticsearch):

     // src/EventListener/CustomSentryTracer.php
     class CustomSentryTracer implements EventSubscriberInterface {
         public static function getSubscribedEvents() {
             return [
                 KernelEvents::CONTROLLER => ['onController', 100],
             ];
         }
     
         public function onController(ControllerEvent $event) {
             $hub = \Sentry\SentrySdk::getCurrentHub();
             $hub->startSpan('elasticsearch.query', ['op' => 'search']);
             // ... your logic
         }
     }
     

2. Override User Context:

   • Implement EnhancedUserInterface to customize PII handling:

     class User implements EnhancedUserInterface {
         public function getEnhancedEmail(): ?string {
             return $this->email ?? null; // Sanitize or redact if needed
         }
     }
     

3. Phase Customization:

   • Add/remove tracked events dynamically:

     $tracer = $container->get(SentryListenerPhasesTracer::class);
     $tracer->addTrackedEvent('custom.event');