Weave Code
System Metrics Laravel Package
cboxdk/system-metrics
Get real-time system metrics from Linux and macOS in pure PHP. No extensions or dependencies—just type-safe, readonly classes covering CPU, memory, storage, network, load, uptime, and container metrics with explicit Result-based error handling.
Cbox System Metrics gives you real-time system metrics from Linux and macOS in pure PHP—no extensions, no Composer dependencies. Built for PHP 8.3+, it uses readonly classes, strict types, and full PHPStan Level 9 compliance for clean, type-safe access to the data you need.
A Result pattern replaces exceptions, so success and failure are handled explicitly instead of surfacing uncaught errors in production.
- Environment detection: OS, kernel, architecture, virtualization, and containers
- CPU & load: raw time counters, per-core data, usage, and normalized load average
- Memory & uptime: RAM, swap, buffers, cache, and system uptime
- Storage & network: filesystem usage, disk I/O, interface stats, and connections
- Container metrics: cgroup v1/v2 and Docker support
Frequently asked questions about System Metrics
- How do I install cboxdk/system-metrics in a Laravel application?
- Install it with Composer using composer require cboxdk/system-metrics. It has no PHP extensions or Composer dependencies, so there is nothing else to configure. In Laravel you can resolve SystemMetrics directly or bind it as a singleton in a service provider for shared access.
- Does cboxdk/system-metrics support Laravel 10 and newer?
- Yes, Laravel 10 and newer are supported, and the package requires PHP 8.3 or higher. It is framework-agnostic pure PHP, so it works cleanly inside Laravel without version conflicts. You can call it from controllers, jobs, Artisan commands, or scheduled tasks.
- Do I need any PHP extensions or system binaries to read system metrics?
- No, the package is pure PHP and requires no extensions or external binaries. It reads Linux proc and sys files and macOS system interfaces directly. That makes it suitable for constrained containers and shared hosting where installing extensions is difficult.
- How do I get container memory working set metrics for Kubernetes or ECS?
- Use the working set fields such as memoryWorkingSetBytes, memoryWorkingSetUtilizationPercentage(), and availableMemoryBytesFromWorkingSet(). These subtract inactive file cache from raw cgroup usage, matching cAdvisor and Kubernetes semantics. They are the better choice for HPA custom metrics and container dashboards than raw memory usage.
- Why do working set or OOM kill metrics return null?
- Working set values return null when memory.stat cannot be read inside the container. OOM kill count returns null on kernels older than 4.13 or when the oom_kill counter is unavailable. Treat null as unknown rather than zero in dashboards, alerts, and autoscaling policies.
- What is the difference between cgroup v1 and cgroup v2 support?
- The package detects and reads both cgroup v1 and cgroup v2. On v2 it uses memory.current minus inactive_file for working set, and on v1 it uses memory.usage_in_bytes minus total_inactive_file. OOM kill counting now works on cgroup v1 with Linux 4.13 and later.
- Will upgrading change my memory utilization or available memory values?
- Possibly, if you run inside a cgroup without a memory limit. The limits() method no longer mixes host total memory with cgroup-only usage, which is a correctness fix but changes reported capacity values. Recalibrate dashboards, alerts, and capacity models that consumed availableMemoryBytes() or memoryUtilization() before upgrading.
- Does cboxdk/system-metrics add performance overhead in production?
- Overhead is low because it reads local kernel interfaces rather than shelling out, but real-time polling can add latency if called too often. Cache results briefly, throttle collection, or move polling into queued jobs for high-traffic applications. Avoid calling full overviews on every request unless you need fresh values.
- Can I export these metrics to Prometheus or OpenTelemetry?
- There is no built-in Prometheus or OpenTelemetry exporter, and no historical storage or aggregation. Pair the package with Prometheus, InfluxDB, Monolog, or another time-series store for persistence and trend analysis. The collected values map well to custom metrics in Kubernetes HPA and container dashboards.
- How should I test code that uses cboxdk/system-metrics?
- The Result-based API makes testing explicit: assert success or failure instead of catching exceptions. Handle null working set and OOM values as unknown in your test cases. Because the package is type-safe and PHPStan level 9 compliant, static analysis also catches many integration mistakes early.
Weaver
How can I help you explore Laravel packages today?