必须在Job类handle()方法中手动埋点并启用hyperf/metric组件，否则Prometheus无法采集队列积压、消费速率、失败率等指标，Grafana面板将显示“no data”。
企业级Hyperf异步队列监控面板搭建，需让Prometheus抓取到真实队列积压、消费速率、失败重试等核心指标，并在Grafana中可视化呈现——跳过自定义埋点与指标暴露环节，所有面板将显示“no data”。
确认Hyperf异步队列指标已暴露
Hyperf的hyperf/async-queue组件本身不主动上报队列深度、失败次数等业务指标，必须通过hyperf/metric手动注册并采集。若未启用metric组件或未在Job类中埋点，Prometheus将无法获取任何有效数据。
检查config/autoload/metric.php中'enable_default_metric' => true已开启，且'default' => 'prometheus'配置正确。
在你的Job类（如App\Job\SendEmailJob）中，注入MetricFactoryInterface，并在handle()方法开头添加计数器：
$this->metricFactory->makeCounter('async_queue_job_total', ['status'])->with('success')->add(1);
在catch块中补上失败计数：$this->metricFactory->makeCounter('async_queue_job_total', ['status'])->with('failed')->add(1);
【关键前提】必须在Job执行入口处埋点，不能只在投递侧统计——投递成功不等于消费成功，监控目标是消费链路而非发送链路。
配置Prometheus抓取async-queue指标
编辑prometheus.yml，新增一个独立job，专门抓取Hyperf应用暴露的/metrics端点：
scrape_configs:
- job_name: 'hyperf-async-queue'
scrape_interval: 5s
static_configs:
- targets: ['host.docker.internal:9502']
注意：target地址必须与config/autoload/metric.php中'scrape_host'和'scrape_port'一致；Docker环境下宿主机Redis或Hyperf服务用host.docker.internal，Linux物理机请替换为实际内网IP。
重启Prometheus容器，访问http://localhost:9090/targets，确认hyperf-async-queue状态为UP。若显示connection refused，说明Hyperf未启动或metric服务未监听指定端口。
构建Grafana核心监控看板
登录Grafana（默认http://localhost:3000），进入Create → Import，上传Hyperf官方提供的src/metric/grafana.json（路径以实际项目为准）。
若无现成JSON文件，可手动创建新Dashboard，添加以下三个核心Panel：
① 队列积压量（实时）：
Metrics字段填：hyperf_async_queue_length{job="hyperf-async-queue"}
该指标需你在Job类中用Gauge类型主动维护，例如在消费前$gauge->set($length)，否则该查询始终返回空。
② 每秒成功消费数：
Metrics字段填：rate(async_queue_job_total{status="success"}[1m])
使用rate()而非irate()，避免瞬时毛刺干扰趋势判断。
③ 失败率（滚动5分钟）：
Metrics字段填：sum(rate(async_queue_job_total{status="failed"}[5m])) / (sum(rate(async_queue_job_total{status="success"}[5m])) + sum(rate(async_queue_job_total{status="failed"}[5m])))
分母必须包含success与failed之和，仅用total会导致分母缺失标签而计算失败。
每个Panel右上角设置Alert规则：失败率持续3分钟＞5% → 触发通知；积压量＞1000且增速＞50条/分钟 → 触发高优告警。
