Laravel指标暴露怎么做

wen PHP项目 2026-07-10 2

Laravel指标暴露怎么做？完整指南与最佳实践

📖 目录导读

为什么要暴露Laravel应用指标？
暴露指标的核心方式：Prometheus + 自定义Exporter
实战步骤：安装与配置
关键指标清单：哪些数据应该暴露？
常见问题FAQ
总结与进阶建议

Laravel指标暴露怎么做

为什么要暴露Laravel应用指标？

在现代微服务架构中，指标暴露是监控系统健康、排查性能瓶颈、进行容量规划的基础，如果你只依赖服务器层面的CPU、内存监控，而不知道某个Laravel路由响应时间飙升、或是队列积压严重,你就无法快速定位问题。

暴露指标的核心价值包括：

实时追踪HTTP请求数、响应时长、错误率
监控数据库连接池使用情况
观察队列任务处理速度与失败率
为自动伸缩（如K8s HPA）提供数据源

暴露指标的核心方式：Prometheus + 自定义Exporter

最流行的方案是使用 Prometheus 作为监控系统，Laravel应用通过HTTP端点暴露Prometheus可抓取的指标数据,这里推荐两个开源库：

spatie/laravel-prometheus：功能全面，支持自动采集HTTP请求、数据库查询、Redis等常见指标
superbalist/laravel-prometheus-exporter：轻量级，适合自定义场景

核心原理：Laravel应用在 /metrics 路由上输出Prometheus格式的文本数据，Prometheus Server定期抓取。

实战步骤：安装与配置

步骤1：安装依赖包（以spatie/laravel-prometheus为例）

composer require spatie/laravel-prometheus

步骤2：发布配置

php artisan vendor:publish --provider="Spatie\Prometheus\PrometheusServiceProvider"

步骤3：配置路由与中间件

在 config/prometheus.php 中：

设置 url 为 /metrics（建议限制内网访问）
启用中间件组，如 web 或 api

步骤4：启动指标采集

默认情况下,它会自动采集：

Laravel HTTP请求计数 & 耗时直方图
数据库查询次数 & 慢查询
缓存命中率
队列任务状态

步骤5：验证指标端点

curl http://your-app.test/metrics

你会看到类似这样的输出：

# HELP laravel_http_requests_total Total number of HTTP requests
# TYPE laravel_http_requests_total counter
laravel_http_requests_total{method="GET",route="home"} 1024

关键指标清单：哪些数据应该暴露？

类别	指标名称	说明
HTTP	`http_requests_total`	按路由、方法统计的请求总数
性能	`http_request_duration_seconds`	请求耗时分布（P50/P95/P99）
数据库	`db_query_count` & `db_slow_query_count`	数据库查询频率 & 慢查询
队列	`queue_jobs_total` / `queue_failed_jobs_total`	队列任务总量 & 失败量
Redis	`redis_hit_count` / `redis_miss_count`	缓存命中率
PHP	`php_memory_usage_bytes`	当前进程内存

自定义指标示例

在 AppServiceProvider 中注册：

use Spatie\Prometheus\Facades\Prometheus;
Prometheus::counter('orders_created_total')
    ->labels(['status'])
    ->help('Total orders created by status')
    ->register();

常见问题FAQ

Q1：为什么我的 `/metrics` 路由返回404？

检查 config/prometheus.php 中 url 是否正确
确保运行了 php artisan config:clear
确认中间件没有阻止该路由（如CSRF中间件）

Q2：暴露指标会不会泄露敏感数据？

建议：在生产环境下，只对内网IP开放 /metrics 端点

使用Nginx或Laravel中间件限制访问：

Route::middleware(['throttle:60,1'])->group(function () {
  Route::get('/metrics', [PrometheusController::class, 'metrics']);
});

Q3：如何将指标接入Grafana仪表盘？

首先在Prometheus中添加Laravel应用的target
然后在Grafana中创建数据源（类型：Prometheus）
使用 laravel_http_requests_total 等指标构建图表

Q4：自定义指标为什么没有数据？

确认在代码中调用了 inc() 或 observe() 增加指标值
检查Prometheus抓取间隔是否合理（默认15秒）

总结与进阶建议

核心要点回顾：

使用Prometheus + spatie/laravel-prometheus是Laravel指标暴露的标准方案
关键指标包括：HTTP请求、数据库、队列、缓存
生产环境下务必做好访问控制

进阶方向：

结合OpenTelemetry：在分布式架构中实现链路追踪
使用Kubernetes HPA：基于自定义指标实现Pod自动伸缩
告警配置：在Prometheus Alertmanager中设置规则，如“5分钟内错误率超过1%”

实际案例参考：一家电商团队通过暴露 checkout_duration_seconds 指标，发现支付网关响应缓慢，及时切换了服务商，将转化率提升了12%。

如果你已经在生产环境实践过Laravel指标暴露，欢迎分享你的自定义指标和踩坑经验，监控没有终点,持续优化指标结构才能真正发挥数据价值。

Laravel指标暴露怎么做