Jaeger Php Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require auxmoney/jaeger-php
   

   Ensure your project uses OpenTracing PHP (opentracing/opentracing) as a dependency.

2. Basic Initialization

   use Jaeger\Reporter\RemoteReporter;
   use Jaeger\Sampler\ConstSampler;
   use Jaeger\Tracer;
   use Jaeger\Sender\UdpSender;
   use OpenTracing\Tracer as OpenTracingTracer;
   
   $reporter = new RemoteReporter(
       new UdpSender('jaeger-agent-host', 6831),
       'my-service'
   );
   
   $sampler = new ConstSampler(true); // Sample all traces (for dev)
   $tracer = new Tracer(
       'my-service',
       $reporter,
       $sampler
   );
   
   // Register as OpenTracing Tracer
   OpenTracingTracer::register($tracer);
   

3. First Use Case: Instrumenting a Request

   use OpenTracing\Span;
   use OpenTracing\Tracer;
   
   $tracer = Tracer::get();
   $span = $tracer->buildSpan('http-request')->start();
   
   try {
       // Your logic here (e.g., HTTP call, DB query)
       $span->setTag('http.method', 'GET');
       $span->setTag('http.url', '/api/users');
   } finally {
       $span->finish();
   }
   

Key Files to Explore

• vendor/auxmoney/jaeger-php/src/ – Core classes (e.g., Tracer.php, Reporter.php).
• vendor/opentracing/opentracing/src/ – OpenTracing API reference.
• Jaeger UI docs (jaegertracing.io) for interpreting traces.

Implementation Patterns

1. Global Tracer Initialization

• Best Practice: Initialize the tracer in a service provider (e.g., AppServiceProvider) or Laravel’s bootstrap/app.php to ensure it’s available globally.
• Example:

  // app/Providers/AppServiceProvider.php
  public function boot()
  {
      $this->initializeJaeger();
  }
  
  protected function initializeJaeger()
  {
      $reporter = new RemoteRepporter(
          new UdpSender(config('jaeger.agent_host'), config('jaeger.agent_port')),
          config('app.name')
      );
      $tracer = new Tracer(
          config('app.name'),
          $reporter,
          new ConstSampler(config('jaeger.sampling_rate'))
      );
      OpenTracingTracer::register($tracer);
  }
  

2. Middleware for Automatic Span Creation

• Use Laravel middleware to auto-instrument HTTP requests/responses.
• Example:

  // app/Http/Middleware/TraceRequests.php
  public function handle($request, Closure $next)
  {
      $tracer = Tracer::get();
      $span = $tracer->buildSpan('http.request')
          ->withTag('http.method', $request->method())
          ->withTag('http.url', $request->fullUrl())
          ->start();
  
      try {
          $response = $next($request);
          $span->setTag('http.status_code', $response->getStatusCode());
          return $response;
      } finally {
          $span->finish();
      }
  }
  

• Register in app/Http/Kernel.php:

  protected $middleware = [
      \App\Http\Middleware\TraceRequests::class,
  ];
  

3. Database Query Tracing

• Wrap Eloquent queries or raw PDO statements in spans.
• Example with Eloquent:

  use OpenTracing\Scope;
  
  public function getUser($id)
  {
      $tracer = Tracer::get();
      $span = $tracer->buildSpan('query.users')->start();
  
      try {
          $scope = $tracer->activateSpan($span);
          $user = User::find($id);
          $span->setTag('db.query', 'SELECT * FROM users WHERE id = ?');
          return $user;
      } finally {
          $scope->detach();
          $span->finish();
      }
  }
  

4. Context Propagation (Microservices)

• Use HTTP headers (uber-trace-id) to propagate traces across services.
• Example:

  // Extract context from incoming request
  $tracer = Tracer::get();
  $extractor = new HttpHeaderExtractor();
  $scopeManager = new ScopeManager();
  $tracer->inject(
      $extractor->extract($request->header()),
      'http_headers',
      $request->headers
  );
  
  // Inject into outgoing requests
  $tracer->inject($span->context(), 'http_headers', $response->headers);
  

5. Custom Samplers

• Replace ConstSampler with probabilistic sampling (e.g., ProbabilisticSampler) for production.
• Example:

  $sampler = new ProbabilisticSampler(0.1); // Sample 10% of traces
  

6. Logging Integration

• Correlate Monolog logs with traces using uber-trace-id.
• Example:

  $logger = Log::getMonolog();
  $logger->pushHandler(new \Monolog\Handler\StreamHandler(
      storage_path('logs/jaeger.log')
  ));
  $logger->pushProcessor(new \Monolog\Processor\UidProcessor());
  $logger->pushProcessor(function ($record) {
      $record['extra']['trace_id'] = Tracer::get()->activeSpan()?->context()->toTraceId();
      return $record;
  });
  

Gotchas and Tips

1. Configuration Quirks

• Agent Host/Port: Ensure the Jaeger agent (jaeger-agent) is running and accessible. Default UDP port is 6831.
  • Debugging: If traces don’t appear, verify the agent is running:

    docker run -d -p 6831:6831/udp -p 6832:6832/udp -p 16686:16686 jaegertracing/all-in-one
    

• Sampling Rate: In production, use a low sampling rate (e.g., 0.01) to avoid overwhelming the agent.
• Service Name: Must match the Jaeger UI service name for proper grouping.

2. Common Pitfalls

• Unfinished Spans: Always call $span->finish() in a finally block to avoid memory leaks.
  • Fix: Use a trait or helper to ensure spans are closed:

    trait AutoFinishSpan
    {
        protected function withSpan(string $name, Closure $callback)
        {
            $tracer = Tracer::get();
            $span = $tracer->buildSpan($name)->start();
            try {
                return $callback($span);
            } finally {
                $span->finish();
            }
        }
    }
    

• Context Leaks: Avoid holding references to spans/contexts longer than necessary (e.g., in cached data).
• Thread Safety: Jaeger-PHP is not thread-safe. Use one tracer instance per request (Laravel’s request lifecycle handles this).

3. Debugging Tips

• Check Trace IDs: Log the trace_id and span_id for debugging:

  $span->context()->toTraceId(); // e.g., "a1b2c3d4..."
  

• Jaeger UI: Query traces by operation_name or tags (e.g., http.url).
• Reporter Failures: If traces disappear, check:
  • Agent connectivity (telnet jaeger-agent-host 6831).
  • Firewall rules (UDP port 6831 must be open).
  • Reporter errors (wrap RemoteReporter in a try-catch to log failures).

4. Extension Points

• Custom Reporters: Implement Jaeger\Reporter\ReporterInterface for custom storage (e.g., database).
• Span Processors: Extend Jaeger\SpanProcessor to add custom logic before sending spans.
• Baggage: Use span->setBaggageItem() to pass structured data across services:

  $span->setBaggageItem('user.id', $user->id);
  

• Custom Tags: Add domain-specific tags (e.g., queue.name, cache.hit).

5. Performance Considerations

• Span Creation Overhead: Avoid creating spans for trivial operations (e.g., simple loops).
• Batch Reporting: Use BatchReporter to reduce network calls:

  $reporter = new BatchReporter(
      new RemoteReporter($sender, 'my-service'),
      100, // Max queue