Skip to content

api-reference.md

Latest commit

 

History

History
302 lines (218 loc) · 7.73 KB

api-reference.md

File metadata and controls

302 lines (218 loc) · 7.73 KB
title API Reference
description Complete API documentation for all public methods and classes in Cbox System Metrics
weight 80

API Reference

Complete API documentation for all public methods.

SystemMetrics Facade

Main entry point for system metrics.

SystemMetrics::environment(): Result<EnvironmentSnapshot>

Get environment detection (OS, kernel, architecture, virtualization, containers, cgroups).

Returns: Result<EnvironmentSnapshot> Caching: Results are automatically cached after first call Example:

$env = SystemMetrics::environment()->getValue();
echo "OS: {$env->os->name}\n";

SystemMetrics::cpu(): Result<CpuSnapshot>

Get CPU time counters (raw ticks, not percentages).

Returns: Result<CpuSnapshot> Example:

$cpu = SystemMetrics::cpu()->getValue();
echo "Cores: {$cpu->coreCount()}\n";

SystemMetrics::cpuUsage(float $interval): Result<CpuDelta>

Calculate CPU usage percentage over the specified interval (blocking).

Parameters:

  • $interval - Time to wait in seconds (e.g., 1.0 for 1 second)

Returns: Result<CpuDelta> Example:

$delta = SystemMetrics::cpuUsage(1.0)->getValue();
echo "CPU: " . round($delta->usagePercentage(), 1) . "%\n";

SystemMetrics::memory(): Result<MemorySnapshot>

Get memory metrics (physical RAM and swap).

Returns: Result<MemorySnapshot> Example:

$mem = SystemMetrics::memory()->getValue();
echo "Usage: " . round($mem->usedPercentage(), 1) . "%\n";

SystemMetrics::loadAverage(): Result<LoadAverageSnapshot>

Get system load average (1, 5, 15 minutes).

Returns: Result<LoadAverageSnapshot> Example:

$load = SystemMetrics::loadAverage()->getValue();
echo "Load (1 min): {$load->oneMinute}\n";

SystemMetrics::uptime(): Result<UptimeSnapshot>

Get system uptime since last boot.

Returns: Result<UptimeSnapshot> Example:

$uptime = SystemMetrics::uptime()->getValue();
echo "Uptime: {$uptime->humanReadable()}\n";

SystemMetrics::storage(): Result<StorageSnapshot>

Get filesystem usage and disk I/O statistics.

Returns: Result<StorageSnapshot> Example:

$storage = SystemMetrics::storage()->getValue();
foreach ($storage->mountPoints as $mount) {
    echo "{$mount->mountPoint}: {$mount->usedPercentage()}%\n";
}

SystemMetrics::network(): Result<NetworkSnapshot>

Get network interface statistics and connections.

Returns: Result<NetworkSnapshot> Example:

$network = SystemMetrics::network()->getValue();
foreach ($network->interfaces as $iface) {
    echo "{$iface->name}: {$iface->stats->totalBytes()} bytes\n";
}

SystemMetrics::container(): Result<ContainerLimits>

Get container resource limits and usage (cgroups).

Returns: Result<ContainerLimits> Example:

$container = SystemMetrics::container()->getValue();
if ($container->hasCpuLimit()) {
    echo "CPU quota: {$container->cpuQuota} cores\n";
}

SystemMetrics::limits(): Result<SystemLimits>

Get actual resource limits (environment-aware: host vs container).

Returns: Result<SystemLimits> Example:

$limits = SystemMetrics::limits()->getValue();
echo "CPU: {$limits->cpuCores} cores\n";
echo "Memory: " . round($limits->memoryBytes / 1024**3, 2) . " GB\n";

SystemMetrics::overview(): Result<SystemOverview>

Get complete snapshot of all available metrics in a single call.

Core metrics (environment, CPU, memory) are required — if any fail, the result is a failure. Optional metrics (storage, network, load average, uptime, limits, container) gracefully degrade to null.

Returns: Result<SystemOverview>

Properties:

Property Type Required
environment EnvironmentSnapshot Yes
cpu CpuSnapshot Yes
memory MemorySnapshot Yes
storage ?StorageSnapshot No
network ?NetworkSnapshot No
loadAverage ?LoadAverageSnapshot No
uptime ?UptimeSnapshot No
limits ?SystemLimits No
container ?ContainerLimits No

Example:

$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";
echo "Load: {$overview->loadAverage?->oneMinute}\n";
echo "Uptime: {$overview->uptime?->humanReadable()}\n";

if ($overview->limits?->isContainerized()) {
    echo "Container memory limit: " . round($overview->limits->memoryBytes / 1024**2) . " MB\n";
}

SystemMetrics::clearEnvironmentCache(): void

Clear cached environment detection results.

Returns: void Example:

SystemMetrics::clearEnvironmentCache();
$env = SystemMetrics::environment()->getValue();  // Fresh read

ProcessMetrics Facade

Process-level monitoring.

ProcessMetrics::snapshot(int $pid): Result<ProcessSnapshot>

Get one-time snapshot of a process.

Parameters:

  • $pid - Process ID

Returns: Result<ProcessSnapshot> Example:

$process = ProcessMetrics::snapshot(getmypid())->getValue();
echo "Memory: {$process->resources->memoryRssBytes} bytes\n";

ProcessMetrics::group(int $pid): Result<ProcessGroupSnapshot>

Get snapshot of process group (parent + all children).

Parameters:

  • $pid - Parent process ID

Returns: Result<ProcessGroupSnapshot> Example:

$group = ProcessMetrics::group($pid)->getValue();
echo "Total processes: {$group->totalProcessCount()}\n";

ProcessMetrics::start(int $pid, bool $includeChildren = false): Result<string>

Start tracking a process or process group.

Parameters:

  • $pid - Process ID
  • $includeChildren - Track children too

Returns: Result<string> - Tracker ID Example:

$trackerId = ProcessMetrics::start($pid)->getValue();

ProcessMetrics::sample(string $trackerId): Result<void>

Take manual sample of tracked process (optional).

Parameters:

  • $trackerId - Tracker ID from start()

Returns: Result<void> Example:

ProcessMetrics::sample($trackerId);

ProcessMetrics::stop(string $trackerId): Result<ProcessStats>

Stop tracking and get statistics.

Parameters:

  • $trackerId - Tracker ID from start()

Returns: Result<ProcessStats> Example:

$stats = ProcessMetrics::stop($trackerId)->getValue();
echo "Peak memory: {$stats->peak->memoryRssBytes} bytes\n";

Result Methods

All metrics methods return Result<T> objects with these methods:

isSuccess(): bool

Check if operation succeeded.

isFailure(): bool

Check if operation failed.

getValue(): T

Get the value (throws if failure).

getValueOr(T $default): T

Get value or default if failure.

getError(): ?Throwable

Get error (null if success).

map(callable $fn): Result

Transform success value.

onSuccess(callable $fn): Result

Execute callback on success.

onFailure(callable $fn): Result

Execute callback on failure.

Configuration

SystemMetricsConfig::setCpuMetricsSource(CpuMetricsSource $source): void

Set custom CPU metrics source.

SystemMetricsConfig::setMemoryMetricsSource(MemoryMetricsSource $source): void

Set custom memory metrics source.

SystemMetricsConfig::setEnvironmentDetector(EnvironmentDetector $detector): void

Set custom environment detector.

See Custom Implementations for details.

Related Documentation