Scrutiny helps your Laravel 8 project ensure that its current server environment is configured and running as planned.
Have you ever been in the situation where you've moved servers and forgotten to:
- Get your queue running?
- Add the cron job to run your schedule?
- Install an obscure program that your reporting uses once a month?
- Enable a PHP extension that you need for an API?
This is the scenario Scrutiny was built to address – use the availability monitor you already use (like Oh Dear or Pingdom) to also monitor other important aspects of your environment.
This means your availability monitor notifies you of any problems with your server environment setup instead of waiting for your clients or customers to tell you something is wrong.
To install through composer, add the following to your composer.json
file:
{
"require": {
"brightmachine/scrutiny": "~2.0"
}
}
Then run composer install
from the terminal.
The installation instructions can be simplified using the following:
composer require "brightmachine/scrutiny=~2.0"
You are all setup – next step it to add your probes!
- In
AppServiceProvider::boot()
, configure the probes to check for all the things your environment needs in order to run - Set up an
uptime check
in Oh Dear or Pingdom to alert you if any of the probes fail to pass
<?php
namespace App\Providers;
use Illuminate\Support\ServiceProvider;
class AppServiceProvider extends ServiceProvider
{
public function boot()
{
// …
$this->configureScrutinyProbes();
}
public function register()
{
}
protected function configureScrutinyProbes()
{
\Scrutiny\ProbeManager::configure()
->connectsToDatabase()
->executableIsInstalled('composer.phar')
->queueIsRunning(30, 'high')
->queueIsRunning(60, 'low')
;
}
}
All probes are added through \Scrutiny\ProbeManager
and calls can be chained:
\Scrutiny\ProbeManager::configure()->scheduleIsRunning()->queueIsRunning();
The following probes are available via \Scrutiny\ProbeManager::configure()
:
Ensure that you always have space available.
It works by finding the disk related to a given folder and checking its usage.
public availableDiskSpace( number $minPercentage [, string $diskFolder = null ] )
$minPercentage
is the minimum amount of disk space that should be available$diskFolder
the folder used to find the disk. Defaults to the disk storing your laravel app.
If your use-case isn't supported out-of-the-box you can write your own custom probe.
When a probe is checked, 3 outcomes are possible:
- Skipped – if a
\Scrutiny\ProbeSkippedException
exception is thrown - Failed – if any other exception is thrown
- Passed – if no exception is thrown
public callback( string $probeName , callable $callback )
$probeName
the name of the probe used to report the results of the check$callback
the callback that runs your custom check
Check that you're able to connect to one of your databases configured on config/database.php
.
public connectsToDatabase([ string $connectionName = null ])
$connectionName
is the name of your database connection fromconfig/database.php
This probe checks that a given URL will return a 2xx response.
NB: Redirects will not be followed – only the first response will be considered.
public connectsToHttp( string $url [, array $params = array(), string $verb = 'GET' ] )
$url
the URL to check, which can contain a username and password, e.g.https://user@pass:example.com
$params
an array of URL parameters to add to the request$verb
eitherGET
orPOST
This probe will search your path, and your current vendor/bin
looking for a particular executable.
public executableIsInstalled( string $executableName )
$executableName
the name of the executable to find
Check that a particular PHP extension is loaded.
public phpExtensionLoaded( string $extensionName )
$extensionName
the name of the PHP extension to check
This probe checks that your laravel queue is running.
public queueIsRunning( [ int $maxHandleTime = 300, $queue = null, $connection = null ] )
$maxHandleTime
the maximum time in seconds that you give a job to run on the given queue$queue
if you run multiple queues on the same connection, this is the name of the queue to check$connection
if you run multiple connections, this is the one to check as configured inconfig/queue.php
Make sure that the artisan schedule is being run.
public scheduleIsRunning()
By default, when scrutiny outputs details of your probe (e.g. if it fails, or in the history) it guesses a name based on the configuration setting.
If this default name would output sensitive information, such as API keys, then you'll want to set the name of the probe.
public named( string $identifier )
You override the name by calling ->named()
after you set the probe:
\Scrutiny\ProbeManager::configure()
->connectsToHttp('https://api.example.com/me?api_key=12345678900987654321')
->named('example.com API');
Certain probes will need to search for a certain executable on disk.
By default, scrutiny will search directories in your $PATH
environment variable
as well as your base_path()
and your vendor/bin
.
But this isn't always enough.
You can add directories to the path when you configure your probes:
\Scrutiny\ProbeManager::extraDirs([
'/usr/local/bin/',
'/var/www/bin',
]);
Your configured probes are rate-limited to 1 check every minute.
This isn't what you want when first setting up your probes, so
to bypass this locally set DEBUG=true
in your .env
file.
Run php artisan scrutiny:check-probes
to check if your probes are passing.
This command is not rate-limited, so it's a good way to test immediately after making a change, or even as part of a deployment process.
The command will return 0
on success and 1
on failure.
Configure a new site in Oh Dear with the following setting:
- In
Settings
(theGeneral
tab), point to the scrutiny URL for your domainyourdomain.com/~scrutiny/check-probes
where yourdomain.com is your production domain - Scrutiny will return an HTTP status of
590 Some Tests Failed
when something is awry – this is a custom code
Configure a new check in pingdom with the following setting:
- Add an
uptime check
in pingdom to hithttps://yourdomain.com/~scrutiny/check-probes
where yourdomain.com is your production domain - Scrutiny will return an HTTP status of
590 Some Tests Failed
when something is awry – this is a custom code
Any contribution is received with humility and gratitude.
Thank you if you're considering contributing an improvement to this project.
Process:
- Fork, change, create pull-request
- Tell us why/how your PR will benefit the project
- We may ask you for clarification, but we'll quickly let you know whether or not it's likely your change will be merged
😘 Xx