# 指标

Queuety 提供一个指标 API，用于根据日志表计算各处理器的统计数据。可用于监控、仪表盘和告警。

## 处理器统计数据

获取指定时间范围内所有处理器的指标：

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

返回数组中的每个条目都包含：

| 字段 | 描述 |
|---|---|
| `handler` | 处理器名称 |
| `completed` | 成功执行次数 |
| `failed` | 失败尝试次数（`failed` 和 `buried` 日志事件，因此同一个作业可能计数多次） |
| `avg_ms` | 平均执行时长（毫秒） |
| `p95_ms` | 执行时长的第 95 百分位数 |
| `error_rate` | 0 到 1 之间的失败率：`failed / (completed + failed)`，四舍五入到小数点后四位 |

## 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
```

输出示例：

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

## 使用场景

- **仪表盘组件。** 在 WordPress 管理后台中显示吞吐量和错误率。
- **运行状况检查。** 当处理器的错误率超过阈值时发出告警。
- **性能调优。** 使用 `p95_ms` 找出速度较慢的处理器并进行优化。
- **容量规划。** 跟踪吞吐量趋势，以确定工作进程池的规模。