feat: add aggregated job metrics calculation

Add ability to calculate aggregated metrics for a job class across all queues:
- CalculateAggregatedJobMetricsAction aggregates metrics across connection/queue combinations
- AggregatedJobMetricsData DTO with weighted averages for duration and memory
- Per-queue breakdown included in aggregated data
- Helper methods: hasFailures() and isHealthy() (failure rate < 5%)
- Weighted averages account for varying execution counts per queue

Author: sylvesterdamgaard

src/Actions/CalculateAggregatedJobMetricsAction.php

@@ -0,0 +1,111 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPeek\LaravelQueueMetrics\Actions;
+
+use Carbon\Carbon;
+use PHPeek\LaravelQueueMetrics\DataTransferObjects\AggregatedJobMetricsData;
+use PHPeek\LaravelQueueMetrics\Repositories\Contracts\JobMetricsRepository;
+
+/**
+ * Calculate aggregated metrics for a job class across all queues.
+ */
+final readonly class CalculateAggregatedJobMetricsAction
+{
+    public function __construct(
+        private JobMetricsRepository $repository,
+        private CalculateJobMetricsAction $calculateJobMetrics,
+    ) {}
+
+    public function execute(string $jobClass): AggregatedJobMetricsData
+    {
+        // Get all jobs from the discovery set
+        $allJobs = $this->repository->listJobs();
+
+        // Filter to find all connection/queue combinations for this job class
+        $jobQueues = array_filter($allJobs, fn (array $job): bool => $job['jobClass'] === $jobClass);
+
+        // If no queues found, return empty aggregated metrics
+        if (empty($jobQueues)) {
+            return new AggregatedJobMetricsData(
+                jobClass: $jobClass,
+                totalExecutions: 0,
+                totalFailures: 0,
+                avgDurationMs: 0.0,
+                avgMemoryMb: 0.0,
+                failureRate: 0.0,
+                throughputPerMinute: 0.0,
+                byQueue: [],
+                calculatedAt: Carbon::now(),
+            );
+        }
+
+        // Calculate metrics for each connection/queue combination
+        $byQueue = [];
+        $totalExecutions = 0;
+        $totalFailures = 0;
+        $weightedDuration = 0.0;
+        $weightedMemory = 0.0;
+        $totalThroughput = 0.0;
+
+        foreach ($jobQueues as $job) {
+            $metrics = $this->calculateJobMetrics->execute(
+                $job['jobClass'],
+                $job['connection'],
+                $job['queue']
+            );
+
+            $executions = $metrics->execution->totalProcessed;
+            $failures = $metrics->execution->totalFailed;
+
+            // Accumulate totals
+            $totalExecutions += $executions;
+            $totalFailures += $failures;
+
+            // Weighted averages (weight by number of executions)
+            if ($executions > 0) {
+                $weightedDuration += $metrics->duration->avg * $executions;
+                $weightedMemory += $metrics->memory->avg * $executions;
+            }
+
+            $totalThroughput += $metrics->throughput->perMinute;
+
+            // Calculate failure rate for this queue
+            $totalJobs = $executions + $failures;
+            $failureRate = $totalJobs > 0 ? ($failures / $totalJobs) * 100 : 0.0;
+
+            // Add to by_queue breakdown
+            $byQueue[] = [
+                'connection' => $job['connection'],
+                'queue' => $job['queue'],
+                'executions' => $executions,
+                'failures' => $failures,
+                'avg_duration_ms' => round($metrics->duration->avg, 2),
+                'avg_memory_mb' => round($metrics->memory->avg, 2),
+                'failure_rate' => round($failureRate, 2),
+                'throughput_per_minute' => round($metrics->throughput->perMinute, 2),
+            ];
+        }
+
+        // Calculate overall weighted averages
+        $avgDurationMs = $totalExecutions > 0 ? $weightedDuration / $totalExecutions : 0.0;
+        $avgMemoryMb = $totalExecutions > 0 ? $weightedMemory / $totalExecutions : 0.0;
+
+        // Calculate overall failure rate
+        $totalJobs = $totalExecutions + $totalFailures;
+        $failureRate = $totalJobs > 0 ? ($totalFailures / $totalJobs) * 100 : 0.0;
+
+        return new AggregatedJobMetricsData(
+            jobClass: $jobClass,
+            totalExecutions: $totalExecutions,
+            totalFailures: $totalFailures,
+            avgDurationMs: $avgDurationMs,
+            avgMemoryMb: $avgMemoryMb,
+            failureRate: $failureRate,
+            throughputPerMinute: $totalThroughput,
+            byQueue: $byQueue,
+            calculatedAt: Carbon::now(),
+        );
+    }
+}

src/DataTransferObjects/AggregatedJobMetricsData.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPeek\LaravelQueueMetrics\DataTransferObjects;
+
+use Carbon\Carbon;
+
+/**
+ * Aggregated metrics for a job class across all queues.
+ */
+final readonly class AggregatedJobMetricsData
+{
+    /**
+     * @param  array<array{connection: string, queue: string, executions: int, avg_duration_ms: float, avg_memory_mb: float, failures: int, failure_rate: float, throughput_per_minute: float}>  $byQueue
+     */
+    public function __construct(
+        public string $jobClass,
+        public int $totalExecutions,
+        public int $totalFailures,
+        public float $avgDurationMs,
+        public float $avgMemoryMb,
+        public float $failureRate,
+        public float $throughputPerMinute,
+        public array $byQueue,
+        public Carbon $calculatedAt,
+    ) {}
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function toArray(): array
+    {
+        return [
+            'job_class' => $this->jobClass,
+            'total_executions' => $this->totalExecutions,
+            'total_failures' => $this->totalFailures,
+            'avg_duration_ms' => round($this->avgDurationMs, 2),
+            'avg_memory_mb' => round($this->avgMemoryMb, 2),
+            'failure_rate' => round($this->failureRate, 2),
+            'throughput_per_minute' => round($this->throughputPerMinute, 2),
+            'by_queue' => $this->byQueue,
+            'calculated_at' => $this->calculatedAt->toIso8601String(),
+        ];
+    }
+
+    public function hasFailures(): bool
+    {
+        return $this->totalFailures > 0;
+    }
+
+    public function isHealthy(): bool
+    {
+        return $this->failureRate < 5.0;
+    }
+}