README

Real-time error monitoring, intelligent alerts, and traffic surveillance for Laravel applications.

PulseAlert is a lightweight, zero-configuration package designed to keep you informed about your application's health. It goes beyond simple logging by classifying errors, sending instant Telegram notifications for critical issues, and providing daily summaries.

✨ Features

Intelligent Priority Engine: Automatically classifies exceptions (CRITICAL, HIGH, MEDIUM, LOW).
Telegram Instant Alerts: Receive 🔴 Critical and 🟠 High priority alerts directly on Telegram.
Smart Rate Limiting: Prevents alert spam by silencing duplicate errors for 10 minutes.
Traffic Surveillance: Middleware to detect and notify about suspicious request volume from single IPs.
Daily Error Digest: Beautifully formatted email summaries sorted by importance.
Data Sanitization: Automatically scrubs sensitive data (passwords, tokens) from stack traces.

🚀 Installation

Step 1 — Install via Composer

composer require mohamedsamy902/laravel-pulse-alert

Step 2 — Publish Config & Migrations

php artisan vendor:publish --tag=pulse-alert-config
php artisan vendor:publish --tag=pulse-alert-migrations

Step 3 — Run Migrations

php artisan migrate

📋 Configuration

Environment Variables

Add these keys to your .env file:

Variable	Description	Default
`PULSE_ALERT_TELEGRAM_TOKEN`	Your Telegram Bot Token (@BotFather)	`null`
`PULSE_ALERT_TELEGRAM_CHAT_ID`	Your Telegram Chat/Group ID	`null`
`PULSE_ALERT_TELEGRAM_ENABLED`	Toggle Telegram alerts	`true`
`PULSE_ALERT_TELEGRAM_QUEUE`	Set `false` for instant delivery without Worker	`false`
`PULSE_ALERT_LOCALE`	Message language (`en` or `ar`)	`en`
`PULSE_ALERT_MAIL_TO`	Recipient for daily reports	`null`
`PULSE_ALERT_MAIL_ENABLED`	Toggle email reports	`true`
`PULSE_ALERT_REPORT_TIME`	Departure time for daily report	`08:00`
`PULSE_ALERT_RATE_MAX`	Max requests allowed per window	`20`
`PULSE_ALERT_RATE_WINDOW`	Time window in minutes	`1`

Registering the Logger (Laravel 11/12)

In your bootstrap/app.php, register the PulseAlert logger within the withExceptions block:

use MohamedSamy902\PulseAlert\Services\ErrorLogger;

// ...
->withExceptions(function (Exceptions $exceptions) {
    app(ErrorLogger::class)->register($exceptions);
})

Scheduling the Daily Report

In your routes/console.php, schedule the report to run daily:

use Illuminate\Support\Facades\Schedule;

Schedule::command('pulse-alert:daily-report')->dailyAt('08:00');

📖 Usage

Automatic Traffic Surveillance

The package automatically registers its rate-limiting middleware globally. All requests (Web, API, Dashboard) are monitored by default using the settings in your config file.

Manual Logging

You can manually log errors with a specific priority if needed:

use MohamedSamy902\PulseAlert\Services\ErrorLogger;

try {
    // ... code
} catch (\Exception $e) {
    app(ErrorLogger::class)->log($e, 'CRITICAL');
}

🎯 Priority Classification Logic

CRITICAL: Database errors, 500 status codes, or severe engine errors. (Instant Alert 🔴)
HIGH: Keywords like "payment", "unauthorized", "auth", or "token" detected in message. (Instant Alert 🟠)
MEDIUM: General exceptions that don't match critical/high criteria. (Daily Report only)
LOW: Minor issues or manually logged low-priority events. (Daily Report only)

🧪 Testing

composer test

📄 License

The MIT License (MIT). Please see License File for more information.

mohamedsamy902 / laravel-pulse-alert

Maintainers

Package info

Statistics

Security