hyperf服务监控需确保metric组件暴露指标、prometheus稳定抓取、grafana正确关联数据源；须验证/metrics接口可用性、prometheus target可达性、grafana数据源健康及promql前缀匹配，并注意业务指标需在协程内上报。
Hyperf 服务监控不是“配完就能用”，关键在于 metric 组件是否真正暴露了指标、Prometheus 是否能稳定抓取、Grafana 是否正确关联数据源——三者任一环节断开，仪表盘就成空壳。
确认 /metrics 接口是否真实可用
很多问题其实卡在第一步：Hyperf 根本没把指标吐出来。默认配置下，use_standalone_process 必须为 true，否则指标采集会和业务协程争抢资源，甚至因超时导致接口返回空或 500。
-
scrape_host不能写127.0.0.1或localhost（Docker 容器内解析失败），应设为0.0.0.0 -
scrape_port需确保未被其他进程占用，且宿主机或容器网络能通（例如 Docker Compose 中用host.docker.internal指向宿主） - 手动 curl 测试：
curl http://localhost:9502/metrics，看到类似# TYPE hyperf_worker_request_count counter才算成功 - 若返回空或 Connection refused，先检查
php bin/hyperf.php process:list是否有MetricProcess在运行
Prometheus 抓取配置常见失效点
Prometheus 不是“配了 job 就自动干活”，它对 target 地址的可达性极其敏感，尤其在容器环境下。
- Docker Compose 中，
targets: ['host.docker.internal:9502']是 Mac/Windows 的解法；Linux 需改用宿主机真实 IP 或用network_mode: "host" -
scrape_interval: 5s太短可能压垮 Hyperf 监控进程，生产建议调至15s或30s - 抓取失败时，进 Prometheus Web UI 的
Status > Targets页面，看对应 job 状态和报错（如context deadline exceeded通常意味着网络不通或端口拒绝） - 不要复用
job_name: 'hyperf'，多个实例需区分，比如job_name: 'hyperf-api'和job_name: 'hyperf-worker'
Grafana 导入 Dashboard 前必须校验的两件事
直接导入 grafana.json 很快，但若跳过校验，面板里全是“no data”。
- 先确认 Prometheus 数据源已添加并显示
Healthy，URL 填的是http://prometheus:9090（容器名）或http://localhost:9090（本地） - 导入 JSON 后，打开任意面板，点击右上角
Inspect > Metrics，看实际执行的 PromQL 是否能返回结果，例如：sum(rate(hyperf_worker_request_count[5m])) - Hyperf 默认指标带命名空间前缀（如
hyperf_），若自定义了namespace（如'namespace' => 'myapp'），所有 Grafana 面板里的 PromQL 都得同步替换前缀 - 时间范围选太小（如 Last 5 minutes）也可能看不到数据，建议先切到
Last 6 hours观察趋势
自定义业务指标上报容易漏掉的初始化时机
用 Metric::counter('order_paid_total')->inc() 时，如果在非协程安全上下文（如 __construct 或静态属性初始化）中调用，指标会丢失或报错。
- 必须在协程内调用：Controller 方法、Listener、Job handle、自定义 Process 的
handle()中都 OK - 避免在
Di容器构建阶段或ConfigProvider中提前 new 实例并调用inc() - Counter 类型不支持减操作，误用
dec()会静默失败；需要增减的场景请改用Gauge - 直方图
histogram的observe($value)要传 float，传 int 可能触发类型警告（PHP 8.1+）
最常被忽略的是：Hyperf 的 /metrics 是独立进程暴露的，它不走 HTTP Server 的中间件链，所以 Nginx 反向代理、SSL 终止、路径重写这些都可能拦住 Prometheus 的抓取请求——调试时绕过代理直连 9502 端口，往往一眼定位问题。
