Yammi Jobs Monitoring Laravel Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require romalytar/yammi-jobs-monitoring-laravel
   php artisan vendor:publish --provider="RomaLytar\YammiJobsMonitor\YammiJobsMonitorServiceProvider" --tag="migrations"
   php artisan migrate
   

   • Publishes migrations and config. Run migrations to create the monitoring tables.

2. First Use Case:

   • Dispatch a job and immediately access the dashboard at /jobs-monitor.
   • Example job dispatch:

     dispatch(new ProcessPayment($userId));
     

   • The dashboard will show job lifecycle (queued, processing, completed, failed) in real-time.

3. Quick Wins:

   • Dead Letter Queue (DLQ): Failed jobs auto-populate the DLQ with payloads and error details.
   • Worker Heartbeats: Monitor worker uptime and latency via the dashboard’s "Workers" tab.
   • Alerts: Configure alerts (e.g., Slack) in .env (e.g., YAMMI_SLACK_WEBHOOK_URL) to notify on failures or anomalies.

Implementation Patterns

Core Workflows

1. Job Lifecycle Tracking:

   • Automatic Integration: No manual instrumentation needed. The package hooks into Laravel’s queue system via events (job.processing, job.failed, etc.).
   • Custom Jobs: Extend YammiJobsMonitor\Contracts\MonitorableJob for custom job metadata:

     use YammiJobsMonitor\Contracts\MonitorableJob;
     
     class ProcessPayment implements MonitorableJob {
         public function getMonitoringMetadata(): array {
             return ['user_id' => $this->userId, 'amount' => $this->amount];
         }
     }
     

2. Alerting System:

   • Configure Alerts: Define thresholds in config/yammi.php:

     'alerts' => [
         'failure_threshold' => 3, // Retry 3 times before alerting
         'duration_threshold' => 60, // Alert if job takes >60s
     ],
     

   • Supported Channels: Slack, Email, PagerDuty, Opsgenie, or custom webhooks. Example Slack setup:

     YAMMI_SLACK_WEBHOOK_URL=https://hooks.slack.com/...
     YAMMI_ALERT_CHANNELS=slack
     

3. Scheduled Tasks:

   • Monitor schedule:run jobs by wrapping them in YammiJobsMonitor\Jobs\ScheduledTaskJob:

     ScheduledTaskJob::dispatch($command)->onQueue('scheduled');
     

4. Worker Management:

   • Heartbeat Configuration: Workers auto-register via YammiJobsMonitor\Workers\WorkerHeartbeat. Customize heartbeat interval in config:

     'worker_heartbeat' => [
         'interval' => 30, // Seconds
     ],
     

   • Worker Dashboard: View active workers, their queues, and response times in /jobs-monitor/workers.

5. Dead Letter Queue (DLQ):

   • Access DLQ: Navigate to /jobs-monitor/dlq to inspect failed jobs.
   • Retry/Requeue: Use the dashboard UI or API to manually retry jobs:

     YammiJobsMonitor::retryFailedJob($failedJobId);
     

Integration Tips

• Queue Drivers: Works seamlessly with Redis, SQS, Database, and Sync queues. No driver-specific setup required.
• Existing Jobs: Use the YammiJobsMonitor\Traits\Monitorable trait to retroactively enable monitoring:

  use YammiJobsMonitor\Traits\Monitorable;
  
  class LegacyJob {
      use Monitorable;
  }
  

• API Access: Fetch job data via HTTP (e.g., /api/jobs?queue=default) or Laravel’s HTTP client:

  $jobs = Http::get('/api/jobs')->json();
  

Gotchas and Tips

Pitfalls

1. Performance Overhead:

   • Issue: Monitoring adds minimal overhead (~5-10ms per job). For high-throughput queues, consider batching heartbeats or alerts.
   • Fix: Adjust worker_heartbeat.interval to balance granularity and performance.

2. Database Bloat:

   • Issue: Long-running jobs or high failure rates may bloat the failed_jobs table.
   • Fix: Configure automatic cleanup in config/yammi.php:

     'cleanup' => [
         'failed_jobs_ttl' => 30, // Days to retain failed jobs
     ],
     

     Run the cleanup manually:

     php artisan yammi:cleanup
     

3. Alert Fatigue:

   • Issue: Over-alerting on transient failures (e.g., network blips).
   • Fix: Use failure_threshold and fingerprinting to ignore duplicate failures:

     'alerts' => [
         'fingerprint_fields' => ['exception', 'payload_hash'], // Group similar failures
     ],
     

4. Worker Heartbeat Desync:

   • Issue: Workers may appear offline if heartbeats are missed (e.g., due to long-running jobs).
   • Fix: Reduce worker_heartbeat.interval or implement a secondary heartbeat mechanism (e.g., cron job ping).

5. Queue Driver Quirks:

   • SQS: Ensure IAM permissions allow SQS visibility timeouts to be extended (required for long jobs).
   • Database: Monitor jobs table growth; consider archiving old jobs.

Debugging

1. Missing Jobs in Dashboard:

   • Check: Verify the YammiJobsMonitorServiceProvider is registered in config/app.php.
   • Logs: Tail storage/logs/laravel.log for YammiJobsMonitor events.

2. Alerts Not Triggering:

   • Check: Validate .env alert configurations (e.g., YAMMI_SLACK_WEBHOOK_URL).
   • Test: Manually trigger an alert via:

     YammiJobsMonitor::alert('test', 'Test alert', ['channel' => 'slack']);
     

3. Dashboard Not Loading:

   • Check: Run migrations and clear cache:

     php artisan migrate
     php artisan view:clear
     php artisan cache:clear
     

Extension Points

1. Custom Alert Channels:

   • Implement RomaLytar\YammiJobsMonitor\Contracts\AlertChannel:

     class CustomChannel implements AlertChannel {
         public function send(Alert $alert) {
             // Send to your custom system (e.g., Teams, Datadog)
         }
     }
     

   • Register in config/yammi.php:

     'alert_channels' => [
         'custom' => \App\Alerts\CustomChannel::class,
     ],
     

2. Custom Job Metadata:

   • Override getMonitoringMetadata() in jobs to include business-specific data (e.g., order IDs, user segments).

3. Dashboard Extensions:

   • Publish views and extend the dashboard:

     php artisan vendor:publish --provider="RomaLytar\YammiJobsMonitor\YammiJobsMonitorServiceProvider" --tag="views"
     

   • Add custom tabs by extending YammiJobsMonitor\Dashboard.

4. Bulk Actions:

   • Use the API to manage jobs programmatically:

     // Retry all failed jobs for a queue
     YammiJobsMonitor::retryFailedJobsForQueue('emails');
     

5. Integration with Observability Tools:

   • Export metrics to Prometheus or Datadog by extending the YammiJobsMonitor\Metrics\MetricEmitter trait.

```markdown
### Pro Tips
- **Anomaly Detection**: Leverage `duration_threshold` to catch slow jobs early. Example:
  ```php
  'alerts' => [
      'duration_threshold' => 30, // Alert if job takes >30s (vs. avg 5s)
  ],

• Queue Prioritization: Use the dashboard to identify bottlenecks (e.g., emails queue stuck due to SMTP issues).
• Incident Response: Combine with laravel-debugbar to correlate job failures with server metrics.
• CI/CD: Add a yammi:cleanup step to your deploy script to prune old monitoring data.