Metrics Laravel Package

Product Decisions This Supports

• Build vs. buy for the instrumentation layer — now a clearer "buy." v3.0 turns a minimal emission abstraction into a credible one: strictly typed CollectorInterface, per-call tags, four new collectors (Chain, OpenTelemetry, InfluxDB v2, CloudWatch), and a maintained dependency tree (the abandoned Prometheus and InfluxDB SDKs are gone). The hand-rolled StatsDClient wrapper argument is stronger than before, because the replacement now covers dimensional metrics and multiple backends without you writing adapters.
• Deferring — and now safely reversing — the backend vendor decision. Tags being native means metric names alone are no longer the entire contract; the tag taxonomy becomes part of it. More importantly, the Chain collector makes migration a first-class operation: dual-write to old and new backends for a sprint, cut dashboards over, then remove the old collector. That converts "we might renegotiate observability spend" from a risk into a scheduled task.
• A real OpenTelemetry exit ramp. The new OTel collector records onto an MeterProviderInterface, so the same call sites can feed a Prometheus/OTLP pipeline later. This meaningfully weakens the old "instrumenting twice" objection: you can adopt this now as a phase 1 and converge on OTel metrics without touching call sites. It does not give you spans or trace correlation — that remains a separate, additive decision.
• Tag taxonomy and cardinality governance (a new product decision this release forces). Once every metric call accepts array $tags, someone must own the policy: which tag keys are allowed, what their value domains are, and what the cardinality budget is per metric. The library gives no guardrails, sampling, or aggregation hints. Deciding "we slice by endpoint and plan tier, but never by user ID or request ID" is a product/ops decision, and it belongs in the same doc as the metric naming standard.
• Running a backend bake-off cheaply. The examples/ app ships Docker stacks for Prometheus, Graphite/StatsD, InfluxDB 1.x/2.x, PostgreSQL, and LocalStack CloudWatch, each with a provisioned Grafana dashboard, and it runs in CI. Evaluating Datadog vs. CloudWatch vs. self-hosted Prometheus becomes a two-week spike rather than a quarter-long integration project — useful input to the buy-vs-self-host observability decision.
• Roadmap sequencing for observability work. Phase 1 stays cheap: instrument hot paths (request latency, queue job duration, cache hit/miss, signup/checkout counters) with tags for endpoint and cohort, defer tracing. Unchanged in spirit, but the phase 1 output is now portable to OTel.
• A runtime-upgrade decision is now bundled in. PHP 8.4+ is a hard gate. For teams on 8.2/8.3 this release is not adoptable today, and the honest framing is: upgrade PHP, then adopt, or stay on 2.x knowing it is effectively frozen. Surfacing that as an explicit roadmap item is better than discovering it in a PR.
• Use cases it fits well: SLO/error-budget instrumentation with per-endpoint tags, latency timings with fractional-millisecond precision, queue/worker health (collectors are tagged kernel.reset, so long-running workers don't leak state), feature-adoption counters sliced by plan tier or region, AWS-native shops that want CloudWatch without an extra agent, and before/after measurement for pricing or performance experiments.
• A weakening — but not removal — of the framework-coupling hedge. The Symfony bundle got substantially better (autowiring aliases, #[Target], lazy optional services, empty config falls back to null). Laravel still gets nothing, so the plain-PHP interface remains your portability story.
• Supply-chain hygiene as a decision input. Replacing two abandoned SDKs, adding PHPStan level 8 and PHPUnit 13, and shipping a CI-tested demo stack are quality signals that reduce (but do not eliminate) the single-maintainer concern.

When to Consider This Package

Adopt when most of these hold:

• PHP 8.4+ is available across all environments, including CI and long-lived queue workers. This is now the first gate, not a footnote. Laravel apps on 8.2/8.3 must sequence a runtime upgrade first.
• You need counters, gauges, and timings with low-cardinality tags — now supported per call on every metric method, or fixed once in the collector constructor for defaults.
• You want the backend decision reversible and are willing to own the metric name, unit, and tag-key contract as a documented standard.
• You want a plausible OpenTelemetry future without committing to the full OTel SDK and tracer plumbing this quarter — i.e. metrics-only OTel convergence is acceptable to you.
• You expect to dual-write during a migration at least once, and want that to be configuration rather than code.
• You're comfortable with one day of Laravel wiring: a service provider binding, config, and a NullMetrics fallback for local/test. No auto-discovery, no middleware, no /metrics route — that is still yours.
• You pin the version (^3.0) and treat the adapter layer as yours to wrap or compose (note: collectors and Factory are now final, so fork-by-subclassing is out; decorate or implement CollectorInterface instead).

Look elsewhere when:

• You cannot move to PHP 8.4 yet. This is the dominant disqualifier for v3.0. Remaining on 2.x means accepting an effectively frozen line with known-abandoned transitive dependencies.
• Tracing, spans, or log correlation are on the roadmap within one to two quarters. The OTel collector covers metrics only; you would still instrument separately for traces. Go straight to the OpenTelemetry SDK in that case.
• You need client-side percentiles, histograms with configurable buckets, exemplars, sampling controls, or buffered/async transport at high throughput. Not in scope.
• You need high-cardinality dimensions or unbounded tag values. Tags are now easy to add and there is no cardinality protection, no sampling, and no per-collector budget — a foot-gun that requires discipline.
• You require a multi-maintainer bus factor, a security-response commitment, or a support contract. The 3.0 release is strong evidence of active investment, but it is still a single-maintainer project.
• You want batteries-included Laravel: config publishing, auto-discovered provider, request middleware, a scrape endpoint. Prefer a Laravel-specific package that composes a client with framework integration.
• You depend on Zabbix or Librato (removed with no replacement), or on subclassing collectors/Factory (now final), or on TaggableCollector::setTags() / the null_inlinetaggable factory type — all removed.

How to Pitch It (Stakeholders)

To executives: We're adopting a free (MIT), thin instrumentation layer so reliability and usage measurement don't lock us into one observability vendor. This release materially changes the calculus in our favor: it now supports tags (so we can slice latency and adoption by endpoint, plan tier, or region), it can write to several backends at once, and it has an OpenTelemetry path — meaning our instrumentation survives a future vendor change instead of being rewritten. It also ships a demo stack with dashboards for Prometheus, CloudWatch, InfluxDB, and Graphite, so we can compare observability vendors on real data before signing. The cost is small: roughly a day of integration, plus a PHP 8.4 runtime upgrade we should schedule regardless. The expensive, reversible commercial decision — which backend and dashboards we pay for — stays separate and stays ours.

To engineering: One strictly typed interface, one service-provider binding, and vendor adapters behind it. Every metric call now takes array $tags, so application code emits a stable, testable API and swapping StatsD for CloudWatch or an OTLP pipeline is config plus one adapter — not a refactor of call sites. The Chain collector lets us dual-write during any migration; the OpenTelemetry collector lets us converge on OTel metrics without re-instrumenting; collectors swallow client exceptions so the telemetry path can't take down the app; and everything is kernel.reset-tagged for long-running workers. A null collector covers local and test. Trade-offs we accept explicitly: PHP 8.4+ only, no tracing/spans, no histograms-percentiles-sampling, a tag-cardinality policy we must write and enforce ourselves, and a single maintainer — so we pin ^3.0, treat metric names/units/tag keys as our contract, and wrap rather than extend (collectors and Factory are final). If we need traces within two quarters, we should start with the OpenTelemetry SDK instead and skip the intermediate step. Upgrading from 2.x is a breaking change with a documented guide; we should budget the interface and tag migration in the same sprint as the runtime bump.