Gearman Stats Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require necromant2005/gearman-stats
   

   Ensure gearman/gearman is also installed (dependency).

2. Basic Usage Initialize the client and start collecting stats:

   use Necromant2005\GearmanStats\GearmanStats;
   
   $stats = new GearmanStats();
   $stats->start(); // Begin tracking stats
   

3. First Use Case Wrap Gearman job execution to log metrics:

   $client = new \GearmanClient();
   $client->addServer();
   
   $stats->trackJob('process_data', function() use ($client) {
       $client->addTask('process_data', 'data');
       return $client->runTasks();
   });
   

Implementation Patterns

Workflow Integration

1. Middleware for Job Tracking Create middleware to auto-wrap Gearman calls:

   // app/Http/Middleware/GearmanStatsMiddleware.php
   public function handle($request, Closure $next) {
       $stats = app(GearmanStats::class);
       $stats->trackJob('webhook_processing', function() use ($request) {
           // Gearman logic here
       });
       return $next($request);
   }
   

2. Queue Job Wrapper Extend Laravel’s Job class to include stats:

   class GearmanJob implements ShouldQueue {
       use Dispatchable, InteractsWithQueue;
   
       public function handle() {
           $stats = app(GearmanStats::class);
           $stats->trackJob('email_sending', fn() => $this->sendEmail());
       }
   }
   

3. Batch Processing Track performance of bulk operations:

   $stats->startBatch('user_import');
   foreach ($users as $user) {
       $client->addTask('import_user', $user);
   }
   $stats->endBatch(); // Logs total time + per-job metrics
   

Gotchas and Tips

Pitfalls

1. Thread Safety

   • GearmanStats is not thread-safe. Avoid concurrent calls to start()/endBatch().
   • Fix: Use a singleton or request-scoped binding in Laravel.

2. Memory Leaks

   • Long-running batches may accumulate stats in memory.
   • Fix: Call flush() periodically or use endBatch() explicitly.

3. Gearman Worker Context

   • Stats collected on the client side won’t reflect worker performance.
   • Workaround: Pair with gearman/worker logging for full visibility.

Debugging

• Enable Verbose Logging

  $stats->setLogLevel(GearmanStats::LOG_DEBUG);
  

• Check for Silent Failures Wrap trackJob() in a try-catch to log unhandled errors:

  try {
      $stats->trackJob('fragile_task', fn() => $this->riskyOperation());
  } catch (\Exception $e) {
      $stats->logError($e->getMessage());
  }
  

Extension Points

1. Custom Metrics Extend the StatsCollector interface to add fields:

   $stats->extend(function($collector) {
       $collector->set('custom_metric', $this->calculateCustomValue());
   });
   

2. Output Formats Override getStats() to return JSON/CSV:

   $stats->setFormatter(function($data) {
       return json_encode($data);
   });
   

3. Storage Backends Replace the default logger with a database writer:

   $stats->setLogger(new DatabaseLogger());