PHPackages                             php-observability/prometheus-kit - 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. php-observability/prometheus-kit

ActiveLibrary[Logging & Monitoring](/categories/logging)

php-observability/prometheus-kit
================================

PHP observability kit for Prometheus + Grafana — HTTP/DB/Redis/RabbitMQ metrics, tracing, logging. Supports ThinkPHP5, Hyperf, and standalone PHP.

v2.0.0(yesterday)00MITPHPPHP >=7.4

Since Jun 8Pushed yesterdayCompare

[ Source](https://github.com/lanzengwei/php-observability)[ Packagist](https://packagist.org/packages/php-observability/prometheus-kit)[ RSS](/packages/php-observability-prometheus-kit/feed)WikiDiscussions main Synced yesterday

READMEChangelogDependencies (3)Versions (4)Used By (0)

PHP Observability — Prometheus + Grafana 可观测性套件
===============================================

[](#php-observability--prometheus--grafana-可观测性套件)

一个开箱即用的 PHP Composer 包，为 **ThinkPHP 5**、**Hyperf** 和 **纯 PHP** 项目提供系统级性能监控。**接入后自动采集，无需在业务代码中手动埋点。**

- HTTP 请求 QPS / 延迟 / 错误率
- MySQL 查询性能、慢查询
- Redis 命令性能、慢命令、错误
- RabbitMQ / 队列操作性能与错误
- 请求链路追踪（trace\_id / span）
- 结构化 JSON 日志（可开关）

快速开始
----

[](#快速开始)

### 1. 安装

[](#1-安装)

```
composer require php-observability/prometheus-kit
```

### 2. 复制配置文件

[](#2-复制配置文件)

```
cp vendor/php-observability/prometheus-kit/config/observability.php config/observability.php
```

只需修改 `project`、`app_name` 和 Redis 地址，其余保持默认即可。多项目共用一套监控栈时，每个项目配置不同的 `project` 即可在 Grafana 中筛选。

### 3. 按框架接入（仅注册，无埋点代码）

[](#3-按框架接入仅注册无埋点代码)

#### ThinkPHP 5

[](#thinkphp-5)

```
// application/tags.php

return [

    'app_begin' => ['\\PhpObservability\\Bridge\\ThinkPHP5\\Service'],

];

// application/middleware.php

return [

    \\PhpObservability\\Bridge\\ThinkPHP5\\Middleware::class,

];

// application/extra/observability.php — 复制配置文件
```

完成。`Service` 启动时自动注册框架原生钩子，业务代码零改动。

#### Hyperf

[](#hyperf)

```
composer require php-observability/prometheus-kit

php bin/hyperf.php vendor:publish php-observability/prometheus-kit
```

安装后自动注册中间件与事件监听器，配置文件发布到 `config/autoload/observability.php`。

#### 纯 PHP

[](#纯-php)

```
require 'vendor/autoload.php';

\PhpObservability\Bridge\Standalone\Bootstrap::init(__DIR__ . '/config/observability.php');

// 在路由入口包裹 HTTP 请求（仅此一行接入代码）

\PhpObservability\Bridge\Standalone\Bootstrap::handleHttp($method, $path, $handler);
```

纯 PHP 无框架事件机制，HTTP 与异常自动采集；数据库/Redis 需通过框架或连接池才能自动拦截（见下方说明）。

### 4. 暴露 /metrics 端点

[](#4-暴露-metrics-端点)

各框架桥接已自动处理。Prometheus 抓取地址：

```

http://your-app-host/metrics

```

### 5. 部署 Grafana 监控栈（独立项目）

[](#5-部署-grafana-监控栈独立项目)

```
git clone

cd php-observability-stack

cp .env.example .env

docker compose up -d
```

详见 [php-observability-stack](../php-observability-stack/README.md)。

自动采集机制（无需手动埋点）
--------------

[](#自动采集机制无需手动埋点)

| 监控项 | ThinkPHP 5 | Hyperf | 纯 PHP |

|--------|-----------|--------|--------|

| HTTP 请求 | 中间件自动 | 中间件自动 | `handleHttp()` 自动 |

| MySQL 查询 | `Db::listen()` 原生钩子 | `QueryExecuted` 事件 | 需框架或连接池 |

| Redis | 自动替换 cache/session 驱动 | `CommandExecuted` 事件 | 需框架或连接池 |

| RabbitMQ | think-queue 钩子（如已安装） | `AfterProduce` / `AfterConsume` 事件 | 需框架 |

| 异常 / 错误 | 中间件 + `app_exception` 钩子 | `HandlerFailed` 事件 | 全局异常处理 |

| 链路追踪 | 中间件自动创建 Span | 中间件自动 | `handleHttp()` 自动 |

| 日志 | 自动写入 observability.log | 自动写入 | 自动写入 |

### ThinkPHP 5 自动原理

[](#thinkphp-5-自动原理)

- **SQL**：复用 `think\Db::listen()`，框架每次执行 SQL 后回调
- **Redis**：启动时自动将 `cache.type=redis` 替换为可观测驱动类，透明代理所有缓存操作
- **Session Redis**：同上，自动替换 `session.type=redis`
- **队列**：如安装了 `topthink/think-queue`，监听 `queue_job_processed` / `queue_job_failed` 钩子
- **HTTP / 异常**：中间件拦截请求，钩子记录未捕获异常

### Hyperf 自动原理

[](#hyperf-自动原理)

- **SQL**：监听 `Hyperf\Database\Events\QueryExecuted`
- **Redis**：监听 `Hyperf\Redis\Event\CommandExecuted`（需 `hyperf/redis`）
- **AMQP**：监听 `AfterProduce` / `AfterConsume` / `FailTo*` 事件（需 `hyperf/amqp`）
- **异常**：监听 `Hyperf\ExceptionHandler\Event\HandlerFailed`
- **HTTP**：PSR-15 中间件自动注册

配置说明
----

[](#配置说明)

```
return [

    'enabled' => true,                    // 总开关

    'project' => 'order-system',          // 项目标识（Grafana 按项目筛选）

    'app_name' => 'api-gateway',          // 服务名（同项目下可有多个服务）

    'environment' => 'production',

    'metrics' => [

        'enabled' => true,

        'path' => '/metrics',

        'storage' => 'redis',             // redis | apcu | in_memory

        'slow_query_threshold' => 1.0,    // 慢查询阈值（秒）

        'slow_redis_threshold' => 0.1,

    ],

    'tracing' => [

        'enabled' => true,

        'sample_rate' => 1.0,

    ],

    'logging' => [

        'enabled' => true,                // 日志开关

        'path' => runtime_path('logs/observability.log'),

        'level' => 'info',

    ],

    'instrument' => [

        'http' => true,

        'mysql' => true,

        'redis' => true,

        'rabbitmq' => true,

        'system' => true,

    ],

];
```

多项目筛选
-----

[](#多项目筛选)

所有指标与日志均携带 **`project` / `app` / `env`** 三维标签：

维度配置项用途项目`project`业务项目划分，如 `mall`、`crm`应用`app_name`项目内服务，如 `api`、`admin`环境`environment``production` / `staging` / `local`**PHP 侧**：每个项目/服务独立配置即可，无需改代码。

```
// 商城 API
'project' => 'mall', 'app_name' => 'api', 'environment' => 'production',

// 商城后台
'project' => 'mall', 'app_name' => 'admin', 'environment' => 'production',

// CRM 系统
'project' => 'crm', 'app_name' => 'api', 'environment' => 'production',
```

**Grafana 侧**：仪表盘顶部提供 **项目 / 应用 / 环境** 三级下拉筛选，指标与日志联动过滤。

**Prometheus 侧**：在 `prometheus.yml` 添加多个抓取目标，每个 PHP 应用暴露 `/metrics` 即可。

可选：自定义业务 Span
-------------

[](#可选自定义业务-span)

常规 HTTP / DB / Redis / 队列已全自动。仅在需要追踪**自定义业务逻辑**时才手动加 Span：

```
$span = obs_trace('order.create', 'business', ['order_id' => '123']);

// ... 业务逻辑 ...

observability()->tracer()->finishSpan($span);
```

与监控栈的关系
-------

[](#与监控栈的关系)

本包只负责 PHP 侧埋点与指标暴露。可视化与采集由独立项目 [php-observability-stack](../php-observability-stack) 提供（Prometheus + Grafana + Loki + Promtail）。

Prometheus 指标一览
---------------

[](#prometheus-指标一览)

| 指标 | 说明 |

|------|------|

| `php_app_http_requests_total` | HTTP 请求总数 |

| `php_app_http_request_duration_seconds` | HTTP 请求耗时 |

| `php_app_http_errors_total` | HTTP 错误数 |

| `php_app_mysql_queries_total` | MySQL 查询总数 |

| `php_app_mysql_slow_queries_total` | 慢查询数 |

| `php_app_mysql_query_duration_seconds` | 查询耗时 |

| `php_app_redis_commands_total` | Redis 命令数 |

| `php_app_redis_slow_commands_total` | Redis 慢命令 |

| `php_app_rabbitmq_operations_total` | RabbitMQ / 队列操作数 |

| `php_app_php_memory_usage_bytes` | PHP 内存使用 |

License
-------

[](#license)

MIT

###  Health Score

36

—

LowBetter than 79% of packages

Maintenance100

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity35

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.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

1d ago

Major Versions

v1.1.1 → v2.0.02026-06-08

### 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)")

---

Tags

Metricstracingobservabilityhyperfprometheusthinkphpgrafana

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/php-observability-prometheus-kit/health.svg)

```
[![Health](https://phpackages.com/badges/php-observability-prometheus-kit/health.svg)](https://phpackages.com/packages/php-observability-prometheus-kit)
```

###  Alternatives

[artprima/prometheus-metrics-bundle

Symfony 5.4/6.4/7.4/8.x Prometheus Metrics Bundle

1754.0M3](/packages/artprima-prometheus-metrics-bundle)[open-telemetry/api

API for OpenTelemetry PHP.

1938.5M259](/packages/open-telemetry-api)[open-telemetry/sdk

SDK for OpenTelemetry PHP.

2326.5M315](/packages/open-telemetry-sdk)[renoki-co/octane-exporter

Export Laravel Octane metrics using this Prometheus exporter.

30128.9k](/packages/renoki-co-octane-exporter)[worldia/instrumentation-bundle

Symfony opentelemetry auto-instrumentation: requests, commands, messenger, doctrine.

2873.4k](/packages/worldia-instrumentation-bundle)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)