先确认 hyperf/metric 已启用且运行正常：检查 metric.php 中 enable_default_metric 为 true、use_standalone_process 推荐设为 true；访问 http://:9502/metrics 验证返回内容含实际指标数值；核对 namespace 前缀、prometheus 抓取配置、网络连通性及采集间隔一致性。
确认 hyperf/metric 是否启用并运行正常
很多情况下指标“不更新”其实是根本没采集起来。先检查 metric.php 配置中 enable_default_metric 是否为 true，且 use_standalone_process 推荐设为 true——Hyperf 多 Worker 进程下若不启用独立收集进程，指标会互相覆盖或丢失。
验证方式：直接访问 http://<your-hyperf-app>:9502/metrics</your-hyperf-app>（端口以 scrape_port 为准）。如果返回空或 404，说明 HTTP 指标服务未启动；若返回内容但全是 # HELP、# TYPE 而无实际数值行（如 hyperf_worker_request_count{...} 123），说明采集逻辑未触发。
常见卡点：
-
use_standalone_process => false时，需确保至少一个 Worker 进程已处理过请求（否则默认指标不会生成） - 环境变量
METRIC_DRIVER被误设为influxdb或其他非prometheus值 - 配置中
scrape_host设为127.0.0.1导致容器内 Prometheus 无法从外部访问
检查 Prometheus 的 scrape_interval 与 Hyperf 的 default_metric_interval 是否匹配
Prometheus 不会“实时”看到指标变化，它只按配置周期拉取。如果 scrape_interval: 15s，但 Hyperf 每 30 秒才刷一次内存使用量（default_metric_interval: 30），那你在 Grafana 里看到的 memory_usage 就会每 30 秒跳变一次，中间看似“冻结”。
更隐蔽的问题是：二者间隔差异过大可能引发数据稀疏。例如 Prometheus 每 5s 拉一次，而 Hyperf 每 60s 更新一次 GC 计数器，结果就是 12 个采样点里只有 1 个有值，其余为 NaN ——Grafana 默认不画线，看起来像“断更”。
建议统一设为 15s 或 30s，并在 metric.php 中显式声明：
return [
'default_metric_interval' => 15,
'metric' => [
'prometheus' => [
'scrape_port' => 9502,
// ...
],
],
];
排查 namespace 不一致导致的指标“消失”
Hyperf 默认所有指标加前缀 hyperf_，但如果你在 metric.php 里自定义了 namespace => 'myapp'，那实际暴露的指标名就变成 myapp_worker_request_count。而 Prometheus 配置或 Grafana 面板里写的还是 hyperf_worker_request_count，自然查不到数据。
验证方法：
- curl
http://hyperf-app:9502/metrics，看第一行指标是否带预期前缀 - 进 Prometheus 表达式浏览器，输入
count({__name__=~".*_worker_request_count"})，确认是否存在匹配指标 - Grafana 面板 JSON 中所有
expr字段，需全局替换前缀（不能只改一处）
特别注意：Hyperf 升级到 v3.2+ 后，namespace 默认值可能已变，旧面板不改会彻底失联。
确认 Prometheus 抓取目标状态为 UP 且无 timeout
进 Prometheus UI → Status → Targets，找到 hyperf job 对应的 target。如果状态是 DOWN 或显示 context deadline exceeded，说明网络或服务层有问题，不是指标逻辑问题。
典型原因：
- K8s Service 没把
9502端口正确暴露（Service 的ports[].targetPort必须对上 Hyperf 配置的scrape_port） - NetworkPolicy 阻止了 Prometheus Pod 到 Hyperf Pod 的 9502 端口访问
- Hyperf 所在节点启用了防火墙，或云厂商安全组未放行该端口
- Prometheus 配置里写的是
hyperf-app.default.svc.cluster.local:9502，但实际 Service 名叫hyperf-svc
快速验证：在 Prometheus Pod 内执行 curl -v http://hyperf-app:9502/metrics，看能否拿到响应体。拿不到就别调指标逻辑了，先通网络。
