laravel 直接暴露 /metrics 会失败，因为默认无 prometheus 兼容端点，需手动注册指标并绑定路由，且必须在服务启动阶段（如 appserviceprovider::boot）完成单例注册；laravel-s 依赖 apcu 存储进程指标，缓存事件需开启 events=true 并显式注册监听器，gauge 与 counter 类型不可混用，否则导致图表异常。

为什么 Laravel 直接暴露 /metrics 会失败

因为 Laravel 默认不提供 Prometheus 兼容的指标端点，/metrics 路由不存在，直接配 Prometheus 去抓会返回 404 或空响应。必须手动注册指标收集器并绑定 HTTP 路由，且不能在每次请求里重复注册（否则触发 duplicate metrics collector registration attempted panic）。

• 别在控制器或中间件里调用 prometheus_client_php 的 register() 或 addCounter()
• 指标注册必须在服务启动阶段完成，推荐放在 AppServiceProvider::boot() 或独立的 PrometheusServiceProvider
• 确保使用单例容器管理 CollectorRegistry，避免多个实例冲突

Laravel-S 用户必须先装 APCu 才能启用 Prometheus

laravel-s 的 Prometheus 组件依赖 APCu 存储进程级指标（如 Worker 请求计数、内存占用），不是可选——没它，RequestMiddleware 会静默失效，所有耗时/状态码指标全丢。

Laravel 13.2.0

PHP中文网提供Laravel 13.2.0版本下载，Laravel框架 是基于 PHP 8.3+ 的高性能框架，官方推荐通过 Composer 安装。它内置 AI SDK、JSON:API Resources 及原生向量搜索，支持属性驱动开发与队列路由，大幅提升开发效率。相比旧版，13.2.0 优化了缓存 TTL 管理与实时通信，无需 Redis 即可横向扩展。作为现代 Web 开发首选，它兼顾安全与极速体验，助您快速构建企业级应用。

下载

• 检查是否启用：php -m | grep apcu，若无输出需安装；PHP 8.1+ 常见路径是 extension=apcu.so + apc.enable_cli=1
• 旧版 APC 已废弃，APCu 是唯一支持 CLI 模式的替代品
• 配置后必须重启 Swoole Worker，仅 reload 不生效

CacheHit/CacheMiss 事件埋点要开开关，否则监听器不触发

Laravel 缓存事件默认关闭，即使你写了 TrackCacheHitRate 监听器，CacheHit 和 CacheMissed 事件也不会广播，hit/miss 计数永远为 0。

• 确认 config/cache.php 中 'events' => true 已设置（不是注释掉的状态）
• 监听器注册必须在 EventServiceProvider 的 $listen 数组里显式声明，例如：'Illuminate\Cache\Events\CacheHit' => ['App\Listeners\TrackCacheHitRate']
• 别用 cache:clear 命令测试——它不触发 CacheMissed，要用真实缓存读取逻辑（如 Cache::get('key')）

Gauge 和 Counter 用错类型会导致 Grafana 图表异常

比如把并发请求数当成 Counter 累加，结果曲线一路飙升不回落；或把请求总数当 Gauge 设置，导致数值被覆盖丢失历史趋势。

• Counter：只增不减，适合统计总量（http_requests_total、cache_hits_total）
• Gauge：可升可降，适合瞬时值（php_memory_usage_bytes、queue_jobs_pending）
• Label 值别带动态 ID，例如路由 /users/123 应模板化为 /users/:id，否则 label 组合爆炸，Prometheus 存储和查询都会崩

指标注册时机、APCu 依赖、事件开关、类型误用——这四点漏掉任意一个，Prometheus 就只能抓到空数据或错误数据。实际部署时，先 curl 一下 /actuator/prometheus 看输出是否含你定义的指标名，再查 Prometheus UI 的 Targets 页面确认抓取状态，比盯着 Grafana 空面板更有意义。