System Metrics Laravel Package

Technical Evaluation

• Architecture fit: Framework-agnostic pure PHP library, not a Laravel-native package. It fits best as a low-level metrics adapter behind a Laravel service/provider layer, feeding health checks, admin dashboards, scheduled snapshots, or a Prometheus exporter. The Result<T> pattern and immutable DTOs are clean but differ from Laravel’s exception-heavy conventions, so a thin adapter is required. Container/cgroup awareness is valuable for Laravel workloads running in Docker or Kubernetes. No service provider, config publishing, or Laravel facade is included; the static SystemMetrics:: API is not a Laravel facade.
• Integration feasibility: Composer installation is trivial and there are no transitive dependencies. PHP 8.3+ aligns with modern Laravel 11/12 deployments. Linux/macOS-only support is a real constraint; Windows dev or CI environments need explicit guards. Reading /proc//sys requires no root but can be blocked by hardened containers, masked procfs, or disabled exec on macOS. Integration effort is moderate: wrapper, config, caching, auth middleware, failure handling, and feature flags must be built by us.
• Technical risk: Low adoption is the primary vendor risk: 7 stars, 0 dependents, and a single-maintainer profile. The v3.0.0 changelog shows breaking changes, including CPU core types changing from int to float, so API stability should not be assumed. Parsing /proc and cgroup v1/v2 is inherently environment-sensitive. Metrics semantics, such as CPU deltas, load-average normalization, and utilization values exceeding 100%, can be misinterpreted by product and alerting consumers. Long-running Laravel Octane/queue processes may be affected by static caching. Security review is needed for host metric exposure and command execution paths.
• Key questions: Which Linux distributions, container runtimes, cgroup versions, and Kubernetes environments are in scope? Is PHP 8.3+ acceptable across all target services? Is this intended for dashboards/health checks only, or will it drive alerting or autoscaling? What sampling interval and staleness are acceptable? Are exec-style calls permitted on macOS and in production containers? How will we isolate vendor risk if the package is abandoned? Does it behave correctly under Octane and long-running queue workers? Who owns the wrapper, runbook, and fallback path?

Integration Approach

• Stack fit: Use as a supplementary infrastructure metrics source inside Laravel, not as a replacement for Prometheus, node_exporter, CloudWatch, or an APM. Build a Laravel service provider that binds a SystemMetricsProvider interface, publishes config for enabled metrics, cache TTL, sampling interval, and access control. Expose via authenticated admin/health endpoints, scheduled metrics:snapshot commands, or a custom Pulse card/exporter. Queue workers and containerized services can use limits data for capacity tuning.
• Migration path: Start in a non-critical observability slice with a feature flag. Add a wrapper interface around all package calls so the vendor can be replaced without touching controllers or commands. Convert Result<T> failures into logs, degraded health responses, or null-safe DTOs at the boundary. If replacing shell scripts or cloud-agent metrics, run both in parallel for at least one sprint and compare outputs before cutover. Pin the exact package version initially.
• Compatibility: Target Laravel 11/12 on Linux with PHP 8.3+. Explicitly reject or degrade on Windows. Validate Docker/Kubernetes cgroup v1/v2 behavior in the actual runtime, not only local macOS. Check Octane compatibility because static caching may persist across requests; if needed, disable it or wrap reads with bounded cache invalidation. Do not treat the package’s static facade as a Laravel facade. Composer conflict risk is low due to zero dependencies.
• Sequencing: 1) Prove the package in a representative Linux container and document failure modes. 2) Build the Laravel wrapper, config, auth, and automated tests. 3) Add an authenticated health endpoint behind a feature flag. 4) Add scheduled sampling and caching. 5) Integrate dashboards or alerting only after baseline stability. 6) Evaluate queue-worker or autoscaling use cases. 7) Establish upgrade and fork/pin policy. Do not let the package block application startup or critical request paths.

Operational Impact

• Maintenance: Low code volume but elevated vendor-maintenance risk. We own the wrapper, documentation, and upgrade testing. Pin versions, monitor releases, and budget quarterly review because changelog history shows breaking changes. Lack of dependents means fewer community regression signals. Maintain a fork-or-replace contingency.
• Support: Community support is limited to GitHub issues for a low-adoption project. No commercial support or formal SLA. On-call should treat metrics failures as observability degradation, not application outages. Create an internal runbook covering unsupported OS, permission errors, missing cgroup files, and fallback behavior.
• Scaling: Do not call full overview collection per web request at high QPS. Use scheduled sampling or a sidecar/exporter pattern with bounded cache TTL. CPU usage sampling blocks by default for about one second if using the convenience method, so it must never sit in a request path. Static caching helps performance but can produce stale data in long-running workers. Memory overhead is small; the main scaling concern is file/command I/O and fleet-wide collection strategy.
• Failure modes: Unsupported Windows, missing /proc or /sys, masked procfs, permission denial, unmounted cgroups, missing sysctl, disabled exec, malformed kernel files, and container-runtime changes. The Result<T> pattern should prevent uncaught exceptions, but callers must handle failures explicitly. CPU deltas require two snapshots; first samples may be null or invalid. Utilization may exceed 100% in v3, so alert thresholds and UI displays must cap or annotate values. Public exposure of host metrics creates information-disclosure risk.
• Ramp-up: Basic read-only usage is quick for a Laravel/PHP developer. Production hardening requires roughly one sprint for wrapper, tests, auth, caching, feature flags, and security review. Ramp-up should include environment matrix testing, runbook creation, and dashboard validation. Start with one service and one production-like Linux environment; expand only after proving graceful degradation and upgrade safety.