Corewatch Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require hamzi/corewatch
   php artisan vendor:publish --provider="Hamzi\CoreWatch\CoreWatchServiceProvider" --tag="corewatch-config"
   

   Publish the default config and migrations:

   php artisan migrate
   

2. First Use Case:

   • Register the CoreWatchServiceProvider in config/app.php under providers.
   • Access the dashboard via /corewatch (or your configured route).
   • Verify server metrics (CPU, memory, disk) and log streaming appear in the UI.

3. Quick Start:

   • Run php artisan corewatch:install to auto-configure routes, middleware, and Filament integration (if used).
   • Start monitoring immediately—no external services required.

Where to Look First

• Dashboard: /corewatch (or /admin/corewatch if using Filament).
• Configuration: config/corewatch.php (adjust routes, middleware, and alert thresholds).
• Logs: storage/logs/corewatch.log (for package-level debugging).
• API Docs: php artisan corewatch:docs (generates API reference for programmatic access).

Implementation Patterns

Core Workflows

1. Monitoring Integration

• Server Metrics: Automatically collects CPU, memory, disk, and network stats via Laravel’s Process facade.

  use Hamzi\CoreWatch\Facades\CoreWatch;
  CoreWatch::metrics()->fetch(); // Manually trigger a refresh
  

• Custom Metrics: Extend via events:

  CoreWatch::extend('custom_metric', function () {
      return ['value' => app('cache')->stats()['memory_usage']['used_memory']];
  });
  

2. Log Streaming

• Real-Time Logs: Stream Laravel logs via WebSockets (Laravel Echo/Pusher required).

  // Frontend (Vue/JS)
  Echo.channel('corewatch.logs')
      .listen('LogEvent', (e) => console.log(e.message));
  

• Log Filters: Configure in config/corewatch.php:

  'log' => [
      'channels' => ['single', 'daily'], // Monitor specific log channels
      'levels' => ['error', 'critical'], // Focus on high-severity logs
  ],
  

3. Alerting System

• Threshold Alerts: Define rules in config/corewatch.php:

  'alerts' => [
      'cpu' => ['threshold' => 90, 'notify' => ['email', 'slack']],
      'memory' => ['threshold' => 80, 'cooldown' => 300], // 5-minute cooldown
  ],
  

• Custom Alerts: Dispatch via events:

  use Hamzi\CoreWatch\Events\AlertTriggered;
  event(new AlertTriggered('custom_alert', 'Database connection failed'));
  

4. Safe Ops Panel

• Remote Commands: Execute shell commands securely via the dashboard.

  CoreWatch::ops()->execute('php artisan queue:work --once');
  

• Middleware Integration: Restrict access:

  Route::middleware(['corewatch.auth', 'corewatch.roles:admin'])->group(function () {
      // Safe ops routes
  });
  

5. Filament Integration (Optional)

• Dashboard Widgets: Add CoreWatch panels to Filament:

  use Hamzi\CoreWatch\Filament\Widgets\CoreWatchMetrics;
  public function getWidgets(): array {
      return [CoreWatchMetrics::class];
  }
  

• Resource Integration: Attach metrics to Filament resources:

  CoreWatch::resource('posts')->track('view_count');
  

Integration Tips

1. Laravel Echo/Pusher:

   • Required for real-time log streaming. Configure in config/broadcasting.php:

     'pusher' => [
         'key' => env('PUSHER_APP_KEY'),
         'options' => ['cluster' => env('PUSHER_APP_CLUSTER')],
     ],
     

2. Queue Workers:

   • CoreWatch uses queues for background tasks (metrics collection, alerts). Run:

     php artisan queue:work --daemon
     

3. Caching:

   • Metrics are cached for performance. Clear with:

     php artisan cache:clear
     

4. Multi-Server Setups:

   • Use Laravel Horizon or a shared database to aggregate metrics across servers.

Gotchas and Tips

Pitfalls

1. WebSocket Dependencies:

   • Log streaming requires Laravel Echo/Pusher. Without it, the WebSocket endpoint (/corewatch/logs) will fail.
   • Fix: Mock WebSocket events in testing:

     CoreWatch::shouldReceive('broadcastLog')->andReturnTrue();
     

2. Permission Issues:

   • Safe ops commands execute as the web server user (e.g., www-data). Ensure:
     • Commands have proper permissions (e.g., chmod +x for scripts).
     • Sensitive operations are gated by middleware (e.g., corewatch.roles).

3. Metric Polling Overhead:

   • Frequent metric collection (*_interval in config) can spike CPU usage.
   • Tip: Start with metrics_interval = 60 (seconds) and adjust based on server load.

4. Log Channel Mismatch:

   • If logs don’t appear, verify config/corewatch.php includes the correct log channels (e.g., single, daily).
   • Debug: Check storage/logs/corewatch.log for channel errors.

5. Filament Conflicts:

   • If using Filament, ensure the corewatch route doesn’t conflict with Filament’s admin panel.
   • Fix: Override routes in config/corewatch.php:

     'routes' => [
         'prefix' => 'admin/corewatch',
     ],
     

Debugging

1. Enable Debug Mode:

   'debug' => env('COREWATCH_DEBUG', false),
   

   • Logs detailed errors to storage/logs/corewatch.log.

2. Clear Cached Metrics:

   php artisan corewatch:clear-cache
   

3. Test Alerts Locally:

   • Trigger alerts manually:

     php artisan corewatch:test-alert cpu 95
     

4. Check Queue Jobs:

   • Monitor failed jobs:

     php artisan queue:failed-table
     php artisan queue:work --once --tries=3
     

Extension Points

1. Custom Metric Providers:

   • Implement Hamzi\CoreWatch\Contracts\MetricProvider:

     class DatabaseMetricProvider implements MetricProvider {
         public function getMetrics(): array {
             return ['queries' => DB::getTotalQueries()];
         }
     }
     

   • Register in config/corewatch.php:

     'providers' => [
         \App\Providers\DatabaseMetricProvider::class,
     ],
     

2. Alert Notifications:

   • Extend notification channels:

     CoreWatch::extendAlertChannel('discord', function ($alert) {
         // Send to Discord webhook
     });
     

3. UI Customization:

   • Override Blade views in resources/views/vendor/corewatch/.
   • Example: Modify metrics.blade.php to add custom charts.

4. API Extensions:

   • Access raw data via the API:

     $metrics = CoreWatch::metrics()->raw();
     $logs = CoreWatch::logs()->recent(100);
     

   • Build custom endpoints using these methods.

Config Quirks

1. Environment Variables:

   • Prefix CoreWatch configs with COREWATCH_ (e.g., COREWATCH_ALERT_CPU_THRESHOLD=90).
   • Overrides in .env take precedence over config/corewatch.php.

2. Middleware Order:

   • Place corewatch.auth before web middleware to protect routes:

     Route::middleware(['corewatch.auth', 'web'])->group(...);
     

3. Log Retention:

   • Logs are stored in the database. Adjust retention in migrations:

     Schema::table('corewatch_logs', function (Blueprint $table) {
         $table->integer('retention_days')->default(30);
     });