Corewatch Laravel Package

Getting Started

Minimal Setup

1. Installation:

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

2. Run the doctor first (v2.2.0):

   php artisan corewatch:doctor
   

   This is now the fastest way to confirm the package is wired correctly. It checks System, Database, Cache, Queue, Scheduler, Alerts, and Security, and prints a pass/fail summary per area. Anything red here is the actual root cause of a broken dashboard or silent alerts — check it before touching config.

3. First Use Case:

   • Access the dashboard at /corewatch (or /admin/corewatch with Filament).
   • Confirm metrics (CPU, memory, disk) and log streaming render.
   • Verify your alert channel with the new interactive command:

     php artisan corewatch:test-alert
     

     It walks you through Slack/Telegram delivery and gives feedback on the failure if the message doesn't arrive.

4. Quick Start:

   php artisan corewatch:install
   php artisan corewatch:doctor
   

Where to Look First

• Doctor output: php artisan corewatch:doctor — replaces guessing for Queue/Scheduler/Alerts issues.
• Dashboard: /corewatch (or /admin/corewatch for Filament).
• Configuration: config/corewatch.php (routes, middleware, thresholds, notifications_queue).
• Logs: storage/logs/corewatch.log for package-level errors. Since v2.2.0 catches \Throwable, failures are logged rather than thrown — this file is where they surface.
• Programmatic diagnostics:

  use Hamzi\CoreWatch\Facades\CoreWatch;
  $results = CoreWatch::doctor()->run();
  

Implementation Patterns

Core Workflows

1. Diagnostics (new in 2.2.0)

• Run ad-hoc checks in a health endpoint or deploy script:

  $report = CoreWatch::doctor()->run();
  if (! $report->passes()) {
      Log::critical('CoreWatch diagnostics failed', $report->toArray());
  }
  

• Wire into your post-deploy/CI step:

  php artisan corewatch:doctor || exit 1
  

• Prefer this over checking individual collectors — it covers Queue, Scheduler, and Security checks you won't think to write yourself.

2. Server & Custom Metrics

• Metrics are collected via Laravel's Process facade.

  CoreWatch::metrics()->fetch(); // Manual refresh
  

• Custom metrics via events:

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

3. Log Streaming

• Real-time streaming requires Laravel Echo/Pusher.

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

• Filter channels/levels in config/corewatch.php:

  'log' => [
      'channels' => ['single', 'daily'],
      'levels' => ['error', 'critical'],
  ],
  

4. Alerting (now queued)

• Thresholds in config:

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

• Alerts dispatch through SendQueuedAlertJob (ShouldQueue, with backoff retries). Control the queue in .env:

  COREWATCH_NOTIFICATIONS_QUEUE=notifications
  

• Run a worker for that queue — the default queue:work won't pick up a dedicated queue name:

  php artisan queue:work --queue=notifications,default
  

• Custom alerts:

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

5. Safe Ops Panel

• Securely execute commands from the dashboard:

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

• Gate with middleware:

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

6. Filament Integration (optional)

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

Integration Tips

1. Queue workers are now on the alerting critical path. With async dispatch, a dead worker means alerts never send — and with \Throwable handling, the app won't crash to tell you. Add a doctor check or Horizon supervisor for the notifications queue.
2. Keep a sync queue in local/test. QUEUE_CONNECTION=sync still works for alert delivery, but you lose the backoff/retry semantics, so don't rely on it as a production test.
3. Laravel Echo/Pusher is required only for log streaming, not for metrics or alerts.
4. Multi-server: aggregate via a shared database or Horizon, and run corewatch:doctor per node in your deploy pipeline.

Gotchas and Tips

Pitfalls

1. Silent alerts after upgrading to 2.2.0. Alerts are queued. If you previously relied on synchronous delivery, upgrade without a running worker and nothing arrives. Fix: set COREWATCH_NOTIFICATIONS_QUEUE, start a worker on that queue, and run php artisan corewatch:test-alert to prove delivery end-to-end.
2. \Throwable handling hides bugs. Collectors, controllers, repositories, and actions now catch \Throwable instead of \Exception. Fatal errors, type errors, and memory exhaustion no longer bubble up — always check storage/logs/corewatch.log and run corewatch:doctor before assuming a metric is simply unavailable.
3. WebSocket dependencies. Log streaming requires Echo/Pusher; without it /corewatch/logs fails. In tests:

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

4. Permissions for Safe Ops. Commands run as the web user (www-data). Use chmod +x for scripts and gate everything behind corewatch.roles.
5. Metric polling overhead. Start with metrics_interval = 60 seconds and tune from there.
6. Log channel mismatch. If nothing appears in the stream, confirm your log channels are listed in config/corewatch.php; debug via storage/logs/corewatch.log.
7. Filament route conflicts. Override the prefix:

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

Debugging

1. Start with the doctor — it isolates System vs Database vs Queue vs Alerts. Most "dashboard is blank" reports are a Cache or Scheduler failure it will name directly.
2. Isolate channel delivery with the interactive tester:

   php artisan corewatch:test-alert
   

   It gives diagnostic feedback on the webhook/credentials step rather than a generic failure.
3. Enable debug mode:

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

4. Clear cached metrics:

   php artisan corewatch:clear-cache
   

5. Inspect failed alert jobs (new failure mode since queued dispatch):

   php artisan queue:failed
   php artisan queue:retry all
   

Extension Points

1. Custom Metric Providers: implement Hamzi\CoreWatch\Contracts\MetricProvider and register it under 'providers' in config/corewatch.php.
2. Alert Notifications:

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

   If you extend a channel, make it queue-aware — throw on failure so SendQueuedAlertJob's backoff retries actually trigger.
3. Diagnostics consumers: CoreWatch::doctor()->run() returns a structured report — feed it to your own Slack notifier, uptime monitor, or /health endpoint instead of parsing CLI output.
4. UI customization: override Blade views in resources/views/vendor/corewatch/.
5. Raw data access: CoreWatch::metrics()->raw() and CoreWatch::logs()->recent(100) for custom endpoints.

Config Quirks

1. Env prefix: COREWATCH_* overrides config/corewatch.php; COREWATCH_NOTIFICATIONS_QUEUE is the new one to set explicitly.
2. Middleware order: place corewatch.auth before web to protect routes:

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

3. Log retention: retention_days defaults to 30 in the migrations — adjust and re-publish if you need longer history.