Scrutiny
Scrutiny helps your Laravel 8 project ensure that its current server environment is configured and running as planned., (*1)
, (*2)
Problem
Have you ever been in the situation where you've moved servers and forgotten to:, (*3)
- 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., (*4)
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., (*5)
Installation
To install through composer, add the following to your composer.json file:, (*6)
{
"require": {
"brightmachine/scrutiny": "~2.0"
}
}
Then run composer install from the terminal., (*7)
Quick Installation
The installation instructions can be simplified using the following:, (*8)
composer require "brightmachine/scrutiny=~2.0"
You are all setup – next step it to add your probes!, (*9)
How it works
- 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')
;
}
}
What probes are available
All probes are added through \Scrutiny\ProbeManager and calls can be chained:, (*10)
\Scrutiny\ProbeManager::configure()->scheduleIsRunning()->queueIsRunning();
The following probes are available via \Scrutiny\ProbeManager::configure():, (*11)
availableDiskSpace()
Ensure that you always have space available., (*12)
It works by finding the disk related to a given folder and checking its usage., (*13)
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.
callback()
If your use-case isn't supported out-of-the-box you can write your own custom probe., (*14)
When a probe is checked, 3 outcomes are possible:, (*15)
-
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
connectsToDatabase()
Check that you're able to connect to one of your databases configured on config/database.php., (*16)
public connectsToDatabase([ string $connectionName = null ])
-
$connectionName is the name of your database connection from config/database.php
connectsToHttp()
This probe checks that a given URL will return a 2xx response., (*17)
NB: Redirects will not be followed – only the first response will be considered., (*18)
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 either GET or POST
executableIsInstalled()
This probe will search your path, and your current vendor/bin looking for a particular executable., (*19)
public executableIsInstalled( string $executableName )
-
$executableName the name of the executable to find
phpExtensionLoaded()
Check that a particular PHP extension is loaded., (*20)
public phpExtensionLoaded( string $extensionName )
-
$extensionName the name of the PHP extension to check
queueIsRunning()
This probe checks that your laravel queue is running., (*21)
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 in config/queue.php
scheduleIsRunning()
Make sure that the artisan schedule is being run., (*22)
public scheduleIsRunning()
Customising the name of your probe
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., (*23)
If this default name would output sensitive information, such as API keys, then
you'll want to set the name of the probe., (*24)
public named( string $identifier )
You override the name by calling ->named() after you set the probe:, (*25)
\Scrutiny\ProbeManager::configure()
->connectsToHttp('https://api.example.com/me?api_key=12345678900987654321')
->named('example.com API');
Customising the executable search path
Certain probes will need to search for a certain executable on disk., (*26)
By default, scrutiny will search directories in your $PATH environment variable
as well as your base_path() and your vendor/bin., (*27)
But this isn't always enough., (*28)
You can add directories to the path when you configure your probes:, (*29)
\Scrutiny\ProbeManager::extraDirs([
'/usr/local/bin/',
'/var/www/bin',
]);
Debugging locally
Your configured probes are rate-limited to 1 check every minute., (*30)
This isn't what you want when first setting up your probes, so
to bypass this locally set DEBUG=true in your .env file., (*31)
Artisan command
Run php artisan scrutiny:check-probes to check if your probes are passing., (*32)
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., (*33)
The command will return 0 on success and 1 on failure., (*34)
Configure a new site in Oh Dear with the following setting:, (*35)
- In
Settings (the General tab), point to the scrutiny URL for your domain 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
Configure a new check in pingdom with the following setting:, (*36)
- Add an
uptime check in pingdom to hit https://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
Contributing
Any contribution is received with humility and gratitude., (*37)
Thank you if you're considering contributing an improvement to this project., (*38)
Process:, (*39)
- 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, (*40)
Wallogit.com
