Tracing Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Microservices/Monolithic Alignment: Fits well in Symfony 7-based applications (monolithic or microservices) where distributed tracing and log correlation are critical. UUIDv7 ensures time-ordered, globally unique IDs without coordination, making it ideal for event-driven architectures (e.g., Messenger queues).
• Observability Stack Compatibility: Designed to integrate with Monolog (standard in Symfony) and Symfony Messenger, enabling seamless correlation across HTTP requests, async workers, and logs. Works with ELK, Datadog, or custom log aggregators via structured logging.
• Laravel Adaptability: While Symfony-native, the core logic (UUIDv7 generation, header propagation, log injection) can be ported to Laravel via:
  • Middleware for X-Request-Id handling.
  • Monolog processor for log correlation.
  • Queue job metadata injection (Laravel Queues).
  • Risk: Laravel’s event/queue systems differ from Symfony Messenger, requiring custom bridge logic.

Integration Feasibility

• Low-Coupling Design: Bundle is self-contained (no external dependencies beyond Symfony core). Key components:
  • HTTP Layer: X-Request-Id header injection/extraction.
  • Logging Layer: Monolog processor to attach request_id to every log.
  • Async Layer: Messenger middleware to propagate IDs through queues.
• Laravel-Specific Challenges:
  • Symfony Messenger → Laravel Queues: Requires custom middleware to inject request_id into queue payloads (e.g., via Illuminate\Queue\SerializesModels or dispatchSync wrappers).
  • Monolog Integration: Laravel uses monolog/monolog by default; the bundle’s processor can be adapted via a custom Handler or Processor.
  • Middleware Gaps: Laravel’s middleware stack may need adjustments to ensure X-Request-Id is set before other middleware (e.g., auth, validation) runs.
• UUIDv7: Laravel’s Ramsey\Uuid or symfony/uuid can generate UUIDv7 (if not already in use).

Technical Risk

Key Questions

1. Observability Goals:
   • Is end-to-end request tracing (HTTP → Queue → Logs) a hard requirement, or is log correlation sufficient?
   • Are there existing tracing tools (e.g., OpenTelemetry) that could conflict or complement this?
2. Laravel Ecosystem Fit:
   • Does the team use Symfony Messenger, or is Laravel Queues the primary async system?
   • Are there custom log formats (e.g., JSON) that need request_id injection?
3. Scalability:
   • Will high-throughput queues (e.g., 10K+ jobs/sec) stress the request_id propagation mechanism?
   • Are there edge cases (e.g., nested queues, delayed jobs) where IDs might drop?
4. Maintenance:
   • Is the team comfortable extending Symfony bundles in Laravel, or should this be a custom package?
   • What’s the upgrade path if the bundle evolves (e.g., Symfony 8 support)?

Integration Approach

Stack Fit

• Core Compatibility:
  • Laravel 10/11: ✅ (PHP 8.1+ compatible; Monolog/UUID support).
  • Symfony Components: ⚠️ (Bundle is Symfony-native; extract logic for Laravel).
  • Queue Systems: ✅ (Laravel Queues, Horizon, or custom workers).
  • Logging: ✅ (Monolog is Laravel’s default; processor can be adapted).
• Alternatives Considered:
  • OpenTelemetry PHP: More feature-rich (distributed tracing) but heavier.
  • Custom Middleware: Less maintainable than a bundled solution.
  • Laravel Debugbar: Limited to HTTP layer (no queue/log correlation).

Migration Path

1. Phase 1: HTTP Layer (1-2 days)

   • Replace Symfony’s RequestIdListener with Laravel middleware:

     // app/Http/Middleware/RequestIdMiddleware.php
     public function handle($request, Closure $next) {
         $request->headers->set('X-Request-Id', Uuid::v7()->toString());
         return $next($request);
     }
     

   • Register middleware in app/Http/Kernel.php.

2. Phase 2: Logging (1 day)

   • Add Monolog processor to inject request_id:

     // config/logging.php
     'processors' => [
         (new \Amashukov\TracingBundle\Processor\RequestIdProcessor())->withAttribute('request_id'),
     ],
     

   • OR create a custom processor for Laravel’s Monolog setup.

3. Phase 3: Queue Propagation (2-3 days)

   • Option A: Use Laravel’s dispatchSync for critical paths (no queue bridge needed).
   • Option B: Create a queue job wrapper to inject request_id:

     // app/Jobs/TraceableJob.php
     public function handle() {
         Log::info('Processing job', ['request_id' => $this->requestId]);
     }
     

   • Option C: Extend Illuminate\Queue\Queue to auto-inject headers (advanced).

4. Phase 4: Validation (1 day)

   • Test Cases:
     • HTTP request → Queue job → Logs: All have same request_id.
     • Failed jobs: request_id persists in retry logs.
     • Nested queues: ID propagates through multiple workers.

Compatibility

Sequencing

1. Prerequisites:
   • Laravel 10+ with PHP 8.1+.
   • ramsey/uuid or symfony/uuid for UUIDv7 generation.
   • Monolog configured (default in Laravel).
2. Order of Implementation:
   • HTTP Middleware → Logging Processor → Queue Integration → Testing.
3. Rollout Strategy:
   • Canary: Enable in a single service first (e.g., API layer).
   • Feature Flag: Wrap middleware with a config flag for gradual rollout.
   • Monitor: Check for request_id drops in logs/queues.

Operational Impact

Maintenance

• Pros:
  • Minimal Boilerplate: Core logic is reusable across projects.
  • Structured Logs: request_id enables easy filtering in ELK/Datadog.
  • No External Dependencies: Self-contained after extraction.
• Cons:
  • Laravel-Specific Overhead: Custom queue/worker logic may need updates for Laravel versions.
  • Debugging Complexity: Distributed request_id issues require cross-layer tracing.
• Maintenance Tasks:
  • UUIDv7 Updates: Monitor for PHP/Ramsey UUID changes.
  • Log Format Changes: Ensure request_id remains in extra field.
  • Queue Worker Patches: Update if Laravel Queue internals change.

Support

• Proactive Measures:
  • Documentation: Create a Laravel-specific README for setup/debugging.
  • Centralized Logging: Use request_id in alerting rules (e.g., "no logs for this ID").
  • **Error