daun/laravel-uptime-ping

Ping an endpoint regularly to monitor uptime and system status.

1.1.0 2024-11-11 17:59 UTC

Requires

• php: ^8.1
• laravel/framework: ^10.0 || ^11.0

Requires (Dev)

• guzzlehttp/guzzle: ^7.9
• larastan/larastan: ^2.9
• laravel/pint: ^1.14
• mockery/mockery: ^1.6
• orchestra/testbench: ^9.5
• pestphp/pest: ^3.5
• pestphp/pest-plugin-laravel: ^3.0
• spatie/laravel-ray: ^1.0

MIT

• Philipp Daun

• schedule
• laravel
• health-check
• uptime-monitoring
• uptime-ping
• dead-mans-switch

README

A dead man's switch for Laravel apps that regularly pings an endpoint to confirm the site is up and its task scheduler is processing important jobs, such as backups and notifications. A missed ping indicates issues with the job queue.

Useful with health monitors like Uptime Kuma.

Installation

Install the package via composer:

composer require daun/laravel-uptime-ping

How it works

An uptime ping sent from within the job queue is the most reliable method for detecting a broken job queue. While your site may be running, a misconfigured cron job might prevent your backups and notifications from being processed. A standard health check wouldn't necessarily identify this issue.

The package will send a GET request to your configured endpoint every minute. This way, you'll know immediately if the site goes down or the job queue stops processing items.

Basic setup

Define the URL to ping in your .env file. For more customization, see below.

UPTIME_PING_URL="https://uptime.kuma.instance/api/push/xxxxxxxxxx?status=up&msg=OK&ping="

Configuration

To change the frequency of pings, request method, timeout, number of retries, or add custom headers, publish and adjust the config file by running php artisan vendor:publish --tag=uptime-ping-config. Adjust any settings in config/uptime-ping.php.

return [

    /*
    | The URL to ping. If this is not set, the job will not run.
    */

    'url' => env('UPTIME_PING_URL', null),

    /*
    | The frequency at which to ping the URL, in crontab syntax. @see https://crontab.guru for help
    */

    'cron' => env('UPTIME_PING_CRON', '* * * * *'),

    /*
    | The HTTP method to use when pinging the URL.
    */

    'method' => env('UPTIME_PING_METHOD', 'GET'),

    /*
    | The number of retries to attempt before failing.
    */

    'retries' => 3,

    /*
    | The timeout in seconds before failing.
    */

    'timeout' => 3,

    /*
    | Additional headers to send with the request.
    */

    'headers' => [
        // 'User-Agent' => 'Laravel Uptime Ping',
    ],

];

License

MIT