Laravel Prometheus Laravel Package

Technical Evaluation

Verdict: Low technical risk, high ownership risk. The package is a thin Laravel integration layer over the PHP Prometheus client (promphp/prometheus_client_php — verify in composer.json), providing a service provider, config, facade, and a scrape route. That surface area is small enough to audit in an afternoon and to fork if necessary. The concern is not what it does; it is who maintains it.

Architecture fit. Laravel's request-per-process model means metrics cannot live in process memory between requests without losing data behind any load balancer. Any viable deployment requires a shared storage adapter (Redis) so that N app instances contribute to one consistent exposition. Confirm the package supports Redis as a first-class adapter and that increments use atomic Redis operations rather than read-modify-write. Confirm whether the auto-registered middleware counts every request (including health checks and the /metrics scrape itself) — self-scraping inflates counters and is a classic first-week bug.

Integration feasibility. High. MIT license, Composer install, package auto-discovery, vendor:publish for config. A competent Laravel engineer can have counters and a /metrics endpoint in a non-production environment within a day. The real work is naming conventions, label design, and Redis provisioning — not the package.

Technical risk.

• Maintenance risk (high): 0 stars, 0 dependents, single maintainer, no visible community. Treat as you own this code. MIT permits a hard fork; plan for it rather than assuming upstream fixes.
• Cardinality risk (high, but self-inflicted): the package will happily accept a user ID or raw URL as a label. Unbounded label values are the most common way to take down a Prometheus server. This is a governance gap, not a package defect.
• Redis on the hot path (medium): if request middleware is enabled globally, every request gains a Redis round trip and inherits Redis's failure mode. Must be fail-open with a short timeout.
• Exposition exposure (medium): /metrics typically must bypass auth, CSRF, and the metrics middleware itself. Route-level network restriction is mandatory; the default config may not do this for you.
• Octane/Swoole (verify): in-memory or APC adapters behave differently under long-lived workers; if you run Octane, Redis is non-negotiable.
• Version drift (medium): confirm supported Laravel/PHP matrix, predis vs phpredis support, and whether the pinned Prometheus client version has known issues.

Key questions for the maintainer or the spike.

1. Which upstream client version is pinned, and is Redis the recommended production adapter?
2. How are increments made atomic, and what happens when Redis is unavailable — exception or silent no-op?
3. Is the scrape route and middleware opt-in or auto-registered on install?
4. Does it support custom registries/multiple storage adapters, or is it a single global registry?
5. What is the test coverage, and is there a CI matrix against current Laravel/PHP versions?
6. Any support for OpenMetrics, exemplars, or pushgateway for batch jobs (queue workers, scheduled commands)?

Integration Approach

Stack fit. Assumes Laravel 9–12, PHP 8.1+, a Redis instance already present or easily added, and a Prometheus-compatible backend (self-hosted Prometheus, Grafana Cloud, AWS Managed Prometheus, or an OTel collector with a Prometheus receiver). If you already run OpenTelemetry, prefer OTel's Prometheus exporter and treat this package as redundant — do not run two instrumentation paths.

Migration path. There are three realistic starting points:

• From nothing (most likely): lowest friction. Install, configure Redis, instrument 5–10 metrics that map to existing dashboards or SLOs. Do not attempt exhaustive instrumentation.
• From logs/Telescope: keep both for one quarter. Telescope for debugging, Prometheus for trends and alerting. They answer different questions.
• From a sibling package (e.g. spatie/laravel-prometheus): the facade APIs are similar but not identical. Migrate behind an internal wrapper, not call-site by call-site.

Compatibility. Pin the exact version in composer.json (no ^ on a package with zero dependents). Verify PHP and Laravel constraints against your matrix before rollout. Confirm the storage adapter matches your Redis client extension; mixing predis and phpredis across services causes confusing behaviour.

Sequencing.

1. Spike (1 week, one non-critical service): install behind a feature flag, wire Redis, scrape from a staging Prometheus, confirm multi-instance consistency by hitting two pods and checking counters aggregate.
2. Wrap: introduce an internal Metrics interface in your app that delegates to the facade. Every call site depends on your interface, not the vendor facade. This is the single highest-leverage decision — it makes the fork-and-replace scenario a one-file change.
3. Govern (before broad rollout): publish a metric naming convention, a label allowlist, and a cardinality budget per service. Reject PRs that add unbounded labels.
4. Instrument: HTTP request duration histogram, error counter by status class, queue job counters, outbound dependency latency. Stop there for phase one.
5. Harden: restrict /metrics at the ingress/security-group layer, exclude it from the metrics middleware, set a Redis timeout and fail-open behaviour, add a Redis-down alert.
6. Roll out service by service, then build dashboards and the first two alerts (error-rate burn, latency SLO).

Operational Impact

Maintenance. Ownership transfers to your team on day one. Budget roughly 2–4 engineer-days per year for dependency bumps and fork maintenance, plus whatever you spend on the fork if upstream goes quiet. Mitigate by keeping the integration thin (see the wrapper above) so replacing it with promphp/prometheus_client_php directly — or OTel — is a contained effort. Track the upstream repo in your dependency register with a named owner and a review date.

Support. No vendor, no community, no published security policy, no CVE feed. Your security team will need to accept an unsupported dependency. Given the package is a few hundred lines of glue over a well-known client, that is defensible with a fork-ready posture; it would not be defensible for something on the auth path.

Scaling. Two axes:

• Application: one Redis round trip per instrumented request. At high RPS this is measurable — consider sampling, restricting middleware to a subset of routes, or pipelining. Redis becomes a tier-0 dependency; if it degrades, request latency degrades with it unless you fail open.
• Observability backend: metric and label cardinality, not request volume, drives Prometheus cost and stability. A single unbounded label can multiply series count by orders of magnitude. Enforce the label allowlist in code review and monitor prometheus_tsdb_head_series against a budget.

Also plan for Redis key growth — histogram buckets and per-label series accumulate. Confirm whether the client sets TTLs or whether you need a sweep job.

Failure modes to design for.

Ramp-up. A Laravel developer is productive with the package in half a day. The binding constraint is Prometheus literacy — histogram vs. summary, quantiles, label design, and how to write a useful alert — which is a 2–3 day learning curve for one engineer who then becomes the internal owner. Plan a single named owner rather than distributed, casual usage; a shared metrics namespace with no owner reliably rots into an unqueried dashboard within two quarters.