PHP 8.5 配置 Prometheus 自定义指标采集的核心是应用自身暴露规范的 /metrics 端点，需用 v3.x client_php 库复用 CollectorRegistry、APCu/Redis 存储、请求中动态打点、单独 metrics.php 渲染输出，并在 prometheus.yml 中配置抓取与标签归一。
PHP 8.5 配置 Prometheus 自定义指标采集，核心是让 PHP 应用自身暴露符合 Prometheus 文本格式的 /metrics 端点，而不是依赖外部探测或被动埋点。关键不在 PHP 版本新旧，而在采集逻辑是否复用、存储是否可靠、暴露是否规范。
一、用 client_php 库注册并管理指标
必须使用支持 PHP 8.5 的 prometheus/client_php（v3.x 起全面兼容），避免低版本中 APCu key 冲突或 GC 异常问题：
- 通过 Composer 安装：
composer require prometheus/prometheus-client-php:^3.0 - 全局复用单例
CollectorRegistry，不要每次请求 new —— 否则指标会重复注册、数值错乱 - 推荐使用 APCu 存储（需启用且
apc.ttl = 0+apc.gc_ttl = 3600），或 Redis（适合多 PHP-FPM 进程共享） - 示例初始化（放在入口文件或服务启动时）：
$adapter = new \Prometheus\Storage\APC();
$registry = new \Prometheus\CollectorRegistry($adapter);
// 计数器：按路由和状态码统计请求
$requests = $registry->getOrRegisterCounter(
'app', 'http_requests_total', 'Total HTTP requests', ['route', 'status']
);
// 直方图：记录响应耗时分布
$duration = $registry->getOrRegisterHistogram(
'app', 'http_request_duration_seconds', 'HTTP request duration', ['route'],
[0.01, 0.05, 0.1, 0.25, 0.5, 1.0]
);
二、在请求生命周期中动态打点
指标值必须从真实上下文获取，不能写死或随机生成：
- 在路由分发后、响应发出前调用
$requests->inc(['/api/users', '200']) - 耗时用
microtime(true)手动计时，再传给$duration->observe($seconds, ['/api/users']) - 错误捕获后，统一增加
$requests->inc(['/api/users', '500']) - 避免在 CLI 脚本中遗漏
$registry->clearCollectors()，否则指标跨任务残留
三、暴露标准 /metrics 接口供 Prometheus 抓取
单独创建 metrics.php 文件，不走框架中间件，确保轻量、稳定、无权限拦截：
立即学习“PHP免费学习笔记（深入）”；
- 文件开头加载 autoloader 和 registry 实例（复用上一步初始化的对象）
- 设置响应头：
header('Content-Type: ' . \Prometheus\RenderTextFormat::MIME_TYPE); - 渲染输出：
echo (new \Prometheus\RenderTextFormat())->render($registry->getMetricFamilySamples()); - Nginx 配置示例（禁止执行 PHP，只做转发）：
alias /path/to/metrics.php;
fastcgi_pass php-fpm:9000;
include fastcgi_params;
}
四、Prometheus 配置抓取并清洗标签
在 prometheus.yml 中添加 job，重点做两件事：精准定位 + 标签归一：
- targets 写容器名或域名（如
php-app:80），确保网络可达 - 用
relabel_configs注入环境、服务名等语义标签：{ source_labels: [__address__], target_label: instance }，{ replacement: "prod", target_label: environment } - 建议设
scrape_interval: 30s，避免高频抓取加重 PHP-FPM 压力 - 加
sample_limit: 10000防止单次返回指标过多导致解析失败
