# Metrics

Queuety provides a metrics API that computes per-handler statistics from the log table. Use it for monitoring, dashboards, and alerting.

## Handler statistics

Get metrics for all handlers within a time window:

```php
$stats = Queuety::metrics()->handler_stats( 60 ); // last 60 minutes
```

Each entry in the returned array contains:

| Field | Description |
|---|---|
| `handler` | Handler name |
| `completed` | Number of successful executions |
| `failed` | Number of failed executions |
| `avg_ms` | Average execution duration in milliseconds |
| `p95_ms` | 95th percentile execution duration |
| `error_rate` | Failure rate as a percentage |

## CLI

```bash
# Metrics for the last 60 minutes (default)
wp queuety metrics

# Metrics for the last 24 hours
wp queuety metrics --minutes=1440

# JSON output
wp queuety metrics --format=json
```

Example output:

```
+------------------+-----------+--------+--------+--------+------------+
| handler          | completed | failed | avg_ms | p95_ms | error_rate |
+------------------+-----------+--------+--------+--------+------------+
| send_email       | 142       | 3      | 45     | 120    | 2.07%      |
| process_image    | 87        | 0      | 230    | 450    | 0.00%      |
| call_openai      | 31        | 5      | 2100   | 4500   | 13.89%     |
+------------------+-----------+--------+--------+--------+------------+
```

## Use cases

- **Dashboard widgets.** Display throughput and error rates in the WordPress admin.
- **Health checks.** Alert when a handler's error rate exceeds a threshold.
- **Performance tuning.** Identify slow handlers using `p95_ms` and optimize them.
- **Capacity planning.** Track throughput trends to size your worker pool.