hyperf监控多进程定时任务的核心是让任务可观测、可采集、可聚合，需通过hyperf/metric在execute前后上报生命周期、执行结果等指标，所有指标必须在协程内调用，并确保use_standalone_process=true、/metrics接口可用、prometheus targets配置正确、grafana promql前缀匹配命名空间。
Hyperf 监控多进程定时任务运行状态，核心不是“写个接口查一下”，而是让任务本身可被观测、可被采集、可被聚合。关键在于把定时任务的生命周期、执行结果、失败次数等指标暴露出来，并接入 Prometheus + Grafana 这套标准链路。
让定时任务主动上报指标
Hyperf 的 hyperf/crontab 本身不自带指标上报，需手动集成 hyperf/metric 组件，在任务执行前后打点：
- 在
execute()方法开头记录开始时间、任务名称、实例 ID（可用getmypid()或Swoole\Coroutine::id()） - 执行完成后，用
MetricFactory::getCounter()上报成功/失败次数，例如：counter('crontab_task_result_total', ['task' => $this->name, 'status' => 'success'])->add(1); - 用
Gauge记录当前是否正在运行（避免并发重入时误判），例如：gauge('crontab_task_running', ['task' => $this->name])->set(1);执行完设为 0 - 所有指标必须在协程内调用，否则可能丢失或上报失败
暴露统一的 /crontab-status 接口（可选但实用）
除了 Prometheus 抓取，也可提供一个轻量 HTTP 接口供运维或前端轮询，返回结构化状态：
- 路由定义：
GET /api/v1/crontab/status - 响应内容包含：
– 已注册任务总数
– 当前活跃任务数（通过CrontabManager::getTasks()获取并过滤状态）
– 每个任务的最近执行时间、耗时、结果（需任务类自行缓存执行日志）
– 是否启用、规则、是否加锁 - 注意：该接口不应实时遍历所有任务执行状态（开销大），建议用内存表（
Swoole\Table）或 Redis 缓存最近一次执行快照，每秒更新一次
Prometheus 抓取配置要点
确保指标能被 Prometheus 正确采集，重点检查：
-
metric组件已启用且use_standalone_process = true，否则指标可能因协程抢占而丢失 -
/metrics接口返回内容中包含类似# TYPE crontab_task_result_total counter的行 - Prometheus 的
scrape_configs中 targets 指向正确地址（Docker 环境慎用127.0.0.1，推荐host.docker.internal或宿主真实 IP） - 抓取间隔建议 ≥15s，避免高频请求压垮 metric 进程
Grafana 面板关键 PromQL 示例
导入 Dashboard 前，先验证以下查询能否返回数据：
- 各任务执行成功率：
sum by (task) (rate(crontab_task_result_total{status="success"}[1h])) / sum by (task) (rate(crontab_task_result_total[1h])) - 当前正在运行的任务数：
sum(crontab_task_running) - 最近 5 分钟失败次数 Top 3：
topk(3, sum by (task) (rate(crontab_task_result_total{status="failed"}[5m]))) - 若自定义了命名空间（如
namespace => 'myapp'），所有 PromQL 中的指标名前缀要同步替换为myapp_crontab_...
