PHPackages cboxdk/system-metrics - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Logging & Monitoring](/categories/logging) 4. / 5. cboxdk/system-metrics ActiveLibrary[Logging & Monitoring](/categories/logging) cboxdk/system-metrics ===================== Peek into your low level system metrics with PHP v2.3.1(1mo ago)2441↓100%[1 PRs](https://github.com/cboxdk/system-metrics/pulls)1MITPHPPHP ^8.3CI passing Since Nov 16Pushed 1mo agoCompare [ Source](https://github.com/cboxdk/system-metrics)[ Packagist](https://packagist.org/packages/cboxdk/system-metrics)[ Docs](https://github.com/cboxdk/system-metrics)[ GitHub Sponsors](https://github.com/cboxdk)[ RSS](/packages/cboxdk-system-metrics/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (5)Dependencies (3)Versions (16)Used By (1) Cbox System Metrics =================== [](#cbox-system-metrics) [![Latest Version on Packagist](https://camo.githubusercontent.com/d26219335a4f6441bd4379573e0ac49f064332cf32948c9b8c09eded6063563c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f63626f78646b2f73797374656d2d6d6574726963732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/cboxdk/system-metrics)[![Tests](https://camo.githubusercontent.com/095dbe6401716fdcef28bdf30dfc8c065f1134be15e5f3f03f36f7ebb3d56514/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f63626f78646b2f73797374656d2d6d6574726963732f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/cboxdk/system-metrics/actions/workflows/run-tests.yml)[![PHPStan Level 9](https://camo.githubusercontent.com/fa7d257d0c5c1cf237ac3490ef3a5561626b17fcb0a8547c01b0bb8746554e60/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d6c6576656c253230392d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](https://phpstan.org/)[![Total Downloads](https://camo.githubusercontent.com/00530634bd6da82fdd431e2fa1a0eee43db005b8fcfe6a7a8bbcd058c7a3bc01/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f63626f78646b2f73797374656d2d6d6574726963732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/cboxdk/system-metrics)[![PHP 8.3+](https://camo.githubusercontent.com/8960f704476a7efc65571df383c7c2477ede1654e8df16e70201ad7e36331d19/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e332b2d626c75652e7376673f7374796c653d666c61742d737175617265)](https://www.php.net) **Get real-time system metrics from Linux and macOS in pure PHP.** No extensions, no dependencies, just clean type-safe access to CPU, memory, storage, network, and container metrics. ``` use Cbox\SystemMetrics\SystemMetrics; $overview = SystemMetrics::overview()->getValue(); echo "OS: {$overview->environment->os->name}\n"; echo "CPU Cores: {$overview->cpu->coreCount()}\n"; echo "Memory: " . round($overview->memory->usedPercentage(), 1) . "%\n"; ``` Table of Contents ----------------- [](#table-of-contents) - [Features](#features) - [Requirements](#requirements) - [Installation](#installation) - [Quick Start](#quick-start) - [Documentation](#documentation) - [Testing](#testing) - [Changelog](#changelog) - [Contributing](#contributing) - [Security](#security) - [Credits](#credits) - [License](#license) Features -------- [](#features) **✨ Pure PHP Implementation** - No PHP extensions required - No Composer dependencies - Works out of the box on any Linux or macOS system **🔒 Type-Safe with Modern PHP** - Built for PHP 8.3+ with readonly classes - Strict types everywhere (`declare(strict_types=1)`) - Full PHPStan Level 9 compliance **🎯 Explicit Error Handling** - Result pattern instead of exceptions - Explicit success/failure handling at compile time - No uncaught exceptions in production **📊 Comprehensive Metrics** - Environment detection (OS, kernel, architecture, virtualization, containers) - CPU metrics (raw time counters, per-core data, usage calculations) - Memory metrics (physical RAM, swap, buffers, cache) - Load average with per-core normalization - System uptime tracking - Storage metrics (filesystem usage, disk I/O) - Network metrics (interface stats, connections) - Container metrics (cgroup v1/v2, Docker, Kubernetes) - Process metrics (individual and group monitoring) - Unified limits API (environment-aware resource limits) **🏗️ Production-Ready** - 89.9% test coverage - PSR-12 code style via Laravel Pint - Graceful degradation when APIs unavailable - Performance optimized with static data caching Requirements ------------ [](#requirements) - **PHP 8.3 or higher** (uses readonly classes) - **Linux or macOS** (Windows not supported) - **Standard system access**: - Linux: Read access to `/proc`, `/sys` filesystems - macOS: Access to `sysctl`, `vm_stat`, `sw_vers` commands **Note:** No special permissions or root access required. Installation ------------ [](#installation) ``` composer require cboxdk/system-metrics ``` Quick Start ----------- [](#quick-start) ### Complete System Overview [](#complete-system-overview) ``` use Cbox\SystemMetrics\SystemMetrics; $result = SystemMetrics::overview(); if ($result->isSuccess()) { $overview = $result->getValue(); // Environment echo "OS: {$overview->environment->os->name} {$overview->environment->os->version}\n"; echo "Architecture: {$overview->environment->architecture->kind->value}\n"; // CPU echo "CPU Cores: {$overview->cpu->coreCount()}\n"; // Memory (cgroup-aware — shows container limit when containerized) if ($overview->limits !== null) { echo "Memory: " . round($overview->limits->memoryUtilization(), 1) . "%\n"; echo "Containerized: " . ($overview->limits->isContainerized() ? 'yes' : 'no') . "\n"; } // Load Average echo "Load Average (1 min): {$overview->loadAverage?->oneMinute}\n"; // Uptime echo "Uptime: {$overview->uptime?->humanReadable()}\n"; } ``` ### Individual Metrics [](#individual-metrics) ``` // Environment detection $env = SystemMetrics::environment()->getValue(); echo "OS: {$env->os->family->value}\n"; // CPU metrics $cpu = SystemMetrics::cpu()->getValue(); echo "CPU Cores: {$cpu->coreCount()}\n"; // Memory metrics $mem = SystemMetrics::memory()->getValue(); echo "Memory: " . round($mem->usedPercentage(), 1) . "%\n"; // Load average $load = SystemMetrics::loadAverage()->getValue(); echo "Load (1 min): {$load->oneMinute}\n"; // Storage metrics $storage = SystemMetrics::storage()->getValue(); echo "Storage: " . round($storage->usedPercentage(), 1) . "%\n"; // Network metrics $network = SystemMetrics::network()->getValue(); echo "Interfaces: " . count($network->interfaces) . "\n"; // Container metrics (cgroups) $container = SystemMetrics::container()->getValue(); if ($container->hasCpuLimit()) { echo "Container CPU limit: {$container->cpuQuota} cores\n"; } // Unified limits (environment-aware) $limits = SystemMetrics::limits()->getValue(); echo "Available CPU: {$limits->availableCpuCores()} cores\n"; echo "Available Memory: " . round($limits->availableMemoryBytes() / 1024**3, 2) . " GB\n"; // Process monitoring $process = ProcessMetrics::snapshot(getmypid())->getValue(); echo "Process Memory: " . round($process->resources->memoryRssBytes / 1024**2, 2) . " MB\n"; ``` ### CPU Usage Percentage [](#cpu-usage-percentage) CPU metrics return raw time counters. To calculate usage percentage: ``` // Convenience method (blocks for 1 second) $delta = SystemMetrics::cpuUsage(1.0)->getValue(); echo "CPU Usage: " . round($delta->usagePercentage(), 1) . "%\n"; // Or manually with two snapshots $snap1 = SystemMetrics::cpu()->getValue(); sleep(2); $snap2 = SystemMetrics::cpu()->getValue(); $delta = CpuSnapshot::calculateDelta($snap1, $snap2); echo "CPU Usage: " . round($delta->usagePercentage(), 1) . "%\n"; ``` ### Error Handling [](#error-handling) All methods return `Result` for explicit error handling: ``` $result = SystemMetrics::memory(); if ($result->isSuccess()) { $memory = $result->getValue(); echo "Memory: " . round($memory->usedPercentage(), 1) . "%\n"; } else { echo "Error: " . $result->getError()->getMessage() . "\n"; } // Or use functional style SystemMetrics::cpu() ->onSuccess(fn($cpu) => echo "CPU: {$cpu->coreCount()} cores\n") ->onFailure(fn($err) => error_log($err->getMessage())); ``` Documentation ------------- [](#documentation) Comprehensive documentation is available in the [docs/](docs/) directory: ### Getting Started [](#getting-started) - **[Introduction](docs/introduction.md)** - Overview and key features - **[Installation](docs/installation.md)** - Installation and setup - **[Quick Start](docs/quickstart.md)** - 30-second working example ### Basic Usage [](#basic-usage) - **[Environment Detection](docs/basic-usage/environment-detection.md)** - OS, kernel, architecture, containers - **[CPU Metrics](docs/basic-usage/cpu-metrics.md)** - CPU time counters and core data - **[Memory Metrics](docs/basic-usage/memory-metrics.md)** - Physical RAM and swap - **[Load Average](docs/basic-usage/load-average.md)** - System load metrics - **[System Uptime](docs/basic-usage/uptime.md)** - Boot time tracking - **[Storage Metrics](docs/basic-usage/storage-metrics.md)** - Filesystem and disk I/O - **[Network Metrics](docs/basic-usage/network-metrics.md)** - Interface statistics - **[System Overview](docs/basic-usage/system-overview.md)** - Complete snapshot ### Advanced Features [](#advanced-features) - **[Container Metrics](docs/advanced-usage/container-metrics.md)** - Cgroup v1/v2, Docker, Kubernetes - **[Process Metrics](docs/advanced-usage/process-metrics.md)** - Process monitoring and tracking - **[Unified Limits](docs/advanced-usage/unified-limits.md)** - Environment-aware resource limits - **[CPU Usage Calculation](docs/advanced-usage/cpu-usage-calculation.md)** - Delta between snapshots - **[Error Handling](docs/advanced-usage/error-handling.md)** - Result pattern deep dive - **[Custom Implementations](docs/advanced-usage/custom-implementations.md)** - Extend with custom sources ### Architecture [](#architecture) - **[Design Principles](docs/architecture/design-principles.md)** - Architectural philosophy - **[Result Pattern](docs/architecture/result-pattern.md)** - Error handling approach - **[Composite Sources](docs/architecture/composite-sources.md)** - Fallback logic - **[Immutable DTOs](docs/architecture/immutable-dtos.md)** - Data structures - **[Action Pattern](docs/architecture/action-pattern.md)** - Use case encapsulation - **[Performance Caching](docs/architecture/performance-caching.md)** - Optimization strategies ### Platform Support [](#platform-support) - **[Linux](docs/platform-support/linux.md)** - Linux-specific implementation - **[macOS](docs/platform-support/macos.md)** - macOS-specific implementation - **[Comparison](docs/platform-support/comparison.md)** - Feature parity table ### Reference [](#reference) - **[API Reference](docs/api-reference.md)** - Complete method documentation - **[Testing Guide](docs/testing.md)** - Running tests and coverage - **[Roadmap](docs/roadmap.md)** - Planned features Testing ------- [](#testing) ``` # Run tests composer test # With coverage composer test-coverage # Static analysis composer analyse # Code style composer format ``` See [Testing Guide](docs/testing.md) for details. Changelog --------- [](#changelog) Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. Contributing ------------ [](#contributing) Please see [CONTRIBUTING](CONTRIBUTING.md) for details. Security -------- [](#security) Please review [our security policy](SECURITY.md) on how to report security vulnerabilities. Credits ------- [](#credits) - [Sylvester Damgaard](https://github.com/sylvesterdamgaard) - [All Contributors](../../contributors) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 48 — FairBetter than 94% of packages Maintenance90 Actively maintained with recent releases Popularity20 Limited adoption so far Community11 Small or concentrated contributor base Maturity58 Maturing project, gaining track record Bus Factor1 Top contributor holds 97.2% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~9 days Recently: every ~15 days Total 14 Last Release 50d ago Major Versions v0.1.0 → v1.0.02025-11-17 v1.6.0 → v2.0.02026-01-16 ### Community Maintainers ![](https://www.gravatar.com/avatar/b9761a79e61f2d5b9d650510dfb3555da18daf38f027aa84012c937e397e39a7?d=identicon)[cboxdk](/maintainers/cboxdk) --- Top Contributors [![sylvesterdamgaard](https://avatars.githubusercontent.com/u/2431914?v=4)](https://github.com/sylvesterdamgaard "sylvesterdamgaard (139 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (3 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (1 commits)") --- Tags phpmonitoringperformancememoryCPUlinuxobservabilityserver monitoringmacossystem-metrics ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/cboxdk-system-metrics/health.svg) ``` [![Health](https://phpackages.com/badges/cboxdk-system-metrics/health.svg)](https://phpackages.com/packages/cboxdk-system-metrics) ``` ### Alternatives [inspector-apm/inspector-php Inspector monitoring for PHP applications. 342.4M15](/packages/inspector-apm-inspector-php) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)