Laravel指标暴露怎么做

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

📖 目录导读

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

---

为什么要暴露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秒）

---

总结与进阶建议

核心要点回顾：

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

进阶方向：

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

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

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