README

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

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

能力清单

能力	说明
Jaeger 链路追踪	生成 128-bit TraceID、64-bit SpanID，按父子关系串联 HTTP、GRPC、MySQL、Redis、MQ、业务 span。
Loki 结构化日志	输出 JSON 日志，自动携带 `service`、`project`、`env`、`trace_id`、`span_id`、`component` 等字段。
Prometheus 指标	暴露 `/metrics` 端点，提供 Counter、Histogram、Gauge 类型指标。
AOP 自动埋点	基于 Hyperf AOP 自动拦截 Controller、GRPC、MySQL、Redis、MQ、异步队列调用。
手动埋点 API	提供 `TraceHelper`、`MetricHelper`、`LogHelper`，用于自定义业务链路、指标和日志。
多项目多环境隔离	所有链路、日志、指标都带 `service`、`project`、`env` 标签。
Grafana 拆分看板	总览、HTTP、GRPC、MySQL、Redis、MQ、日志链路独立看板，避免单页查询过重。
Jaeger + Loki 联动	Loki 日志可通过 `trace_id` 跳转 Jaeger，Jaeger Trace 可反查同 TraceID 日志。

适用场景

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

服务地址：

服务	地址
Demo API	http://localhost:9501
Grafana	http://localhost:3000
Jaeger	http://localhost:16686
Prometheus	http://localhost:9090
Loki	http://localhost:3100

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

Demo 路由

路由	说明
`GET /`	基础健康检查，返回当前 TraceID。
`GET /order`	正常下单链路，包含 Redis、MySQL、GRPC、MQ、业务 span。
`GET /simulate`	随机模拟正常、慢 SQL、超时、库存不足、支付失败、MQ 重试。
`GET /grpc-demo`	模拟 GRPC 调用。
`GET /error`	触发异常链路和错误日志。
`GET /metrics`	Prometheus 指标暴露端点。

常用查询

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

文档目录

文档	内容
完整配置说明	全局、Tracing、Logging、Metrics、组件、AOP、采集、脱敏配置。
AOP 自动埋点与手动埋点 API	自动埋点范围、手动 span、指标、日志、TraceID 传播。
指标字典与 PromQL	指标命名规则、标签说明、HTTP/GRPC/MySQL/Redis/MQ 指标清单。
Jaeger 链路追踪指南	Jaeger 上报、采样、查询、异常链路、Loki 联动。
Grafana 与 Loki 使用指南	看板、LogQL、TraceID 跳转 Jaeger、Jaeger 反查日志。
Docker 本地演示环境	一键启动、持续造数、服务地址、验证流程。
生产环境建议	采样率、性能、安全、容量、故障排查建议。
验收与排障清单	启动服务、持续造数、指标/日志/链路/Grafana 跳转验收命令。

交付内容

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/

netfly / hyperf-observability

Maintainers

Package info

Statistics

Security