PHPackages netfly/netfly-observability - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Logging & Monitoring](/categories/logging) 4. / 5. netfly/netfly-observability ActiveLibrary[Logging & Monitoring](/categories/logging) netfly/netfly-observability =========================== Hyperf observability package for Prometheus metrics and Loki structured logging 00PHPCI failing Since Jun 9Pushed 1w agoCompare [ Source](https://github.com/lanzengwei/netfly-observability)[ Packagist](https://packagist.org/packages/netfly/netfly-observability)[ RSS](/packages/netfly-netfly-observability/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependenciesVersions (2)Used By (0) Netfly Hyperf Observability =========================== [](#netfly-hyperf-observability) 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 包 [](#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. 最小环境变量 [](#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. 验证接入 [](#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 APIGrafanaJaegerPrometheusLokiGrafana 默认账号密码为 `admin` / `admin`，当前演示环境也启用了匿名 Admin 访问。 Demo 路由 ------- [](#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 ``` 文档目录 ---- [](#文档目录) 文档内容[完整配置说明](docs/configuration.md)全局、Tracing、Logging、Metrics、组件、AOP、采集、脱敏配置。[AOP 自动埋点与手动埋点 API](docs/instrumentation.md)自动埋点范围、手动 span、指标、日志、TraceID 传播。[指标字典与 PromQL](docs/metrics.md)指标命名规则、标签说明、HTTP/GRPC/MySQL/Redis/MQ 指标清单。[Jaeger 链路追踪指南](docs/jaeger.md)Jaeger 上报、采样、查询、异常链路、Loki 联动。[Grafana 与 Loki 使用指南](docs/grafana-loki.md)看板、LogQL、TraceID 跳转 Jaeger、Jaeger 反查日志。[Docker 本地演示环境](docs/docker-demo.md)一键启动、持续造数、服务地址、验证流程。[生产环境建议](docs/production.md)采样率、性能、安全、容量、故障排查建议。[验收与排障清单](docs/acceptance.md)启动服务、持续造数、指标/日志/链路/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/` ### Health Score 21 — LowBetter than 17% of packages Maintenance64 Regular maintenance activity Popularity0 Limited adoption so far Community6 Small or concentrated contributor base Maturity13 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Community Maintainers ![](https://avatars.githubusercontent.com/u/10137591?v=4)[lzw](/maintainers/lanzengwei)[@lanzengwei](https://github.com/lanzengwei) --- Top Contributors [![lanzengwei](https://avatars.githubusercontent.com/u/10137591?v=4)](https://github.com/lanzengwei "lanzengwei (1 commits)") ### Embed Badge ![Health badge](/badges/netfly-netfly-observability/health.svg) ``` [![Health](https://phpackages.com/badges/netfly-netfly-observability/health.svg)](https://phpackages.com/packages/netfly-netfly-observability) ``` ### Alternatives [psr/log Common interface for logging libraries 10.4k1.2B11.9k](/packages/psr-log)[open-telemetry/api API for OpenTelemetry PHP. 2041.5M289](/packages/open-telemetry-api)[open-telemetry/sdk SDK for OpenTelemetry PHP. 2428.5M356](/packages/open-telemetry-sdk) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)