Laravel Log Alarm Laravel Package

Getting Started

Install the package via Composer and publish the config:

composer require saasscaleup/laravel-log-alarm
php artisan vendor:publish --provider="Saasscaleup\LogAlarm\LogAlarmServiceProvider"

Start by configuring environment variables in .env — minimal setup requires only:

• LA_SLACK_WEBHOOK_URL (optional)
• LA_NOTIFICATION_EMAIL (comma-separated list)

Then trigger your first alarm manually for testing using tinker:

php artisan tinker
>>> \Log::error('Log alarm'); // repeat 5 times

If configured, this will send an email (and Slack, if webhook is set) after 5 matching log entries within the configured time window (default: 5 errors in 1 minute).

💡 First use case: Catch unexpected recurring errors in development or staging — e.g., failed database migrations, misconfigured environment variables — by watching for repeated error-level logs.

Implementation Patterns

• Passive Monitoring in Production: Once installed, the package runs silently — no code changes required. It listens to Laravel’s logging events via an observer. Ideal for apps where you want "just-in-case" alerting without modifying existing log statements.

• Targeted Error Filtering with specific_string: Use LA_SPECIFIC_STRING=table lock or DB::update to trigger alerts only for critical issues (e.g., deadlocks, connection timeouts). Avoids noise from generic errors.

• Adjust Sensitivity with Time Windows: For high-traffic apps, increase LA_LOG_PER_TIME_FRAME and LA_LOG_TIME_FRAME (e.g., 50 errors in 10 minutes). For low-traffic services, lower thresholds to get notified faster.

• Integrate into Deployment Pipelines: Temporarily disable alerts with LA_ENABLED=false during deployments to avoid false positives from expected downtime or migration errors.

• Combine with Log Channels: Use Laravel’s channel-based logging to send specific contexts (e.g., log-alarm channel) through this package, while routing others elsewhere — filter by log_type (error,warning) in config.

Gotchas and Tips

• Cache-based throttling: Errors are tracked in cache (log-alarm-<hash>), so make sure your cache driver is reliable (use Redis for production). Cache key resets are automatic but can be delayed if cache miss occurs mid-window.

• LA_LOG_TYPE is comma-delimited but not whitespace-safe: Write LA_LOG_TYPE=error,warning — avoid spaces (e.g., error, warning won’t parse correctly). Validate via php artisan config:show log-alarm.

• Log::error() messages must match exactly (or include specific_string): The package compares full message strings by default. "Error" ≠ "Error occurred". For patterns, use specific_string or normalize messages.

• Delay isn’t just between identical messages — it’s global: After triggering an alarm, no alarms are sent for the configured LA_DELAY_BETWEEN_ALARMS minutes, even for different errors. This prevents alert storms.

• Line numbers and paths are only included in the email, not in Slack/Telegram/Discord. If you rely on file/line data, test via email first.

• Telegram/Discord/Slack support is additive — not exclusive: You can enable all three simultaneously. Just provide all relevant env vars. The package batches notifications to avoid duplicates within the same window.

• Testing tip: Use php artisan config:clear && php artisan cache:clear after changing env/config. Restart queue workers if using queue:listen — the listener attaches at service provider boot.

• Extensibility: While the package doesn’t expose event hooks, you can extend LogAlarmService and override sendNotification() by registering a custom binding in AppServiceProvider.