Zipkin Laravel Package

Getting Started

Minimal Setup in Laravel

1. Installation

   composer require openzipkin/zipkin
   

2. Basic Configuration Add to config/app.php under providers:

   OpenZipkin\Laravel\ZipkinServiceProvider::class,
   

   Publish config (if needed):

   php artisan vendor:publish --provider="OpenZipkin\Laravel\ZipkinServiceProvider" --tag="config"
   

3. First Use Case: Tracing a Controller

   use OpenZipkin\Laravel\Zipkin;
   
   class ExampleController extends Controller
   {
       public function index()
       {
           $span = Zipkin::startSpan('example-controller');
           try {
               // Your logic here
               return response()->json(['success' => true]);
           } finally {
               $span->finish();
           }
       }
   }
   

4. Verify in Zipkin UI

   • Start Zipkin server (e.g., Docker: docker run -d -p 9411:9411 openzipkin/zipkin)
   • Access http://localhost:9411 to see traces.

Implementation Patterns

Workflows

1. Automatic Tracing Use middleware to auto-instrument HTTP requests:

   // app/Http/Middleware/TraceRequests.php
   public function handle($request, Closure $next)
   {
       $span = Zipkin::startSpan('http-request', ['http.method' => $request->method()]);
       $response = $next($request);
       $span->finish();
       return $response;
   }
   

   Register in app/Http/Kernel.php:

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

2. Database Query Tracing Wrap Eloquent queries:

   $span = Zipkin::startSpan('user-fetch');
   $user = User::where('id', 1)->first();
   $span->addAnnotation('SQL', ['query' => $user->toSql()]);
   $span->finish();
   

3. Service Calls (HTTP/Queue) Trace external API calls:

   $span = Zipkin::startSpan('external-api-call');
   $response = Http::withOptions(['trace' => true])->get('https://api.example.com');
   $span->finish();
   

4. Queue Job Tracing Use Zipkin::startSpan() in job handles:

   public function handle()
   {
       $span = Zipkin::startSpan('process-payment');
       // Job logic
       $span->finish();
   }
   

Integration Tips

• Laravel Queues: Extend Illuminate\Queue\Jobs\Job to auto-trace jobs.
• Lumen: Use Zipkin::startSpan() in route closures.
• Laravel Horizon: Trace queue workers by extending HorizonServiceProvider.
• API Resources: Trace serialization:

  $span = Zipkin::startSpan('serialize-user');
  $resource = new UserResource($user);
  $span->finish();
  

Gotchas and Tips

Pitfalls

1. Span Context Propagation

   • Ensure Zipkin::getContext() is passed across threads (e.g., queues, HTTP clients).
   • Use Zipkin::setContext() when forking spans (e.g., in async jobs).

2. Sampling Rate

   • Default sampling may drop traces. Adjust in config/zipkin.php:

     'sampler' => [
         'type' => 'probabilistic',
         'rate' => 1.0, // 100% sampling
     ],
     

3. Performance Overhead

   • Avoid tracing trivial operations (e.g., if conditions). Focus on:
     • External calls (HTTP, DB, queues).
     • Business logic layers (services, repositories).

4. Clock Skew

   • Ensure all services use synchronized clocks (NTP) to avoid trace timeline issues.

5. Baggage Propagation

   • Manually propagate baggage (key-value pairs) across services:

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

Debugging

• Missing Traces:

  • Check if the Zipkin reporter is configured (config/zipkin.php).
  • Verify the reporter URL is reachable (e.g., http://zipkin:9411/api/v2/spans).
  • Enable debug logs:

    'logging' => [
        'enabled' => true,
        'channel' => 'single',
    ],
    

• Corrupted Traces:

  • Validate span IDs are unique (use Zipkin::generateId() if needed).
  • Ensure traceId and spanId are propagated correctly in headers:

    $headers = [
        'X-B3-TraceId' => $span->getTraceId(),
        'X-B3-SpanId' => $span->getSpanId(),
    ];
    

Extension Points

1. Custom Reporters Extend OpenZipkin\Reporter\BaseReporter to send spans to custom backends (e.g., Jaeger, Datadog).

2. Span Annotations Add custom annotations for debugging:

   $span->addAnnotation('User loaded', ['user_id' => $user->id]);
   

3. Baggage Filters Use baggage to route requests dynamically:

   if ($span->getBaggageItem('tenant.id')) {
       // Tenant-specific logic
   }
   

4. Context Managers For complex workflows, use Zipkin::withContext():

   Zipkin::withContext(function () {
       $span = Zipkin::startSpan('nested-workflow');
       // Nested logic
       $span->finish();
   });
   

5. Laravel Events Trace events globally:

   Event::listen(function ($event) {
       $span = Zipkin::startSpan('event-' . class_basename($event));
       // Event logic
       $span->finish();
   });