Stethoscope Laravel Package

Getting Started

Start by installing the package via Composer and publishing its configuration:

composer require mohsenabrishami/stethoscope
php artisan vendor:publish --tag=stethoscope-publish-config

The package targets Linux servers (Debian/Ubuntu family) and requires PHP 8.0+ and Laravel 8+. After configuration, run php artisan stethoscope:listen to get an immediate server health snapshot — this outputs CPU, memory, storage, network, and web server status in a human-friendly CLI table. For basic proactive monitoring, use php artisan stethoscope:monitor, which checks thresholds and logs issues.

Implementation Patterns

• Cron-based Monitoring: Schedule the stethoscope:monitor command every 5 minutes in your kernel to keep logs updated:

  $schedule->command('stethoscope:monitor')->everyFiveMinutes();
  

• Log Persistence: Switch from file-based to database logging by setting 'drivers' => ['log_record' => 'database'] in config/stethoscope.php, then run php artisan migrate. Database logs are essential for dashboard use.
• Dashboard Activation: Enable the built-in Laravel Filament-powered dashboard (status: true, path: 'monitoring-panel') and publish views with --tag=stethoscope-publish-view. Protect it with a secret key (e.g., ?key=xyz) and ensure MONITORING_PANEL_KEY is set in .env.
• Custom Notifications: Extend LogReportNotification and Notifiable to plug in Telegram, Slack, or custom endpoints. Register your custom notification class in config/stethoscope.php under notifications.

Gotchas and Tips

• Linux-only Limitations: Server metrics (CPU/memory/storage) are derived using Linux CLI tools (top, df, free). The package will fail or show inaccurate readings on Windows/macOS unless run via WSL or similar.
• Threshold Sensitivity: Default thresholds (cpu: 90, memory: 80, storage: 10 GB free) may be too aggressive or too lenient depending on your workload. Tune them in .env to prevent notification storms or missed alerts.
• Network Monitoring Flakiness: By default, it checks https://1.1.1.1 and https://www.google.com. Ensure both are reachable; if your environment blocks external domains, update network_monitor_url to internal endpoints.
• Log Cleanup: Use php artisan stethoscope:clean regularly (e.g., daily cron job) to prevent log bloat — especially important when using database storage. Check cleanup_resource_logs in config.
• Extension Points: Extend StethoscopeNotifiable and LogReportNotification to inject custom logic. Hook into the MonitorFinished event (if available in future versions) or override the monitor() command logic via command subclassing.