Jaeger Client Php Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require jonahgeorge/jaeger-client-php
   

   Ensure your project uses PHP 8.0+ (recommended) and OpenTracing-compatible dependencies.

2. Basic Initialization

   use Jaeger\Reporter\RemoteReporter;
   use Jaeger\Sampler\ConstSampler;
   use Jaeger\Sender\UdpSender;
   use Jaeger\Tracer;
   
   $reporter = new RemoteReporter(
       new UdpSender('http://jaeger-collector:14268/api/traces', 5000)
   );
   $sampler = new ConstSampler(true); // Sample all traces
   $tracer = new Tracer(
       'my-service',
       $reporter,
       $sampler
   );
   

3. First Use Case: Instrumenting a Request

   use OpenTracing\Span;
   use OpenTracing\Tracer as OpenTracingTracer;
   
   $span = $tracer->startSpan('process-request');
   $tracer->activateSpan($span);
   
   try {
       // Business logic here
       $span->setTag('http.method', 'GET');
       $span->log(['event' => 'request-started']);
   } finally {
       $span->finish();
   }
   

Key Files to Review

• vendor/jaeger-client-php/src/Jaeger/Tracer.php – Core tracer class.
• vendor/jaeger-client-php/src/Jaeger/Sampler/ – Sampling strategies.
• vendor/jaeger-client-php/src/Jaeger/Sender/ – Transport mechanisms (UDP/HTTP).

Implementation Patterns

Workflow: Distributed Tracing in Laravel

1. Middleware Integration Use Laravel middleware to auto-instrument HTTP requests:

   namespace App\Http\Middleware;
   
   use Closure;
   use Jaeger\Tracer;
   use OpenTracing\Span;
   
   class JaegerMiddleware
   {
       public function __construct(private Tracer $tracer) {}
   
       public function handle($request, Closure $next)
       {
           $span = $this->tracer->startSpan('http-request');
           $span->setTag('http.method', $request->method());
           $span->setTag('http.path', $request->path());
   
           try {
               $response = $next($request);
               $span->setTag('http.status', $response->status());
               return $response;
           } finally {
               $span->finish();
           }
       }
   }
   

2. Service-Level Instrumentation Wrap database queries, external API calls, or queues:

   use OpenTracing\Span;
   use OpenTracing\Scope;
   
   public function fetchData()
   {
       $span = $this->tracer->startSpan('fetch-data');
       $scope = $this->tracer->activateSpan($span);
   
       try {
           $data = Http::get('https://api.example.com/data');
           $span->setTag('http.url', 'https://api.example.com/data');
           return $data;
       } finally {
           $scope->detach();
           $span->finish();
       }
   }
   

3. Context Propagation Pass spans across service boundaries (e.g., queues, HTTP clients):

   // Producer (e.g., queue job)
   $span = $this->tracer->startSpan('process-order');
   $this->tracer->inject(
       $span->context(),
       ['HTTP_HEADERS'], // or 'TEXT_MAP'
       $carrier = []
   );
   Queue::push(new OrderProcessedJob($order, $carrier));
   
   // Consumer (e.g., queue worker)
   $this->tracer->extract(
       SpanContext::createFromBaggage($carrier['X-B3-TraceId'], ...),
       'TEXT_MAP'
   );
   

Integration Tips

• Laravel Service Provider: Bind the tracer as a singleton:

  public function register()
  {
      $this->app->singleton(Tracer::class, function ($app) {
          return new Tracer(
              'laravel-app',
              new RemoteReporter(new UdpSender('jaeger:14268')),
              new ConstSampler(false) // Adjust sampling rate
          );
      });
  }
  

• Environment Configuration: Use .env for dynamic settings:

  JAEGER_AGENT_HOST=jaeger
  JAEGER_SAMPLE_RATE=0.1
  

• Log Correlation: Attach the trace ID to Laravel logs:

  Log::debug('Processing order', [
      'trace_id' => $this->tracer->activeSpan()->context()->traceId(),
  ]);
  

Gotchas and Tips

Pitfalls

1. Sampling Overhead

   • Issue: High sampling rates (e.g., ConstSampler(true)) can flood Jaeger with data.
   • Fix: Use probabilistic samplers like ProbabilisticSampler or RateLimitingSampler:

     $sampler = new ProbabilisticSampler(0.1); // 10% sampling
     

   • Debug: Check Jaeger UI for high cardinality in tags (e.g., http.path).

2. Context Leaks

   • Issue: Unfinished spans or detached scopes can cause memory leaks.
   • Fix: Always use finally blocks or context managers:

     $scope = $this->tracer->activateSpan($span);
     try { /* ... */ } finally { $scope->detach(); }
     

   • Debug: Enable OPENTRACING_DEBUG=1 to log context lifecycle.

3. Transport Failures

   • Issue: UDP sender may drop packets under load.
   • Fix: Fall back to HTTP or async reporters:

     $sender = new HttpSender('http://jaeger-collector:14250/api/traces');
     

   • Debug: Monitor jaeger-client-php logs for SenderException.

4. Baggage Propagation

   • Issue: Custom baggage items may not propagate across services.
   • Fix: Explicitly declare baggage keys in extract()/inject():

     $this->tracer->inject($span->context(), ['TEXT_MAP'], $carrier, [
         'user_id' => auth()->id(),
     ]);
     

Debugging Tips

• Enable Debug Logging:

  putenv('OPENTRACING_DEBUG=1');
  

• Validate Spans: Use the Jaeger CLI to validate traces:

  jaeger-cli query --service=my-service
  

• Check for Common Tags: Ensure spans include:
  • span.kind (e.g., server, client).
  • http.method/http.url for HTTP spans.
  • error tag for failed operations.

Extension Points

1. Custom Reporters Extend AbstractReporter to batch or filter spans:

   class FilteredReporter extends AbstractReporter {
       public function report(Span $span) {
           if ($span->getTag('sensitive')) return;
           parent::report($span);
       }
   }
   

2. Dynamic Sampling Implement Sampler to adjust rates based on conditions:

   class ConditionalSampler implements Sampler {
       public function isSampled(SpanContext $spanContext) {
           return request()->ip() === '127.0.0.1'; // Sample locally
       }
   }
   

3. Laravel Debugbar Integration Display active spans in Laravel Debugbar:

   Debugbar::addCollector(new class {
       public function collect() {
           return [
               'jaeger' => [
                   'active_span' => $this->tracer->activeSpan()?->operationName(),
               ],
           ];
       }
   });