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

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

• HTTP 请求 QPS / 延迟 / 错误率

• MySQL 查询性能、慢查询

• Redis 命令性能、慢命令、错误

• RabbitMQ / 队列操作性能与错误

• 请求链路追踪（trace_id / span）

• 结构化 JSON 日志（可开关）

快速开始

1. 安装

composer require php-observability/prometheus-kit

2. 复制配置文件

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

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

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

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

composer require php-observability/prometheus-kit

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

安装后自动注册中间件与事件监听器，配置文件发布到 config/autoload/observability.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 端点

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

http://your-app-host/metrics

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

git clone <php-observability-stack>

cd php-observability-stack

cp .env.example .env

docker compose up -d

详见 php-observability-stack。

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

| 监控项 | 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 自动原理

• 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 自动原理

• 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

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

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

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

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

与监控栈的关系

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

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

MIT