Open Telemetry Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony Native Integration: The bundle is designed specifically for Symfony 8.0+, leveraging its dependency injection (DI) and event systems. This aligns perfectly with Laravel’s ecosystem if using Symfony components (e.g., Symfony HTTP Foundation, Messenger, or Doctrine via Laravel Doctrine Bridge).
• OpenTelemetry Standard Compliance: Adheres to OpenTelemetry’s tracing, metrics, and logging standards, ensuring compatibility with observability tools like Jaeger, Prometheus, and Grafana.
• Modular Instrumentation: Supports granular instrumentation (HTTP, Doctrine, Redis, etc.), allowing selective enablement/disablement—ideal for Laravel’s layered architecture (e.g., skip tracing for CLI commands unless explicitly configured).

Integration Feasibility

• Laravel Compatibility:
  • Symfony Components: If the Laravel app uses Symfony’s HttpFoundation, Messenger, or Doctrine, integration is straightforward (e.g., wrap HttpClient with HttpTracingMiddleware).
  • Non-Symfony Components: For native Laravel services (e.g., Illuminate\Http\Request, Illuminate\Database), custom span processors or decorators would be required (see Key Questions).
  • Queue Workers: Messenger integration is available, but Laravel’s queue workers (e.g., php artisan queue:work) would need custom instrumentation (e.g., via TraceableHookCompilerPass equivalent).
• PHP Extension Conflict: The bundle disables OTEL_PHP_AUTOLOAD_ENABLED, which may conflict with Laravel’s auto-loading. A custom compiler pass would be needed to replicate the bundle’s initialization logic.

Technical Risk

Key Questions

1. Symfony Component Adoption:
   • Which Symfony components (if any) are already in use? (e.g., Messenger, HttpClient, Doctrine)
   • If none, what’s the cost of adding them (e.g., symfony/http-client for HTTP tracing)?
2. Laravel-Specific Instrumentation:
   • How to trace Eloquent queries without Doctrine? (Custom QueryObserver or Traceable attribute for repositories.)
   • How to instrument Laravel’s queue workers (e.g., Illuminate\Queue\Worker)?
3. Exporter Configuration:
   • Is an OTLP collector (e.g., OpenTelemetry Collector) available, or will we use console exporter for development?
4. Attribute Support:
   • Can Laravel’s attributes (PHP 8+) be used for #[Traceable] annotations, or is a custom macro needed?
5. Performance Baseline:
   • What’s the acceptable overhead for tracing? (Benchmark with/without instrumentation.)

Integration Approach

Stack Fit

Migration Path

1. Phase 1: Infrastructure Setup
   • Deploy an OTLP collector (e.g., OpenTelemetry Collector with Jaeger/Prometheus backends).
   • Configure environment variables:

     OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318
     OTEL_SERVICE_NAME=laravel-app
     OTEL_PHP_AUTOLOAD_ENABLED=false
     

2. Phase 2: Bundle Integration
   • Install the bundle via Composer (adjust for Laravel’s autoloader):

     composer require danilovl/open-telemetry-bundle
     

   • For Symfony components: Register the bundle in config/bundles.php (if using Symfony’s kernel).
   • For Laravel: Create a custom service provider to replicate the bundle’s compiler passes (see Sequencing).
3. Phase 3: Instrumentation Configuration
   • Start with minimal config (config/packages/open_telemetry.yaml):

     danilovl_open_telemetry:
         service:
             name: 'laravel-app'
         instrumentation:
             http_server: { enabled: true, tracing: { enabled: true } }
             doctrine: { enabled: true, tracing: { enabled: true } }
     

   • Gradually enable other modules (e.g., redis, messenger).
4. Phase 4: Custom Instrumentation
   • For Laravel-native services (e.g., Eloquent), create:
     • A custom Traceable attribute (PHP 8+).
     • A compiler pass to register hooks (mimic TraceableHookCompilerPass).
     • Example:

       // app/Providers/OpenTelemetryServiceProvider.php
       use Danilovl\OpenTelemetryBundle\CompilerPass\TraceableHookCompilerPass;
       
       public function register(): void
       {
           $this->app->register(TraceableHookCompilerPass::class);
       }
       

Compatibility

• PHP 8.5+: The bundle requires PHP 8.5, but Laravel 10+ supports this. Downgrade may require forks.
• Laravel Services:
  • Symfony-Compatible: Direct integration (e.g., Messenger, HttpClient).
  • Native Laravel: Requires custom decorators/observers (e.g., Eloquent, Queues).
• Existing Tracing: If using Monolog or Stackdriver, configure the bundle to export to both via multiple exporters.

Sequencing

1. Initialization Order:
   • Disable OTEL_PHP_AUTOLOAD_ENABLED before loading the bundle.
   • Load the bundle after Symfony components (if used) but before Laravel’s service providers.
2. Compiler Passes:
   • Register OpenTelemetryCompilerPass early (e.g., in AppServiceProvider::boot()) to ensure all DI tags are resolved.
   • Example:

     $this->app->make('kernel')->getContainer()->addCompilerPass(
         new \Danilovl\OpenTelemetryBundle\DependencyInjection\Compiler\OpenTelemetryCompilerPass()
     );
     

3. Runtime Initialization:
   • The SDK initializes lazily on the first request. For CLI apps, trigger initialization manually:

     $this->app->make(\Danilovl\OpenTelemetryBundle\OpenTelemetryInitializer::class)->initializeSdk();
     

Operational Impact

Maintenance

Support