Prometheus Client Php Laravel Package

Product Decisions This Supports

• Observability roadmap and build-vs-buy: Decide whether to instrument Laravel services with a Prometheus-native client instead of building custom metrics plumbing or buying a full APM suite. This package gives a small, permissively licensed (Apache-2.0) instrumentation layer that plugs into an existing Prometheus/Grafana stack.
• SLO and reliability investment: Use counters, gauges, histograms, and summaries to define and track request rates, error rates, latency distributions, queue depths, and business KPIs. This directly supports SLO reviews, incident response, and capacity planning.
• Feature prioritization by evidence: Instrument new features behind flags or by domain labels to measure adoption, failure modes, and performance impact before committing further roadmap investment.
• Platform standardization: Standardize PHP/Laravel metrics conventions across teams—metric naming, label taxonomy, bucket choices, and /metrics endpoint ownership—rather than allowing ad hoc logging-based measurement.
• Adapter strategy by environment: Choose Redis, Predis, APCu/APCng, PDO, or in-memory storage based on deployment topology. This is a product/architecture decision because it affects operational dependencies, metric consistency, and infrastructure cost.
• Laravel-specific instrumentation use cases: Instrument HTTP middleware, queue workers, scheduled commands, external API calls, and domain events. Use histograms for latency and summaries for sliding-window observations where appropriate.
• Cron and batch-job visibility: For long-running scripts or cron jobs, use the in-memory adapter or the companion PushGateway library when pull-based scraping is impractical.
• Risk management around high-cardinality metrics: Decide which labels are safe to expose. PM should gate label design because user IDs, request IDs, or unbounded dimensions can create cost and reliability problems in Prometheus.

When to Consider This Package

• You already run or plan to run Prometheus and Grafana. This is a client library, not a monitoring backend; it renders metrics for scraping but does not store, alert, or visualize them.
• You need vendor-neutral, self-hosted metrics for PHP/Laravel services. It is a reasonable fit when the organization wants to avoid APM lock-in and already has platform competence in Prometheus.
• You can provide a supported aggregation backend. Redis or APCu/APCng is required for cross-request aggregation. Redis is recommended locally next to PHP workers; APCu requires the extension and has per-worker characteristics; PDO is available for database-backed storage.
• You are on supported PHP versions. The README targets PHP ^8.2 and supported PHP releases, so legacy Laravel applications may need an upgrade first.
• You need standard metric primitives. Counters, gauges, histograms, summaries, label dimensions, and text exposition are sufficient. Exponential histogram buckets are available for latency-oriented metrics.
• You are willing to build the Laravel glue. Expect to add a service provider, singleton registry configuration, middleware, a protected metrics route, and environment-specific adapter configuration. The package is not Laravel-specific and does not provide auto-instrumentation.
• You do not require PushGateway support in the core package. PushGateway support was removed in v2.0.0; it requires the separate promphp/prometheus_push_gateway_php companion library.
• Look elsewhere if: you need traces, logs, and metrics in one SDK; you need a managed APM with dashboards and alerting out of the box; you cannot operate Redis/APCu/PDO; you require PushGateway in the core dependency; you need auto-instrumentation for Laravel; or you are unwilling to own metric naming, label hygiene, and dashboard/alert configuration.
• Treat ecosystem maturity as a validation item. The package has a recent release history, README, and Apache-2.0 license, but modest stars and zero listed dependents suggest limited public ecosystem evidence. Run a spike in a representative Laravel service before standardizing.

How to Pitch It (Stakeholders)

For executives: This is a low-cost, vendor-neutral way to make Laravel services measurable. It supports reliability and product decisions—SLOs, incident response, capacity planning, and feature adoption—without buying a full APM platform. The license is permissive, the dependency is small, and it fits an existing Prometheus/Grafana investment. The main costs are operational: we must run or reuse Redis/APCu/PDO for aggregation, secure the metrics endpoint, and own dashboards and alerts.

For engineering: The package provides standard Prometheus primitives for PHP: counters, gauges, histograms, summaries, labels, and text exposition. It supports Redis, Predis, APCu, APCng, PDO, and in-memory adapters. It requires PHP 8.2+ and does not include PushGateway support in the core package. We would integrate it through a Laravel service provider, middleware, and a protected /metrics route, with adapter choice per environment. Key engineering risks are high-cardinality labels, Redis availability, APCu per-worker behavior, endpoint security, and the absence of Laravel auto-instrumentation.

Recommendation: Run a time-boxed spike in one Laravel service with Redis-backed aggregation, define a small metric and label taxonomy, and validate scrape performance and operational overhead. If successful, adopt as the standard metrics client for PHP services already using Prometheus; otherwise evaluate OpenTelemetry or a managed APM based on the gap.