Spatie CPU Load Health Check

https://github.com/spatie/cpu-load-health-check
Admin
Spatie CPU Load Health Check is a Laravel Health check package that measures CPU load and alerts you...
Tokens:12,263
Snippets:160
Trust Score:10
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install the package

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/QUICKSTART.md

Use Composer to add the package to your Laravel project.

```bash
composer require spatie/cpu-load-health-check
```

--------------------------------

### Usage Patterns for CpuLoad

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/module-reference.md

Examples for measuring system load directly or instantiating the DTO manually for testing purposes.

```php
use Spatie\CpuLoadHealthCheck\CpuLoad;

$load = CpuLoad::measure();
echo "Last minute: {$load->lastMinute}";
echo "Last 5 minutes: {$load->last5Minutes}";
echo "Last 15 minutes: {$load->last15Minutes}";
```

```php
$load = new CpuLoad(1.5, 1.2, 0.9);
```

--------------------------------

### Direct Measurement Error Handling

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/module-reference.md

Example of catching the exception when performing a direct CPU load measurement.

```php
use Spatie\CpuLoadHealthCheck\CpuLoad;
use Spatie\
CpuLoadHealthCheck\Exceptions\CouldNotMeasureCpuLoad;

try {
    $load = CpuLoad::measure();
} catch (CouldNotMeasureCpuLoad $e) {
    // Handle error - sys_getloadavg() not available
    log_error($e->getMessage());
}
```

--------------------------------

### Resilient Subclassing

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/module-reference.md

Example of extending CpuLoadCheck to provide a fallback value when measurement fails.

```php
use Spatie\CpuLoadHealthCheck\CpuLoadCheck;
use Spatie\CpuLoadHealthCheck\CpuLoad;
use Spatie\CpuLoadHealthCheck\Exceptions\CouldNotMeasureCpuLoad;

class SafeCpuLoadCheck extends CpuLoadCheck
{
    protected function measureCpuLoad(): CpuLoad
    {
        try {
            return CpuLoad::measure();
        } catch (CouldNotMeasureCpuLoad $e) {
            return new CpuLoad(0, 0, 0);
        }
    }
}
```

--------------------------------

### CpuLoadCheck Usage Pattern

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/module-reference.md

Example of registering the check within a Laravel service provider.

```php
use Spatie\Health\Facades\Health;
use Spatie\CpuLoadHealthCheck\CpuLoadCheck;

// In a service provider boot() method or config file:
Health::checks([
    CpuLoadCheck::new()
        ->failWhenLoadIsHigherInTheLast5Minutes(1.2)
        ->failWhenLoadIsHigherInTheLast15Minutes(1.5),
]);
```

--------------------------------

### Access Result Properties

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/types.md

Example of running a health check and accessing the resulting status and metadata.

```php
use Spatie\Health\Checks\Result;
use Spatie\CpuLoadHealthCheck\CpuLoadCheck;

$check = CpuLoadCheck::new()
    ->failWhenLoadIsHigherInTheLast5Minutes(1.2);

$result = $check->run();

// Access result properties
echo $result->status;           // Enum: ok or failed
echo $result->errorMessage;     // Error description if failed
echo $result->meta['last_minute'];  // Metadata value
```

--------------------------------

### Running Tests

Source: https://github.com/spatie/cpu-load-health-check/blob/main/README.md

Execute the package test suite using Composer.

```bash
composer test
```

--------------------------------

### Log CPU Metrics via Console Command

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/usage-examples.md

Implement a long-running console command to periodically capture and log system CPU load averages.

```php
<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Spatie\CpuLoadHealthCheck\CpuLoad;
use Spatie\CpuLoadHealthCheck\Exceptions\CouldNotMeasureCpuLoad;
use Illuminate\Support\Facades\Log;

class LogCpuMetrics extends Command
{
    protected $signature = 'metrics:log-cpu {--interval=5}';
    
    public function handle(): int
    {
        $interval = (int) $this->option('interval');
        
        while (true) {
            try {
                $load = CpuLoad::measure();
                
                Log::info('CPU metrics', [
                    'last_minute' => $load->lastMinute,
                    'last_5_minutes' => $load->last5Minutes,
                    'last_15_minutes' => $load->last15Minutes,
                ]);
            } catch (CouldNotMeasureCpuLoad $e) {
                Log::warning('Cannot measure CPU load');
            }
            
            sleep($interval);
        }
    }
}
```

--------------------------------

### Fluent Method Chaining

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/configuration.md

Demonstrates the fluent interface where each configuration method returns the check instance.

```php
$check = CpuLoadCheck::new()
    ->failWhenLoadIsHigherInTheLastMinute(2.5)
    ->failWhenLoadIsHigherInTheLast5Minutes(1.8);
```

--------------------------------

### CpuLoadCheck Configuration Methods

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/module-reference.md

Methods for setting CPU load thresholds for different time windows.

```php
public function failWhenLoadIsHigherInTheLastMinute(float $load): self
public function failWhenLoadIsHigherInTheLast5Minutes(float $load): self
public function failWhenLoadIsHigherInTheLast15Minutes(float $load): self
```

--------------------------------

### Initialize CpuLoad instance

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/api-reference.md

Create a new CpuLoad object by manually providing load averages for the three time windows.

```php
public function __construct(
    public float $lastMinute,
    public float $last5Minutes,
    public float $last15Minutes,
)
```

```php
use Spatie\CpuLoadHealthCheck\CpuLoad;

$cpuLoad = new CpuLoad(1.25, 1.50, 1.75);
echo $cpuLoad->lastMinute;    // 1.25
echo $cpuLoad->last5Minutes;  // 1.50
echo $cpuLoad->last15Minutes; // 1.75
```

--------------------------------

### Construct CpuLoad Instance

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/types.md

Manual construction and factory method usage for CpuLoad.

```php
$cpuLoad = new CpuLoad(1.25, 1.50, 1.75);
```

```php
$cpuLoad = CpuLoad::measure();
```

--------------------------------

### Access CpuLoad Properties

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/types.md

Demonstrates how to measure CPU load and access individual load properties.

```php
use Spatie\CpuLoadHealthCheck\CpuLoad;

$cpuLoad = CpuLoad::measure();

// Access properties directly
$oneMinute = $cpuLoad->lastMinute;
$fiveMinutes = $cpuLoad->last5Minutes;
$fifteenMinutes = $cpuLoad->last15Minutes;

// Use in comparisons
if ($cpuLoad->lastMinute > 2.0) {
    echo "High CPU load detected";
}
```

--------------------------------

### Configure CPU Load Thresholds

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/INDEX.md

Use fluent method chaining on the CpuLoadCheck instance to set thresholds for 1, 5, and 15-minute load averages. Unconfigured thresholds are ignored during the health check.

```php
CpuLoadCheck::new()
    ->failWhenLoadIsHigherInTheLastMinute(3.0)
    ->failWhenLoadIsHigherInTheLast5Minutes(2.5)
    ->failWhenLoadIsHigherInTheLast15Minutes(2.0)
```

--------------------------------

### Measure CPU Load via Static Method

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/module-reference.md

Returns a new CpuLoad instance with current system load values rounded to two decimal places.

```php
public static function measure(): self
```

--------------------------------

### Configure CPU Load Thresholds

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/INDEX.md

Sets failure thresholds for CPU load averages over 5 and 15-minute intervals using method chaining.

```php
$check->failWhenLoadIsHigherInTheLast5Minutes(1.2)
      ->failWhenLoadIsHigherInTheLast15Minutes(1.5);
```

--------------------------------

### CpuLoadCheck::run

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/overview.md

Executes the configured CPU load check.

```APIDOC
## CpuLoadCheck::run()

### Description
Executes the health check based on configured thresholds.

### Returns
- **Result** - The result of the health check execution.
```

--------------------------------

### CpuLoadCheck Configuration Methods

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/module-reference.md

Methods to set CPU load thresholds for different time intervals.

```APIDOC
## Configuration Methods

### Description
Sets the CPU load threshold for specific time windows. If the load exceeds the provided value, the health check will fail.

### Methods
- `failWhenLoadIsHigherInTheLastMinute(float $load): self`
- `failWhenLoadIsHigherInTheLast5Minutes(float $load): self`
- `failWhenLoadIsHigherInTheLast15Minutes(float $load): self`

### Parameters
- **$load** (float) - Required - The CPU load threshold value.
```

--------------------------------

### Integration in a Command

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/usage-examples.md

Use the CpuLoad class to measure system load before executing a long-running task. Handle potential measurement exceptions to ensure command resilience.

```php
<?php

namespace App\\Console\\Commands;

use Illuminate\\Console\\Command;
use Spatie\\CpuLoadHealthCheck\\CpuLoad;
use Spatie\\CpuLoadHealthCheck\\Exceptions\\CouldNotMeasureCpuLoad;

class ProcessHeavyTask extends Command
{
    protected $signature = 'process:heavy-task';
    
    public function handle(): int
    {
        try {
            $load = CpuLoad::measure();
            
            if ($load->lastMinute > 3.0) {
                $this->error('CPU load is too high. Aborting.');
                return self::FAILURE;
            }
            
            $this->info("CPU load is acceptable. Last minute: {$load->lastMinute}");
            
            // Execute the heavy task
            $this->executeHeavyTask();
            
            return self::SUCCESS;
        } catch (CouldNotMeasureCpuLoad $e) {
            $this->warn('Cannot measure CPU load. Proceeding anyway.');
            $this->executeHeavyTask();
            return self::SUCCESS;
        }
    }
    
    private function executeHeavyTask(): void
    {
        // Long-running operation
    }
}
```

--------------------------------

### run()

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/api-reference.md

Executes the CPU load check and returns a health check result containing status and metadata.

```APIDOC
## run()

### Description
Executes the CPU load check and returns a health check result. This method is called by the Laravel Health package during health monitoring.

### Returns
- **Spatie\Health\Checks\Result** - A result object containing the check status, summary, and metadata.

### Meta Data
- **last_minute** (float) - CPU load for the last minute
- **last_5_minutes** (float) - CPU load for the last 5 minutes
- **last_15_minutes** (float) - CPU load for the last 15 minutes
```

--------------------------------

### CpuLoadCheck::new

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/overview.md

Creates a new instance of the CpuLoadCheck class.

```APIDOC
## CpuLoadCheck::new()

### Description
Creates a new check instance.

### Returns
- **self** - The new CpuLoadCheck instance.
```

--------------------------------

### Configure 1-minute CPU load threshold

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/api-reference.md

Sets the failure threshold for CPU load over the last minute using the fluent configuration method.

```php
use Spatie\CpuLoadHealthCheck\CpuLoadCheck;

$check = CpuLoadCheck::new()
    ->failWhenLoadIsHigherInTheLastMinute(2.5);
```

--------------------------------

### Execute CPU load check and handle results

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/api-reference.md

Runs the configured health check and demonstrates how to access the status and metadata.

```php
use Spatie\CpuLoadHealthCheck\CpuLoadCheck;

$check = CpuLoadCheck::new()
    ->failWhenLoadIsHigherInTheLast5Minutes(1.5)
    ->failWhenLoadIsHigherInTheLast15Minutes(2.0);

$result = $check->run();

if ($result->status->isFailed()) {
    echo "Check failed: " . $result->errorMessage;
}

// Access metadata
echo "Last minute load: " . $result->meta['last_minute'];
```

--------------------------------

### Create a Custom Configuration Class for CpuLoadCheck

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/usage-examples.md

Encapsulate check thresholds within a static factory method to centralize configuration. Ensure the health check is registered in your service provider or configuration file.

```php
<?php

namespace App\Health;

use Spatie\CpuLoadHealthCheck\CpuLoadCheck;

class CpuLoadCheckConfiguration
{
    public static function create(): CpuLoadCheck
    {
        return CpuLoadCheck::new()
            ->failWhenLoadIsHigherInTheLastMinute(
                config('health.cpu_load.last_minute', 3.0)
            )
            ->failWhenLoadIsHigherInTheLast5Minutes(
                config('health.cpu_load.last_5_minutes', 2.5)
            )
            ->failWhenLoadIsHigherInTheLast15Minutes(
                config('health.cpu_load.last_15_minutes', 2.0)
            );
    }
}

// In config/health.php or your HealthServiceProvider:
use App\Health\CpuLoadCheckConfiguration;

Health::checks([
    CpuLoadCheckConfiguration::create(),
]);
```

--------------------------------

### Checking Availability

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/errors.md

Verifies if the environment supports CPU load monitoring before attempting measurement.

```php
use Spatie\\\CpuLoadHealthCheck\\\CpuLoad;

if (function_exists('sys_getloadavg')) {
    try {
        $load = CpuLoad::measure();
        // Process load data
    } catch (CouldNotMeasureCpuLoad $e) {
        // Handle measurement failure
    }
} else {
    // sys_getloadavg not available on this system
    echo "CPU load monitoring not supported on this platform";
}
```

--------------------------------

### Configure 15-minute CPU load threshold

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/api-reference.md

Sets the failure threshold for CPU load over the last 15 minutes using the fluent configuration method.

```php
use Spatie\CpuLoadHealthCheck\CpuLoadCheck;

$check = CpuLoadCheck::new()
    ->failWhenLoadIsHigherInTheLast15Minutes(3.0);
```

--------------------------------

### Importing CPU Load Classes

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/overview.md

Use these imports when interacting directly with the package classes.

```php
use Spatie\CpuLoadHealthCheck\CpuLoadCheck;
use Spatie\CpuLoadHealthCheck\CpuLoad;
use Spatie\CpuLoadHealthCheck\Exceptions\CouldNotMeasureCpuLoad;
```

--------------------------------

### CpuLoadCheck API reference

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/QUICKSTART.md

Available methods for configuring the CpuLoadCheck instance.

```php
CpuLoadCheck::new()
    ->failWhenLoadIsHigherInTheLastMinute(float)    // Optional
    ->failWhenLoadIsHigherInTheLast5Minutes(float)  // Optional
    ->failWhenLoadIsHigherInTheLast15Minutes(float) // Optional
    ->run()  // Returns Result with status and metadata
```

--------------------------------

### Monitor Without Thresholds

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/configuration.md

Initializes the check without thresholds to retrieve load metrics via metadata without triggering failures.

```php
use Spatie\CpuLoadHealthCheck\CpuLoadCheck;

$check = CpuLoadCheck::new();
$result = $check->run();

// Result will always be ok, but includes metadata
echo $result->meta['last_minute'];      // e.g., 1.25
echo $result->meta['last_5_minutes'];   // e.g., 1.50
echo $result->meta['last_15_minutes'];  // e.g., 1.75
```

--------------------------------

### CpuLoad::__construct

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/api-reference.md

Creates a new CpuLoad instance with specified CPU load measurements.

```APIDOC
## public __construct(float $lastMinute, float $last5Minutes, float $last15Minutes)

### Description
Creates a new CpuLoad instance with three CPU load measurements.

### Parameters
- **lastMinute** (float) - Required - CPU load average over the last minute
- **last5Minutes** (float) - Required - CPU load average over the last 5 minutes
- **last15Minutes** (float) - Required - CPU load average over the last 15 minutes
```

--------------------------------

### Debug CPU load thresholds

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/QUICKSTART.md

Retrieve and display current load metrics to verify if thresholds are configured correctly.

```php
$load = CpuLoad::measure();
echo "Current: {$load->last5Minutes}, Threshold: 1.2";
```

--------------------------------

### Measure CPU load in commands

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/QUICKSTART.md

Use the CpuLoad class to manually measure and output current CPU load metrics.

```php
use Spatie\CpuLoadHealthCheck\CpuLoad;

$load = CpuLoad::measure();
echo "CPU load (1m): {$load->lastMinute}";
```

--------------------------------

### CpuLoad Constructor

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/module-reference.md

Creates a new CpuLoad instance with specific load values for the last 1, 5, and 15 minutes.

```APIDOC
## public function __construct(float $lastMinute, float $last5Minutes, float $last15Minutes)

### Description
Initializes a new CpuLoad object with the provided load averages. The properties are public and readonly.

### Parameters
- **lastMinute** (float) - Required - CPU load average for the last minute.
- **last5Minutes** (float) - Required - CPU load average for the last 5 minutes.
- **last15Minutes** (float) - Required - CPU load average for the last 15 minutes.
```

--------------------------------

### CpuLoad::measure()

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/types.md

Static factory method to retrieve current CPU load averages.

```APIDOC
## CpuLoad::measure()

### Description
Retrieves the current CPU load averages as a CpuLoad object. Values are derived from sys_getloadavg() and rounded to 2 decimal places.

### Returns
- **CpuLoad** - An instance containing lastMinute, last5Minutes, and last15Minutes properties.
```

--------------------------------

### Test CPU Load with FakeCpuLoadCheck

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/usage-examples.md

Use the FakeCpuLoadCheck class to mock CPU load measurements during testing.

```php
<?php

namespace Tests\Feature;

use Spatie\CpuLoadHealthCheck\Tests\TestClasses\FakeCpuLoadCheck;
use PHPUnit\Framework\TestCase;

class CpuLoadCheckTest extends TestCase
{
    public function test_check_passes_when_load_is_low(): void
    {
        $result = FakeCpuLoadCheck::new()
            ->fakeCpuLoad(0.5, 0.6, 0.7)  // Set specific load values
            ->failWhenLoadIsHigherInTheLast5Minutes(1.0)
            ->run();
        
        $this->assertTrue($result->status->isOk());
    }
    
    public function test_check_fails_when_load_exceeds_threshold(): void
    {
        $result = FakeCpuLoadCheck::new()
            ->fakeCpuLoad(1.5, 1.5, 1.5)  // Set high load values
            ->failWhenLoadIsHigherInTheLast5Minutes(1.0)
            ->run();
        
        $this->assertTrue($result->status->isFailed());
    }
    
    public function test_check_reports_load_in_metadata(): void
    {
        $result = FakeCpuLoadCheck::new()
            ->fakeCpuLoad(0.25, 0.50, 0.75)
            ->run();
        
        $this->assertEquals(0.25, $result->meta['last_minute']);
        $this->assertEquals(0.50, $result->meta['last_5_minutes']);
        $this->assertEquals(0.75, $result->meta['last_15_minutes']);
    }
}
```

--------------------------------

### Monitoring CPU Load Without Thresholds

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/usage-examples.md

Register the check without thresholds to collect metrics for dashboards and observability without triggering health check failures.

```php
use Spatie\Health\Facades\Health;
use Spatie\CpuLoadHealthCheck\CpuLoadCheck;

Health::checks([
    CpuLoadCheck::new(),  // No thresholds configured
]);
```

--------------------------------

### Configure Single Threshold

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/configuration.md

Sets a failure threshold for the 5-minute CPU load average only.

```php
use Spatie\CpuLoadHealthCheck\CpuLoadCheck;

$check = CpuLoadCheck::new()
    ->failWhenLoadIsHigherInTheLast5Minutes(1.2);
```

--------------------------------

### Registering the CPU Load Check

Source: https://github.com/spatie/cpu-load-health-check/blob/main/README.md

Register the check within a service provider to monitor CPU load over the last 5 minutes.

```php
// typically, in a service provider

use Spatie\Health\Facades\Health;
use Spatie\CpuLoadHealthCheck\CpuLoadCheck;

Health::checks([
    CpuLoadCheck::new()->failWhenLoadIsHigherInTheLast5Minutes(1.2),
]);
```

--------------------------------

### Configure Multiple Thresholds

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/configuration.md

Sets failure thresholds for all three available time windows.

```php
use Spatie\CpuLoadHealthCheck\CpuLoadHealthCheck;

$check = CpuLoadCheck::new()
    ->failWhenLoadIsHigherInTheLastMinute(2.0)
    ->failWhenLoadIsHigherInTheLast5Minutes(1.5)
    ->failWhenLoadIsHigherInTheLast15Minutes(1.2);
```

--------------------------------

### Implement Conditional Logic Based on CPU Load

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/usage-examples.md

Adjust application behavior by checking load averages before executing tasks.

```php
use Spatie\CpuLoadHealthCheck\CpuLoad;
use Spatie\CpuLoadHealthCheck\Exceptions\CouldNotMeasureCpuLoad;

try {
    $load = CpuLoad::measure();
    
    if ($load->lastMinute > 2.0) {
        // High immediate load - defer heavy operations
        queue_operation(job: $heavyJob, delay: 60);
    } elseif ($load->last5Minutes > 1.5) {
        // Moderate load - proceed with caution
        queue_operation(job: $mediumJob);
    } else {
        // Low load - execute immediately
        execute_immediately($lightJob);
    }
} catch (CouldNotMeasureCpuLoad $e) {
    // Fallback to immediate execution if unable to measure
    execute_immediately($lightJob);
}
```

--------------------------------

### Registering CPU Load Check in Service Provider

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/usage-examples.md

Register the check within a Laravel service provider's boot method to monitor CPU load with a specific threshold.

```php
<?php

namespace App\Providers;

use Spatie\Health\Facades\Health;
use Spatie\CpuLoadHealthCheck\CpuLoadCheck;
use Illuminate\Support\ServiceProvider;

class HealthServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Health::checks([
            CpuLoadCheck::new()
                ->failWhenLoadIsHigherInTheLast5Minutes(1.2),
        ]);
    }
}
```

--------------------------------

### Collect metrics without thresholds

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/QUICKSTART.md

Initialize the check without failure thresholds to report metrics only.

```php
CpuLoadCheck::new()  // No thresholds - always passes but reports metrics
```

--------------------------------

### Create a Resilient Health Check

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/usage-examples.md

Extend CpuLoadCheck to handle measurement failures by returning neutral values instead of throwing exceptions.

```php
use Spatie\CpuLoadHealthCheck\CpuLoadCheck;
use Spatie\CpuLoadHealthCheck\CpuLoad;
use Spatie\CpuLoadHealthCheck\Exceptions\CouldNotMeasureCpuLoad;

class ResilientCpuLoadCheck extends CpuLoadCheck
{
    protected function measureCpuLoad(): CpuLoad
    {
        try {
            return CpuLoad::measure();
        } catch (CouldNotMeasureCpuLoad $e) {
            // Return neutral values instead of throwing
            // Useful when sys_getloadavg is not available
            return new CpuLoad(0, 0, 0);
        }
    }
}

// Usage
use Spatie\Health\Facades\Health;

Health::checks([
    ResilientCpuLoadCheck::new()
        ->failWhenLoadIsHigherInTheLast5Minutes(1.2),
]);
```

--------------------------------

### Measure system CPU load

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/api-reference.md

Retrieve current system load averages using the static measure method, which requires a Unix-like environment.

```php
public static function measure(): self
```

```php
use Spatie\CpuLoadHealthCheck\CpuLoad;

try {
    $cpuLoad = CpuLoad::measure();
    echo "1-minute load: {$cpuLoad->lastMinute}";
    echo "5-minute load: {$cpuLoad->last5Minutes}";
    echo "15-minute load: {$cpuLoad->last15Minutes}";
} catch (CouldNotMeasureCpuLoad $e) {
    echo "Failed to measure CPU load: " . $e->getMessage();
}
```

--------------------------------

### Reporting Dashboard Metrics

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/QUICKSTART.md

Initialize a check without thresholds to retrieve load metadata for display purposes.

```php
CpuLoadCheck::new()  // No thresholds
// Reports 1m/5m/15m load in metadata
// Dashboard can display without triggering alerts
```

--------------------------------

### Accessing Check Results

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/usage-examples.md

Run a CPU load check and handle the result status and metadata. Ensure the threshold is configured before calling the run method.

```php
use Spatie\\\CpuLoadHealthCheck\\\CpuLoadCheck;

$check = CpuLoadCheck::new()
    ->failWhenLoadIsHigherInTheLast5Minutes(1.2);

$result = $check->run();

// Check status
if ($result->status->isOk()) {
    echo "CPU load is healthy";
} else {
    echo "Alert: " . $result->errorMessage;
}

// Access load values from metadata
$loads = [
    'last_minute' => $result->meta['last_minute'],
    'last_5_minutes' => $result->meta['last_5_minutes'],
    'last_15_minutes' => $result->meta['last_15_minutes'],
];

// Use in logging
log_cpu_metrics($loads);
```

--------------------------------

### Throttle Queue Job Execution by CPU Load

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/usage-examples.md

Use this pattern within a queue job to defer processing when the 5-minute CPU load average exceeds a specified threshold.

```php
<?php

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Spatie\CpuLoadHealthCheck\CpuLoad;
use Spatie\CpuLoadHealthCheck\Exceptions\CouldNotMeasureCpuLoad;

class ProcessDataBatch implements ShouldQueue
{
    use Queueable;
    
    public function handle(): void
    {
        try {
            $load = CpuLoad::measure();
            
            if ($load->last5Minutes > 2.0) {
                // Defer execution by 1 minute and retry
                $this->release(60);
                return;
            }
        } catch (CouldNotMeasureCpuLoad $e) {
            // Continue regardless if measurement fails
        }
        
        // Process the batch
        $this->processBatch();
    }
    
    private function processBatch(): void
    {
        // Data processing logic
    }
}
```

--------------------------------

### Register CPU Load Check conditionally

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/usage-examples.md

Register the check only on Unix-like systems that support sys_getloadavg.

```php
use Spatie\Health\Facades\Health;
use Spatie\CpuLoadHealthCheck\CpuLoadCheck;

// Only register on Unix-like systems
if (function_exists('sys_getloadavg')) {
    Health::checks([
        CpuLoadCheck::new()
            ->failWhenLoadIsHigherInTheLast5Minutes(1.2),
    ]);
}
```

```php
class HealthServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Health::checks(
            $this->getHealthChecks()
        );
    }
    
    private function getHealthChecks(): array
    {
        $checks = [
            // Other checks...
        ];
        
        if ($this->isCpuMonitoringSupported()) {
            $checks[] = CpuLoadCheck::new()
                ->failWhenLoadIsHigherInTheLast5Minutes(1.2);
        }
        
        return $checks;
    }
    
    private function isCpuMonitoringSupported(): bool
    {
        return function_exists('sys_getloadavg');
    }
}
```

--------------------------------

### CpuLoad Constructor Definition

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/module-reference.md

Initializes the DTO using PHP promoted properties, which are public and readonly.

```php
public function __construct(
    public float $lastMinute,
    public float $last5Minutes,
    public float $last15Minutes,
)
```

--------------------------------

### CpuLoadCheck Protected Properties

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/module-reference.md

Properties storing the configured load thresholds.

```php
protected ?float $failWhenLoadIsHigherInTheLastMinute = null;
protected ?float $failWhenLoadIsHigherInTheLast5Minutes = null;
protected ?float $failWhenLoadIsHigherInTheLast15Minutes = null;
```

--------------------------------

### Handling CouldNotMeasureCpuLoad

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/errors.md

Demonstrates catching the exception during direct measurement or by overriding the health check method.

```php
use Spatie\\\CpuLoadHealthCheck\\\CpuLoad;
use Spatie\\\CpuLoadHealthCheck\\\Exceptions\\\CouldNotMeasureCpuLoad;

try {
    $cpuLoad = CpuLoad::measure();
    echo "CPU load: {$cpuLoad->lastMinute}";
} catch (CouldNotMeasureCpuLoad $e) {
    echo "Cannot measure CPU load: " . $e->getMessage();
    // Log the error or handle gracefully
}
```

```php
use Spatie\\\CpuLoadHealthCheck\\\CpuLoadCheck;
use Spatie\\\CpuLoadHealthCheck\\\CpuLoad;
use Spatie\\\CpuLoadHealthCheck\\\Exceptions\\\CouldNotMeasureCpuLoad;
use Spatie\\\Health\\\Checks\\\Result;

class ResilientCpuLoadCheck extends CpuLoadCheck
{
    protected function measureCpuLoad(): CpuLoad
    {
        try {
            return CpuLoad::measure();
        } catch (CouldNotMeasureCpuLoad $e) {
            // Handle gracefully - return a neutral load value
            return new CpuLoad(0, 0, 0);
        }
    }
}
```

--------------------------------

### Handling CouldNotMeasureCpuLoad Exception

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/api-reference.md

Catch this exception when attempting to measure CPU load to handle cases where the system environment prevents the measurement.

```php
use Spatie\CpuLoadHealthCheck\Exceptions\CouldNotMeasureCpuLoad;

try {
    $cpuLoad = CpuLoad::measure();
} catch (CouldNotMeasureCpuLoad $e) {
    // Handle the exception
    log_error($e->getMessage());
}
```

--------------------------------

### Handle measurement exceptions

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/QUICKSTART.md

Catch exceptions when CPU load measurement is unavailable, such as on Windows or restricted environments.

```php
use Spatie\CpuLoadHealthCheck\CpuLoad;
use Spatie\CpuLoadHealthCheck\Exceptions\CouldNotMeasureCpuLoad;

try {
    $load = CpuLoad::measure();
} catch (CouldNotMeasureCpuLoad $e) {
    // sys_getloadavg() not available
    // (Usually on Windows or with disabled PHP functions)
}
```

--------------------------------

### CpuLoadCheck Measurement Method

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/module-reference.md

Protected method for measuring CPU load, overridable for testing.

```php
protected function measureCpuLoad(): CpuLoad
```

--------------------------------

### Handle missing sys_getloadavg function

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/QUICKSTART.md

Use this pattern to prevent errors on platforms where sys_getloadavg is unavailable or disabled.

```php
if (function_exists('sys_getloadavg')) {
    $load = CpuLoad::measure();
} else {
    // Fallback behavior
}
```

--------------------------------

### CpuLoadCheck::new

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/INDEX.md

Creates a new instance of the CpuLoadCheck class to be registered with the Laravel Health package.

```APIDOC
## CpuLoadCheck::new()

### Description
Creates a new instance of the CpuLoadCheck health check class.

### Signature
`public static function new(): self`

### Returns
- **self** - Returns the instance for fluent method chaining.
```

--------------------------------

### Composer Autoload Configuration

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/module-reference.md

PSR-4 autoloading configuration for the package.

```json
"autoload": {
    "psr-4": {
        "Spatie\\CpuLoadHealthCheck\\": "src"
    }
}
```

--------------------------------

### CpuLoadCheck Static Constructor

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/module-reference.md

Creates a new instance of the health check.

```php
public static function new(): self
```

--------------------------------

### CpuLoadCheck Threshold Configuration

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/INDEX.md

Methods to configure the CPU load thresholds that trigger a failure in the health check.

```APIDOC
## CpuLoadCheck Threshold Methods

### Description
Configures the load average thresholds for different time intervals. If the system load exceeds these values, the health check will fail.

### Methods
- `failWhenLoadIsHigherInTheLastMinute(float $load): self`
- `failWhenLoadIsHigherInTheLast5Minutes(float $load): self`
- `failWhenLoadIsHigherInTheLast15Minutes(float $load): self`

### Parameters
- **$load** (float) - Required - The CPU load threshold value.

### Returns
- **self** - Returns the instance for fluent method chaining.
```

--------------------------------

### CpuLoad direct measurement

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/QUICKSTART.md

Directly measure CPU load or instantiate the object manually for testing purposes.

```php
// Direct measurement
$load = CpuLoad::measure();  // Throws CouldNotMeasureCpuLoad if unavailable
echo $load->lastMinute;      // float
echo $load->last5Minutes;    // float
echo $load->last15Minutes;   // float

// Or create with specific values (useful for testing)
$load = new CpuLoad(1.5, 1.2, 0.9);
```

--------------------------------

### Responsive Queue Processing

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/QUICKSTART.md

Release a job back to the queue if the 5-minute load average is too high.

```php
if ($load->last5Minutes > 1.5) {
    $this->release(60);  // Retry in 1 minute
} else {
    $this->process();    // Process now
}
```

--------------------------------

### Static Factory Method

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/module-reference.md

The static factory method used to instantiate the exception.

```php
public static function make(): self
```

--------------------------------

### Measure CPU Load Directly

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/usage-examples.md

Use CpuLoad::measure() to retrieve load averages in non-Laravel environments or standalone scripts.

```php
use Spatie\CpuLoadHealthCheck\CpuLoad;
use Spatie\CpuLoadHealthCheck\Exceptions\CouldNotMeasureCpuLoad;

try {
    $load = CpuLoad::measure();
    
    echo "1-minute average: {$load->lastMinute}";
    echo "5-minute average: {$load->last5Minutes}";
    echo "15-minute average: {$load->last15Minutes}";
} catch (CouldNotMeasureCpuLoad $e) {
    echo "Could not measure CPU load: " . $e->getMessage();
}
```

--------------------------------

### CpuLoad::measure

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/INDEX.md

Measures the current system CPU load averages.

```APIDOC
## CpuLoad::measure()

### Description
Measures the current system CPU load averages and returns a CpuLoad object containing the values.

### Signature
`public static function measure(): self`

### Returns
- **CpuLoad** - An instance containing the measured load values for 1, 5, and 15 minutes.
```

--------------------------------

### Threshold Comparison Logic

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/configuration.md

Illustrates the internal strict greater-than comparison used to determine check failure.

```php
// Fails if:
if ($cpuLoad->lastMinute > $this->failWhenLoadIsHigherInTheLastMinute)

// Passes if:
$cpuLoad->lastMinute <= $this->failWhenLoadIsHigherInTheLastMinute
```

--------------------------------

### CpuLoad::measure()

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/module-reference.md

Measures the current system CPU load using sys_getloadavg() and returns a new CpuLoad instance with values rounded to two decimal places.

```APIDOC
## public static function measure()

### Description
Measures current system CPU load using PHP's sys_getloadavg() function. Returns a new CpuLoad instance with rounded values.

### Returns
- **self** - A new instance of CpuLoad containing the current load averages.
```

--------------------------------

### Command Safety Check

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/QUICKSTART.md

Abort console commands if the CPU load exceeds a defined limit.

```php
public function handle()
{
    $load = CpuLoad::measure();
    if ($load->lastMinute > 3.0) {
        $this->error('CPU too high. Aborting.');
        return 1;
    }
    // Proceed...
}
```

--------------------------------

### failWhenLoadIsHigherInTheLast5Minutes(float $load)

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/api-reference.md

Sets the failure threshold for CPU load over the last 5 minutes. The check will report a failed status if the current 5-minute load exceeds the provided value.

```APIDOC
## failWhenLoadIsHigherInTheLast5Minutes(float $load)

### Description
Sets the failure threshold for CPU load over the last 5 minutes. The check will report a failed status if the CPU load measured over the last 5 minutes is strictly greater than the specified threshold.

### Parameters
- **load** (float) - Required - The CPU load threshold.

### Returns
- **self** - Returns the check instance for fluent configuration.
```

--------------------------------

### CpuLoad::measure implementation

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/errors.md

The internal logic where the exception is raised when sys_getloadavg() returns false.

```php
public static function measure(): self
{
    $result = false;

    if (function_exists('sys_getloadavg')) {
        $result = sys_getloadavg();
    }

    if (! $result) {
        throw CouldNotMeasureCpuLoad::make();  // Exception raised here
    }

    // ...
}
```

--------------------------------

### failWhenLoadIsHigherInTheLast15Minutes(float $load)

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/api-reference.md

Sets the failure threshold for CPU load over the last 15 minutes. The check will report a failed status if the current 15-minute load exceeds the provided value.

```APIDOC
## failWhenLoadIsHigherInTheLast15Minutes(float $load)

### Description
Sets the failure threshold for CPU load over the last 15 minutes. The check will report a failed status if the CPU load measured over the last 15 minutes is strictly greater than the specified threshold.

### Parameters
- **load** (float) - Required - The CPU load threshold.

### Returns
- **self** - Returns the check instance for fluent configuration.
```

--------------------------------

### Register CPU Load Health Check

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/overview.md

Register the CPU load check within the Laravel Health framework, setting a failure threshold for the 5-minute load average.

```php
use Spatie\Health\Facades\Health;
use Spatie\CpuLoadHealthCheck\CpuLoadCheck;

Health::checks([
    CpuLoadCheck::new()
        ->failWhenLoadIsHigherInTheLast5Minutes(1.2),
]);
```

--------------------------------

### failWhenLoadIsHigherInTheLastMinute(float $load)

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/api-reference.md

Sets the failure threshold for CPU load over the last minute. The check will report a failed status if the current 1-minute load exceeds the provided value.

```APIDOC
## failWhenLoadIsHigherInTheLastMinute(float $load)

### Description
Sets the failure threshold for CPU load over the last minute. The check will report a failed status if the CPU load measured over the last minute is strictly greater than the specified threshold.

### Parameters
- **load** (float) - Required - The CPU load threshold.

### Returns
- **self** - Returns the check instance for fluent configuration.
```

--------------------------------

### CpuLoad Public Properties

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/module-reference.md

The three public readonly properties representing CPU load averages.

```php
public float $lastMinute;
public float $last5Minutes;
public float $last15Minutes;
```

--------------------------------

### CpuLoadCheck Execution Method

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/module-reference.md

Method called by the Laravel Health framework to perform the check.

```php
public function run(): Result
```

--------------------------------

### Define CpuLoad Class

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/types.md

The CpuLoad data class structure containing CPU load averages.

```php
class CpuLoad
{
    public float $lastMinute;
    public float $last5Minutes;
    public float $last15Minutes;
}
```

--------------------------------

### Preventing Heavy Operations

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/QUICKSTART.md

Check current load before dispatching jobs to manage system resources.

```php
use Spatie\CpuLoadHealthCheck\CpuLoad;

$load = CpuLoad::measure();
if ($load->lastMinute > 2.0) {
    Queue::delay(60)->push(new HeavyJob());
} else {
    Queue::push(new HeavyJob());
}
```

--------------------------------

### Minimal Import for Laravel Health

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/module-reference.md

Use this import for basic integration with the Laravel Health package.

```php
use Spatie\CpuLoadHealthCheck\CpuLoadCheck;
```

--------------------------------

### Importing for Laravel Health

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/overview.md

Use these imports when integrating the check with the Laravel Health package.

```php
use Spatie\Health\Facades\Health;
use Spatie\CpuLoadHealthCheck\CpuLoadCheck;
```

--------------------------------

### Register in Laravel Health

Source: https://github.com/spatie/cpu-load-health-check/blob/main/_autodocs/configuration.md

Registers the check within the Laravel Health configuration array.

```php
use Spatie\Health\Facades\Health;
use Spatie\CpuLoadHealthCheck\CpuLoadCheck;

Health::checks([
    CpuLoadCheck::new()
        ->failWhenLoadIsHigherInTheLastMinute(3.0)
        ->failWhenLoadIsHigherInTheLast5Minutes(2.5)
        ->failWhenLoadIsHigherInTheLast15Minutes(2.0),
]);
```
Tokens:
Raw