Metrics Bundle Laravel Package

Technical Evaluation

Architecture fit. Poor for a Laravel codebase. itk-dev/metrics-bundle is a Symfony bundle, not a Laravel package, and the surface it ships is bundle-shaped: a Bundle class, DI compiler passes, tagged collectors, and a bundled routing file for a scrape endpoint. Laravel's service container, service providers, and route registration do not consume any of that wiring. The reusable value — a Prometheus text-format exposition endpoint sitting on top of promphp/prometheus_client_php, plus a collector abstraction and storage adapters — is real, but it is not the part the package markets as its convenience. Framed for a TPM: this is a Symfony-scoped decision, and if the question on the table is Laravel observability, this package is not the answer — it is a reference implementation for one. The equivalent Laravel path is spatie/laravel-prometheus or a thin /metrics route backed directly by promphp/prometheus_client_php.

Integration feasibility. Low to moderate, and the effort is all ours. Two viable shapes exist: (a) consume only the non-Symfony classes as a plain PHP library and hand-wire collectors plus a Laravel service provider and route; or (b) fork and add a MetricsServiceProvider, then vendor it. Neither is a drop-in adoption. The realistic cost estimate is a spike plus a small internal integration — maybe a day or two of engineering — which is more than zero and lands in exactly the territory where a maintained framework-agnostic client plus ~100 lines of glue produces the same result without us owning a fork.

Technical risk. High, and compounding on three independent axes. Abandonment: 0 stars, 0 dependents, last release July 2022 — no security patching, no PHP 8.3/8.4 compatibility guarantee, no Symfony 7 support, no issue triage, no maintainer. Framework mismatch: a 2022-vintage Symfony bundle will typically pin PHP ~8.0/8.1 and Symfony ~5.4/6.x constraints; under Laravel 10/11 on PHP 8.2/8.3 you will be relaxing constraints in a fork and re-running tests you do not have. Single-maintainer/key-person risk: the repo is a team utility scoped to "the ITK development team," not a general-purpose product; it is dormant by design, not by accident. Mitigant: MIT license makes forking legally clean, so the risk is maintenance load, not legal exposure — but that does not reduce the load.

Key questions.

• Is the target codebase Laravel or Symfony? If Laravel, this package should be treated as reference material, not a dependency, and the decision collapses to "wire promphp/prometheus_client_php ourselves or use spatie/laravel-prometheus."
• What PHP and Symfony version constraints are declared in composer.json, and do they clear our platform floor?
• Do we already operate Prometheus and Grafana? Without a Prometheus server, this bundle produces nothing of value and the TCO argument evaporates.
• Which storage backend do we need — in-memory (per-request, useless for cross-request counters under PHP-FPM), APCu (per-host), or Redis (cross-host)? What is the failure behavior if that backend is down during a scrape?
• Does it support cardinality controls and Histogram/Summary types, or are we exposed to label explosion?
• Who is the named internal owner six months from now if upstream stays dark?
• Is there an actively maintained fork or a Laravel-native alternative covering the same surface?

Integration Approach

Stack fit. As-is: no fit for Laravel. As a reference: good fit — the Prometheus exposition contract is trivial (text format over a /metrics route) and the collector/storage abstraction is the only non-trivial piece worth studying. Recommendation is to treat the package as a design reference rather than a dependency. If the team is Symfony-based, fit improves substantially, but maintenance status still has to be cleared before committing.

Migration path. Two paths. Path A (preferred): do not adopt. Instrument with promphp/prometheus_client_php behind a Laravel service provider, expose /metrics as a route, and pick APCu or Redis based on topology (single host vs. multi-replica). This is the standard pattern and it is what the framework-native wrappers already do. Path B (only with existing investment or a hard constraint): vendor the package into the repo (fork or Composer path/VCS repository), add a MetricsServiceProvider that registers collectors and the route, pin the fork, and own it. Do not point production at the Packagist upstream.

Compatibility. Expect friction on modern PHP. Constraint relaxation in a fork plus a test run is the likely minimum; the bundle's DI tags will not resolve in Laravel's container, so only the library-level classes survive unmodified. Under Laravel 10/11 / PHP 8.2+, validate before writing any instrumentation — if the underlying promphp client version is stale, that is a second dependency to upgrade.

Sequencing.

1. Confirm the requirement: scrape endpoint, metric taxonomy (start with RED — rate, errors, duration — and USE — utilization, saturation, errors), label policy, storage backend, multi-instance behavior.
2. Timebox a spike: fork against the target Laravel version and PHP runtime, or spike promphp + a service provider. Compare on effort and ownership, not features — the feature set is identical.
3. Decide build-vs-adopt from the spike.
4. Implement service provider, route, and auth — the /metrics endpoint must never be publicly reachable.
5. Instrument incrementally; add a scrape target and one dashboard before broadening.
6. Add a CI smoke test asserting the endpoint returns valid exposition format after every dependency bump.

Operational Impact

Maintenance. Effectively zero upstream. We inherit PHP version bumps, dependency CVEs, framework upgrades, and bug fixes. This is the dominant cost and must be priced in explicitly — it is recurring, not a one-time integration. For a TPM, that means a permanent line item against a named owner, for a capability we could obtain from a maintained package.

Support. None. No maintainer responsiveness, no issue triage, no security advisory channel. For code that sits on an HTTP endpoint reached on every scrape and touches request paths, that is meaningful operational exposure. Internal ownership must be named before adoption, not after.

Scaling. Prometheus's pull model means every replica's /metrics is hit on every scrape interval. Under PHP-FPM, in-memory storage is per-request and therefore useless for cross-request counters — APCu or Redis is required. Redis-backed collection adds a network hop to the scrape path, so a Redis hiccup becomes a scrape failure or a blocked worker. Cardinality is the real scaling risk: unbounded labels (user IDs, raw paths, request IDs) will blow up Prometheus memory and are the single most common cause of metrics outages. Enforce label allow-listing at the instrumentation layer regardless of package choice.

Failure modes. (a) Slow collector or scrape timeout blocking PHP-FPM workers and degrading user traffic. (b) Cardinality explosion causing Prometheus OOM or scrape failures. (c) Storage backend outage propagating through the endpoint into the app if not isolated. (d) Silent breakage on PHP/framework upgrade because nobody tests an abandoned package. (e) Auth gaps exposing internal metrics publicly. Mitigations: isolate the /metrics route, set scrape timeouts, cap label cardinality, and keep a post-upgrade smoke test in CI.

Ramp-up. For a Symfony-fluent team, low — the conventions are familiar. For a Laravel team, moderate-to-high: maintaining the fork asks engineers to learn Symfony bundle internals (compiler passes, DI tags, tagged collector resolution) to preserve a capability that a framework-agnostic client plus a small service provider delivers without that learning curve. That ramp-up is a poor allocation of engineering budget and a staffing risk if the one person who understood the fork leaves.

Bottom line for the roadmap. Architecturally mismatched for Laravel, operationally orphaned, and offering little beyond what maintained alternatives already provide. The cheap, defensible move is to skip adoption, use this repo as a reference for the /metrics shape, and build the thin integration on promphp/prometheus_client_php with a named owner, a label policy, and an auth boundary. If a Symfony service is genuinely in scope and Prometheus is already operated, revisit as a timeboxed spike — not a platform commitment.