README

Netfly Hyperf Observability 是一个面向 Hyperf/PHP 项目的可观测性 Composer 组件包，覆盖 Jaeger 链路追踪、Loki 结构化日志、Prometheus 指标采集 三类能力，并提供 Grafana、Loki、Promtail、Prometheus、Jaeger 的本地一键演示环境。

组件支持 AOP 自动埋点 和 手动业务埋点 两种模式。业务项目接入后，可以在低侵入甚至零改造的情况下采集 HTTP、GRPC、MySQL、Redis、MQ 等核心组件的调用链路、结构化日志和监控指标。

能力清单

适用场景

• Hyperf 微服务项目需要快速补齐链路追踪、日志检索、指标监控。
• 多项目、多环境部署，需要按 project 和 env 隔离观测数据。
• 需要通过 Jaeger 定位慢链路、异常链路、跨组件调用耗时。
• 需要通过 Grafana 查看各组件 QPS、错误率、耗时分布、连接池、MQ 堆积。
• 需要通过 Loki 按 TraceID、组件、错误级别、关键词检索结构化日志。

快速接入

1. 安装 Composer 包

composer require netfly/hyperf-observability
php bin/hyperf.php vendor:publish netfly/hyperf-observability

发布后会生成 Hyperf 配置文件：

config/autoload/observability.php

如果项目没有自动注册 /metrics 路由，可以手动添加：

use Hyperf\HttpServer\Router\Router;
use Netfly\HyperfObservability\Metrics\MetricsController;

Router::get('/metrics', [MetricsController::class, 'index']);

2. 最小环境变量

OBSERVABILITY_ENABLED=true
OBS_SERVICE_NAME=order-service
OBS_PROJECT=mall
OBS_ENV=dev

OBS_TRACE_ENABLED=true
OBS_JAEGER_ENDPOINT=http://jaeger:9411/api/v2/spans
OBS_TRACE_SAMPLE_RATE=1.0

OBS_LOGGING_ENABLED=true
OBS_METRICS_ENABLED=true
OBS_CAPTURE_REQUEST=true
OBS_CAPTURE_RESPONSE=false
OBS_SANITIZE_ENABLED=true

3. 验证接入

启动业务服务后按顺序检查：

curl http://127.0.0.1:9501/metrics

预期能看到类似指标：

hyperf_http_requests_total{service="order-service",project="mall",env="dev",component="http",route="/order",method="GET",status="200"} 1

然后在 Jaeger 查询服务名 order-service，在 Grafana Loki 中查询：

{service="order-service", env="dev"}

本地完整演示

启动 Grafana、Loki、Promtail、Prometheus、Jaeger 和 Hyperf Demo：

docker compose up -d --build

后台持续造数据：

docker compose --profile demo-data up -d demo-loadgen

停止持续造数：

docker compose stop demo-loadgen

服务地址：

Grafana 默认账号密码为 admin / admin，当前演示环境也启用了匿名 Admin 访问。

Demo 路由

常用查询

Prometheus HTTP QPS：

sum(rate(hyperf_http_requests_total{service="netfly-demo",env="dev"}[5m])) by (route,status)

Prometheus HTTP P99：

histogram_quantile(0.99, sum(rate(hyperf_http_request_duration_seconds_bucket{service="netfly-demo",env="dev"}[5m])) by (le,route))

Loki 按 TraceID 查日志：

{service="netfly-demo", env="dev"} | json | extra_trace_id="TRACE_ID"

Loki 查错误：

{service="netfly-demo", env="dev", level="ERROR"} | json

文档目录

交付内容

• Composer 包源码：src/
• 默认配置：config/observability.php
• Docker 演示环境：docker-compose.yml、docker/
• Jaeger 采样配置：docker/jaeger/sampling.json
• Hyperf Demo 项目：demo/
• Grafana 拆分看板：docker/grafana/dashboards/
• 中文使用、配置、部署文档：README.md、docs/