Disable notifications and change throttle for individual checks

docs/configuring-notifications/general.md

@@ -11,8 +11,40 @@ Out of the box, the notification can be sent:
 - via [Slack](/docs/laravel-health/v1/configuring-notifications/via-slack)
 - via [Oh Dear](/docs/laravel-health/v1/configuring-notifications/via-oh-dear) (enables snoozing notifications, and delivery via Telegram, Discord, MS Teams, webhooks, ...)
 
+## Disabling notifications
+
+You may want to disable notifications for certain types of checks, but still have them show up on the page or cli.
+To do this you can use the `disableNotifications` method. If you would like to disable notifications for certain check
+statuses, the `disableNotificationsOnWarning` and `disableNotificationsOnFailure` methods are available.
+
+```php
+use Spatie\Health\Facades\Health;
+use Spatie\Health\Checks\Checks\CpuLoadCheck;
+
+Health::checks([
+    CpuLoadCheck::new()
+        ->disableNotifcations()
+]);
+```
+
 ## Throttling notifications
 
 These notifications are throttled, so you don't get overwhelmed with notifications when something goes wrong. By default, you'll only get one notification per hour.
 
 In the `throttle_notifications_for_minutes` key of the `health` config file, you can customize the length of the throttling period.
+
+You can also configure the throttle time for notifications on an individual basis as well. If you want to customize the throttle
+time based on the result of the check, the `throttleWarningNotificationsFor` and `throttleFailureNotificationsFor` methods are also available.
+
+```php
+use Spatie\Health\Facades\Health;
+use Spatie\Health\Checks\Checks\CpuLoadCheck;
+
+Health::checks([
+    CpuLoadCheck::new()
+        ->throttleNotificationsFor(24 * 60) // 1 day
+]);
+```
+
+Note that when a notification for check with a custom throttle time is sent, the notification will include *all* the checks that failed,
+not just the one with the custom throttle time. This avoids the false-positive feeling that an incomplete notification would have.

src/Checks/Check.php

@@ -30,6 +30,14 @@ abstract class Check
      */
     protected array $shouldRun = [];
 
+    protected bool $failureNotificationEnabled = true;
+
+    protected bool $warningNotificationEnabled = true;
+
+    protected ?int $failureThrottleMinutes = null;
+
+    protected ?int $warningThrottleMinutes = null;
+
     public function __construct() {}
 
     public static function new(): static
@@ -122,6 +130,64 @@ public function markAsCrashed(): Result
 
     public function onTerminate(mixed $request, mixed $response): void {}
 
+    public function disableNotifications()
+    {
+        $this->disableNotificationsOnWarning();
+        $this->disableNotificationsOnFailure();
+
+        return $this;
+    }
+
+    public function disableNotificationsOnWarning()
+    {
+        $this->warningNotificationEnabled = false;
+
+        return $this;
+    }
+
+    public function disableNotificationsOnFailure()
+    {
+        $this->failureNotificationEnabled = false;
+
+        return $this;
+    }
+
+    public function throttleNotificationsFor(int $minutes)
+    {
+        $this->throttleWarningNotificationsFor($minutes);
+        $this->throttleFailureNotificationsFor($minutes);
+
+        return $this;
+    }
+
+    public function throttleWarningNotificationsFor(int $minutes)
+    {
+        $this->warningThrottleMinutes = $minutes;
+
+        return $this;
+    }
+
+    public function throttleFailureNotificationsFor(int $minutes)
+    {
+        $this->failureThrottleMinutes = $minutes;
+
+        return $this;
+    }
+
+    public function getThrottleConfiguration(): array
+    {
+        return [
+            Status::warning()->value => [
+                'enabled' => $this->warningNotificationEnabled,
+                'minutes' => $this->warningThrottleMinutes,
+            ],
+            Status::failed()->value => [
+                'enabled' => $this->failureNotificationEnabled,
+                'minutes' => $this->failureThrottleMinutes,
+            ],
+        ];
+    }
+
     public function __serialize(): array
     {
         $vars = get_object_vars($this);

src/Notifications/CheckFailedNotification.php

@@ -12,6 +12,9 @@
 
 class CheckFailedNotification extends Notification
 {
+    /** @param  array<int, array<int, Result>>  $results */
+    protected array $resultsForNotificationByChannel = [];
+
     /** @param  array<int, Result>  $results */
     public function __construct(public array $results) {}
 
@@ -30,14 +33,34 @@ public function shouldSend(Notifiable $notifiable, string $channel): bool
             return false;
         }
 
-        /** @var int $throttleMinutes */
-        $throttleMinutes = config('health.notifications.throttle_notifications_for_minutes');
+        $filteredResults = $this->filterResultsForNotificationChannel($channel);
+        $this->resultsForNotificationByChannel[$channel] = $filteredResults;
 
-        if ($throttleMinutes === 0) {
+        if (count($filteredResults) === 0) {
+            return false;
+        }
+
+        // If we have any checks that have custom throttle times set that have already been locked
+        $hasCustomThrottleCheck = array_reduce($filteredResults, function (bool $a, Result $result) {
+            return $a || ($result->check->getThrottleConfiguration()[$result->status->value]['minutes'] ?? null) != null;
+        }, false);
+
+        if ($hasCustomThrottleCheck) {
             return true;
         }
 
-        $cacheKey = config('health.notifications.throttle_notifications_key', 'health:latestNotificationSentAt:').$channel;
+        /** @var int $defaultThrottleMinutes */
+        $defaultThrottleMinutes = config('health.notifications.throttle_notifications_for_minutes');
+        $defaultCacheKey = config('health.notifications.throttle_notifications_key', 'health:latestNotificationSentAt:').$channel;
+
+        return $this->canAcquireLock($defaultCacheKey, $defaultThrottleMinutes);
+    }
+
+    public function canAcquireLock(string $cacheKey, int $throttleMinutes): bool
+    {
+        if ($throttleMinutes === 0) {
+            return true;
+        }
 
         /** @var \Illuminate\Cache\CacheManager $cache */
         $cache = app('cache');
@@ -65,7 +88,7 @@ public function toMail(): MailMessage
         return (new MailMessage)
             ->from(config('health.notifications.mail.from.address', config('mail.from.address')), config('health.notifications.mail.from.name', config('mail.from.name')))
             ->subject(trans('health::notifications.check_failed_mail_subject', $this->transParameters()))
-            ->markdown('health::mail.checkFailedNotification', ['results' => $this->results]);
+            ->markdown('health::mail.checkFailedNotification', ['results' => $this->getCheckResults('mail')]);
     }
 
     public function toSlack(): SlackMessage
@@ -76,7 +99,7 @@ public function toSlack(): SlackMessage
             ->to(config('health.notifications.slack.channel'))
             ->content(trans('health::notifications.check_failed_slack_message', $this->transParameters()));
 
-        foreach ($this->results as $result) {
+        foreach ($this->getCheckResults('slack') as $result) {
             $slackMessage->attachment(function (SlackAttachment $attachment) use ($result) {
                 $attachment
                     ->color(Status::from($result->status)->getSlackColor())
@@ -88,6 +111,40 @@ public function toSlack(): SlackMessage
         return $slackMessage;
     }
 
+    public function getCheckResults(string $channel)
+    {
+        return $this->resultsForNotificationByChannel[$channel];
+    }
+
+    protected function filterResultsForNotificationChannel(string $channel): array
+    {
+        return array_filter($this->results, function ($result) use ($channel) {
+            if (! array_key_exists($result->status->value, $result->check->getThrottleConfiguration())) {
+                return true;
+            }
+
+            $throttleConfig = $result->check->getThrottleConfiguration()[$result->status->value];
+
+            if ($throttleConfig['enabled'] === false) {
+                return false;
+            }
+
+            $checkCacheKey = implode(':', [
+                trim(config('health.notifications.throttle_notifications_key', 'health:latestNotificationSentAt'), ':'),
+                $channel,
+                get_class($result->check),
+            ]);
+
+            if ($throttleConfig['minutes'] != null) {
+                if (! $this->canAcquireLock($checkCacheKey, $throttleConfig['minutes'])) {
+                    return false;
+                }
+            }
+
+            return true;
+        });
+    }
+
     /**
      * @return array<string, string>
      */

tests/Notifications/CheckFailedNotificationTest.php

@@ -1,9 +1,13 @@
 <?php
 
 use Illuminate\Support\Facades\Notification;
+use Spatie\Health\Checks\Check;
+use Spatie\Health\Checks\Result;
 use Spatie\Health\Commands\RunHealthChecksCommand;
+use Spatie\Health\Enums\Status;
 use Spatie\Health\Facades\Health;
 use Spatie\Health\Notifications\CheckFailedNotification;
+use Spatie\Health\Notifications\Notifiable;
 use Spatie\Health\Tests\TestClasses\FakeUsedDiskSpaceCheck;
 use Spatie\TestTime\TestTime;
 
@@ -72,13 +76,123 @@
 });
 
 test('the notification can be rendered to mail', function () {
-    $mailable = (new CheckFailedNotification([]))->toMail();
+    $notification = (new CheckFailedNotification([]));
+    $notification->shouldSend(new Notifiable(), 'mail');
+    $mailable = $notification->toMail();
 
     $html = (string) $mailable->render();
 
     expect($html)->toBeString();
 });
 
+it('can disable warning notifications', function () {
+    TestTime::freeze();
+    Health::checks([
+        $check = FakeUsedDiskSpaceCheck::new()
+            ->warnWhenUsedSpaceIsAbovePercentage(10)
+            ->failWhenUsedSpaceIsAbovePercentage(50)
+            ->fakeDiskUsagePercentage(11)
+            ->disableNotificationsOnWarning(),
+    ]);
+
+    artisan(RunHealthChecksCommand::class)->assertSuccessful();
+    Notification::assertSentTimes(CheckFailedNotification::class, 0);
+
+    $check->fakeDiskUsagePercentage(51);
+
+    artisan(RunHealthChecksCommand::class)->assertSuccessful();
+    Notification::assertSentTimes(CheckFailedNotification::class, 1);
+});
+
+it('can disable failure notifications', function () {
+    TestTime::freeze();
+    Health::checks([
+        $check = FakeUsedDiskSpaceCheck::new()
+            ->warnWhenUsedSpaceIsAbovePercentage(10)
+            ->failWhenUsedSpaceIsAbovePercentage(50)
+            ->fakeDiskUsagePercentage(11)
+            ->disableNotificationsOnFailure(),
+    ]);
+
+    artisan(RunHealthChecksCommand::class)->assertSuccessful();
+    Notification::assertSentTimes(CheckFailedNotification::class, 1);
+
+    $check->fakeDiskUsagePercentage(51);
+
+    artisan(RunHealthChecksCommand::class)->assertSuccessful();
+    Notification::assertSentTimes(CheckFailedNotification::class, 1);
+});
+
+it('can change warning throttle time', function () {
+    TestTime::freeze();
+    Health::checks([
+        $check = FakeUsedDiskSpaceCheck::new()
+            ->warnWhenUsedSpaceIsAbovePercentage(10)
+            ->failWhenUsedSpaceIsAbovePercentage(50)
+            ->fakeDiskUsagePercentage(11)
+            ->throttleWarningNotificationsFor(15),
+    ]);
+
+    artisan(RunHealthChecksCommand::class)->assertSuccessful();
+    Notification::assertSentTimes(CheckFailedNotification::class, 1);
+
+    TestTime::addMinutes(15)->subSecond();
+    artisan(RunHealthChecksCommand::class)->assertSuccessful();
+    Notification::assertSentTimes(CheckFailedNotification::class, 1);
+
+    TestTime::addSecond();
+    artisan(RunHealthChecksCommand::class)->assertSuccessful();
+    Notification::assertSentTimes(CheckFailedNotification::class, 2);
+
+    TestTime::addSecond();
+    $check->fakeDiskUsagePercentage(55);
+    artisan(RunHealthChecksCommand::class)->assertSuccessful();
+    Notification::assertSentTimes(CheckFailedNotification::class, 3);
+});
+
+it('can change failure throttle time', function () {
+    TestTime::freeze();
+    Health::checks([
+        $check = FakeUsedDiskSpaceCheck::new()
+            ->warnWhenUsedSpaceIsAbovePercentage(10)
+            ->failWhenUsedSpaceIsAbovePercentage(50)
+            ->fakeDiskUsagePercentage(55)
+            ->throttleFailureNotificationsFor(15),
+    ]);
+
+    artisan(RunHealthChecksCommand::class)->assertSuccessful();
+    Notification::assertSentTimes(CheckFailedNotification::class, 1);
+
+    TestTime::addMinutes(15)->subSecond();
+    artisan(RunHealthChecksCommand::class)->assertSuccessful();
+    Notification::assertSentTimes(CheckFailedNotification::class, 1);
+
+    TestTime::addSecond();
+    artisan(RunHealthChecksCommand::class)->assertSuccessful();
+    Notification::assertSentTimes(CheckFailedNotification::class, 2);
+
+    TestTime::addSecond();
+    $check->fakeDiskUsagePercentage(11);
+    artisan(RunHealthChecksCommand::class)->assertSuccessful();
+    Notification::assertSentTimes(CheckFailedNotification::class, 3);
+});
+
+it('can dispatch notifications for crashed check', function () {
+    TestTime::freeze();
+    Health::checks([
+        new class extends Check
+        {
+            public function run(): Result
+            {
+                return new Result(Status::crashed(), 'Check Crashed', 'Check Crashed');
+            }
+        },
+    ]);
+
+    artisan(RunHealthChecksCommand::class)->assertSuccessful();
+    Notification::assertSentTimes(CheckFailedNotification::class, 1);
+});
+
 function registerPassingCheck()
 {
     Health::checks([

tests/__snapshots__/QueueCheckTest__it_can_serialize_closures__1.txt

@@ -1 +1 @@
-O:38:"Spatie\Health\Checks\Checks\QueueCheck":8:{s:10:"expression";s:9:"* * * * *";s:4:"name";N;s:5:"label";N;s:9:"shouldRun";a:1:{i:0;O:47:"Laravel\SerializableClosure\SerializableClosure":1:{s:12:"serializable";O:46:"Laravel\SerializableClosure\Serializers\Native":5:{s:3:"use";a:0:{}s:8:"function";s:14:"fn () => false";s:5:"scope";s:29:"P\Tests\Checks\QueueCheckTest";s:4:"this";N;s:4:"self";s:32:"0000000000000000000000000000000000000000";}}}s:8:"cacheKey";s:37:"health:checks:queue:latestHeartbeatAt";s:14:"cacheStoreName";N;s:37:"failWhenTestJobTakesLongerThanMinutes";i:5;s:8:"onQueues";a:1:{i:0;s:4:"sync";}}
+O:38:"Spatie\Health\Checks\Checks\QueueCheck":12:{s:10:"expression";s:9:"* * * * *";s:4:"name";N;s:5:"label";N;s:9:"shouldRun";a:1:{i:0;O:47:"Laravel\SerializableClosure\SerializableClosure":1:{s:12:"serializable";O:46:"Laravel\SerializableClosure\Serializers\Native":5:{s:3:"use";a:0:{}s:8:"function";s:14:"fn () => false";s:5:"scope";s:29:"P\Tests\Checks\QueueCheckTest";s:4:"this";N;s:4:"self";s:32:"0000000000000000000000000000000000000000";}}}s:26:"failureNotificationEnabled";b:1;s:26:"warningNotificationEnabled";b:1;s:22:"failureThrottleMinutes";N;s:22:"warningThrottleMinutes";N;s:8:"cacheKey";s:37:"health:checks:queue:latestHeartbeatAt";s:14:"cacheStoreName";N;s:37:"failWhenTestJobTakesLongerThanMinutes";i:5;s:8:"onQueues";a:1:{i:0;s:4:"sync";}}

tests/__snapshots__/QueueCheckTest__it_can_serialize_non_closures__1.txt

@@ -1 +1 @@
-O:38:"Spatie\Health\Checks\Checks\QueueCheck":8:{s:10:"expression";s:9:"* * * * *";s:4:"name";N;s:5:"label";N;s:9:"shouldRun";a:1:{i:0;b:1;}s:8:"cacheKey";s:37:"health:checks:queue:latestHeartbeatAt";s:14:"cacheStoreName";N;s:37:"failWhenTestJobTakesLongerThanMinutes";i:5;s:8:"onQueues";a:1:{i:0;s:4:"sync";}}
+O:38:"Spatie\Health\Checks\Checks\QueueCheck":12:{s:10:"expression";s:9:"* * * * *";s:4:"name";N;s:5:"label";N;s:9:"shouldRun";a:1:{i:0;b:1;}s:26:"failureNotificationEnabled";b:1;s:26:"warningNotificationEnabled";b:1;s:22:"failureThrottleMinutes";N;s:22:"warningThrottleMinutes";N;s:8:"cacheKey";s:37:"health:checks:queue:latestHeartbeatAt";s:14:"cacheStoreName";N;s:37:"failWhenTestJobTakesLongerThanMinutes";i:5;s:8:"onQueues";a:1:{i:0;s:4:"sync";}}

tests/__snapshots__/QueueCheckTest__it_can_unserialize__1.yml

@@ -6,3 +6,6 @@ name: Queue
 runConditions:
     - true
     - {  }
+throttleConfiguration:
+    warning: { enabled: true, minutes: null }
+    failed: { enabled: true, minutes: null }