Cbox System Metrics

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

• Features
• Requirements
• Installation
• Quick Start
• Documentation
• Testing
• Changelog
• Contributing
• Security
• Credits
• License

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

• 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

composer require cboxdk/system-metrics

Quick Start

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

// 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 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

All methods return Result<T> 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

Comprehensive documentation is available in the docs/ directory:

Getting Started

• Introduction - Overview and key features
• Installation - Installation and setup
• Quick Start - 30-second working example

Basic Usage

• Environment Detection - OS, kernel, architecture, containers
• CPU Metrics - CPU time counters and core data
• Memory Metrics - Physical RAM and swap
• Load Average - System load metrics
• System Uptime - Boot time tracking
• Storage Metrics - Filesystem and disk I/O
• Network Metrics - Interface statistics
• System Overview - Complete snapshot

Advanced Features

• Container Metrics - Cgroup v1/v2, Docker, Kubernetes
• Process Metrics - Process monitoring and tracking
• Unified Limits - Environment-aware resource limits
• CPU Usage Calculation - Delta between snapshots
• Error Handling - Result pattern deep dive
• Custom Implementations - Extend with custom sources

Architecture

• Design Principles - Architectural philosophy
• Result Pattern - Error handling approach
• Composite Sources - Fallback logic
• Immutable DTOs - Data structures
• Action Pattern - Use case encapsulation
• Performance Caching - Optimization strategies

Platform Support

• Linux - Linux-specific implementation
• macOS - macOS-specific implementation
• Comparison - Feature parity table

Reference

• API Reference - Complete method documentation
• Testing Guide - Running tests and coverage
• Roadmap - Planned features

Testing

# Run tests
composer test

# With coverage
composer test-coverage

# Static analysis
composer analyse

# Code style
composer format

See Testing Guide for details.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

Please review our security policy on how to report security vulnerabilities.

Credits

• Sylvester Damgaard
• All Contributors

License

The MIT License (MIT). Please see License File for more information.