System Metrics Laravel Package

Product Decisions This Supports

• Build vs. buy on observability plumbing. This package replaces a thin slice of what you'd otherwise buy (Datadog/New Relic agents, CloudWatch agent) or build (shelling out to top/free/sysctl and parsing text). It gives you one typed API for CPU, memory, load, uptime, storage, network, cgroups, and per-process resources — with zero extensions and zero Composer dependencies. That's a real cost-avoidance story for a small platform team.
• Container right-sizing and capacity planning. The unified limits API is the headline capability: it resolves cgroup v1/v2, Docker, and Kubernetes quotas into fractional CPU cores and memory limits, and the v3.0.0 changelog shows deliberate work on fractional quotas (200m → 0.2 cores). This directly supports decisions like "are our pods over-provisioned?" and "what's our actual CPU headroom before we scale?"
• Queue worker / job concurrency tuning in Laravel apps. Snapshot memory, CPU, and available headroom, then derive worker counts (Horizon, queue:work pools) from measured limits instead of a hardcoded guess. This is a shipped feature, not a roadmap item.
• Feature scoping: in-app health and status surfaces. A /health or admin "system status" panel becomes a cheap, self-hosted feature — environment detection, uptime, memory/disk pressure, containerized vs. not. Useful for internal tools, on-prem installs, and customer-facing status pages.
• Pre-flight guards for expensive work. Because it exposes process RSS and memory limits with graceful degradation, you can gate large imports/exports/reports on available memory — turning OOM kills into a clean user-facing "try again later."
• Roadmap input on platform support. Linux + macOS only, PHP 8.3+ only. If you sell to Windows/IIS customers or run PHP 8.2, this is out of scope until either side moves — a scoping constraint to record, not a decision to defer.

When to Consider This Package

Adopt when:

• You run PHP 8.3+ on Linux (or macOS dev machines), and you need snapshots, not time-series history.
• Your containers can read /proc and /sys (some hardened/read-only rootfs setups don't mount them — verify in staging first).
• You want metrics embedded in the app with no sidecar, no agent, no daemon, and no outbound network call — attractive for on-prem, air-gapped, or compliance-sensitive deployments.
• You value explicit failure semantics in production code: the Result<T> pattern means no uncaught exceptions from metric reads, which matters on a request path.
• You need container-aware limits for scheduling/concurrency logic, where most "buy" options only give you dashboards, not a callable API.

Look elsewhere when:

• You need retention, alerting, dashboards, or historical trend analysis. This package is a point-in-time reader; pair it with Prometheus/Grafana/a hosted APM rather than replacing them.
• You need Windows support or PHP < 8.3.
• You need high-frequency, sub-second sampling in a request path — note SystemMetrics::cpuUsage() blocks for its sample interval by design. Use the two-snapshot API in a scheduled job instead.
• Supply-chain risk tolerance is low. 7 stars, 0 dependents, and a single named maintainer is a genuine bus-factor concern; the maturity signals (docs, changelog, releases, 89.9% coverage, PHPStan 9) offset it but don't eliminate it. Budget for the possibility of forking — the MIT license and dependency-free design make that cheap.
• You're mid-migration and can't absorb a v3.0.0 breaking change cycle (int → float for CPU fields, uncapped utilization percentages). Read the migration guide before pinning.

How to Pitch It (Stakeholders)

To executives: We can add in-application system visibility — CPU, memory, disk, uptime, container limits — without buying another monitoring vendor, deploying an agent, or adding infrastructure. That reduces observability spend and shortens incident triage for our ops and support teams. More concretely, it tells us whether production containers are over-provisioned, which is a direct cloud-cost lever. It's MIT-licensed with no runtime dependencies, so the lock-in and integration cost are both near zero — the worst case is we fork it or drop it.

To engineering: It's a pure-PHP, dependency-free, extension-free library behind a small, well-documented API. Strict types, readonly DTOs, Result<T> instead of exceptions, PHPStan level 9, ~90% test coverage, and a fake implementation for tests. It handles cgroup v1/v2, Docker, and Kubernetes — including fractional CPU quotas — which is the part you'd otherwise write and maintain yourself. Note two things upfront: it's framework-agnostic, so Laravel wiring is a thin service provider/facade/config file we own (call it half a day), and the cpuUsage() convenience method blocks for its sample window, so it belongs in scheduled jobs, not controllers. We should pin the version and read the v3.0.0 migration notes before committing.