Critical Alerts Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bazoonchik/critical-alerts
   

   Publish the config file:

   php artisan vendor:publish --provider="Bazoonchik\CriticalAlerts\CriticalAlertsServiceProvider" --tag="config"
   

2. Configuration Edit config/critical-alerts.php to define your Telegram and Sentry credentials:

   'telegram' => [
       'bot_token' => env('TELEGRAM_BOT_TOKEN'),
       'chat_id' => env('TELEGRAM_CHAT_ID'),
   ],
   'sentry' => [
       'dsn' => env('SENTRY_DSN'),
       'level' => env('SENTRY_LOG_LEVEL', 'error'),
   ],
   

3. First Use Case: Logging to Telegram Inject the CriticalAlerts facade into your controller/service:

   use Bazoonchik\CriticalAlerts\Facades\CriticalAlerts;
   
   public function handleCriticalError()
   {
       CriticalAlerts::telegram('Application crashed!')->log();
   }
   

Implementation Patterns

Logging Workflows

1. Channel-Specific Logging Use predefined channels (telegram, sentry) for structured alerts:

   CriticalAlerts::telegram('Database connection failed')->log();
   CriticalAlerts::sentry(new \Exception('API timeout'))->log();
   

2. Dynamic Context Attachment Pass metadata (e.g., user ID, request data) for richer debugging:

   CriticalAlerts::telegram('Payment failed')
       ->withContext(['user_id' => 123, 'amount' => 99.99])
       ->log();
   

3. Integration with Monolog Extend Laravel’s default logging to auto-forward critical logs:

   // In app/Providers/AppServiceProvider.php
   public function boot()
   {
       $this->app['log']->extend('critical', function () {
           return new \Bazoonchik\CriticalAlerts\Monolog\CriticalHandler();
       });
   }
   

   Then use in code:

   \Log::critical('Critical failure', ['context' => 'key']);
   

Customization

• Add New Channels: Implement Bazoonchik\CriticalAlerts\Contracts\AlertChannel for custom integrations (e.g., Slack, Email).
• Log Level Filtering: Configure config/critical-alerts.php to restrict alerts by severity:

  'levels' => ['error', 'critical'], // Only log these levels
  

Gotchas and Tips

Pitfalls

1. Environment Variables

   • Ensure TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID, and SENTRY_DSN are set in .env. Missing values will silently fail.
   • Fix: Validate config in AppServiceProvider@boot():

     if (!config('critical-alerts.telegram.bot_token')) {
         throw new \RuntimeException('Telegram token not configured!');
     }
     

2. Sentry Rate Limits

   • Sentry’s free tier has rate limits. Excessive alerts may trigger throttling.
   • Tip: Use ->withLevel('critical') sparingly for high-severity issues only.

3. Telegram Message Length

   • Telegram messages are capped at 4096 characters. Long logs (e.g., stack traces) will truncate.
   • Workaround: Use ->withContext() for details and log the truncated message separately.

Debugging

• Log Channel Mismatch: If alerts aren’t firing, verify the channel is enabled in config/critical-alerts.php:

  'enabled' => [
      'telegram' => true,
      'sentry' => true,
  ],
  

• Test Locally: Use a Telegram test bot and mock Sentry’s DSN with http://localhost:3000 for debugging.

Extension Points

1. Custom Formatting Override the default message formatter by binding a new Bazoonchik\CriticalAlerts\Contracts\MessageFormatter:

   // In AppServiceProvider@register()
   $this->app->bind(\Bazoonchik\CriticalAlerts\Contracts\MessageFormatter::class, function () {
       return new \App\Services\CustomFormatter();
   });
   

2. Queue Delay for Non-Urgent Alerts Use Laravel Queues to defer non-critical alerts:

   CriticalAlerts::telegram('Scheduled job failed')->delay(now()->addMinutes(5))->log();