Laravel Schedule Monitor Laravel Package

Technical Evaluation

Architecture Fit

• Observability Integration: The package excels as a dedicated observability layer for Laravel’s task scheduler, complementing existing monitoring tools (e.g., Laravel Horizon, Sentry, or Datadog). It bridges the gap between scheduled tasks and external alerting systems (e.g., Oh Dear) without requiring custom instrumentation.
• Event-Driven Logging: Leverages Laravel’s event system to log task lifecycle events (start/end/failure/skip) to a database table, enabling post-mortem analysis and trend tracking (e.g., execution time, memory usage).
• Extensibility: Supports customization via:
  • Task metadata (names, grace periods, output storage).
  • Model overrides (e.g., custom MonitoredScheduledTask models).
  • Integration hooks (e.g., Oh Dear sync, multitenancy support).
• Alignment with Laravel Ecosystem: Designed for seamless integration with Laravel’s scheduler (app/Console/Kernel.php), migrations, and queues, reducing friction in adoption.

Integration Feasibility

• Low-Coupling Design: Adds minimal overhead to existing scheduled tasks (only requires monitorName() or doNotMonitor() modifiers). No changes to task logic are needed unless opting into advanced features (e.g., output storage).
• Database Requirements: Introduces two tables (monitored_scheduled_tasks and monitored_scheduled_task_log_items), requiring:
  • Migration compatibility: Supports Laravel’s pruning for log cleanup.
  • Indexing: Log items should index task_id, event_type, and created_at for query performance.
• Queue Dependencies: Oh Dear pings use Laravel queues (PingOhDearJob), necessitating:
  • A dedicated queue (recommended) to avoid contention.
  • Queue worker capacity to handle ping retries (configurable via retry_job_for_minutes).
• External Services: Oh Dear integration requires:
  • API token and monitor ID configuration.
  • Network connectivity to ohdear.app (with fallback retry logic).

Technical Risk

Key Questions for TPM

1. Observability Strategy:

   • How does this package fit into the existing monitoring stack (e.g., does it replace, complement, or duplicate features of tools like Sentry or Datadog)?
   • Are there requirements for real-time alerts (e.g., Slack/email) beyond Oh Dear notifications?

2. Operational Constraints:

   • What are the SLA expectations for scheduled tasks? (Grace time defaults to 5 minutes—is this sufficient?)
   • How will log retention be managed? (Pruning frequency, storage costs.)

3. Deployment Workflow:

   • Should schedule-monitor:sync be automated in CI/CD (e.g., post-deploy hook) or run manually?
   • How will task naming be standardized? (Avoid ambiguous defaults like anonymous closures.)

4. External Dependencies:

   • Is Oh Dear’s API reliability acceptable, or should fallback alerts (e.g., custom webhooks) be implemented?
   • Are there compliance restrictions on sending task execution data to third-party services?

5. Scaling Considerations:

   • How many scheduled tasks are there? (Log table growth may require partitioning for >10K tasks.)
   • Will tasks run in multiple environments (dev/staging/prod)? (Sync configuration per environment.)

Integration Approach

Stack Fit

• Laravel Core: Native support for Laravel 10/11 (and 8 via v2). Integrates with:
  • Task Scheduler: Hooks into app/Console/Kernel.php via method chaining (monitorName(), graceTimeInMinutes()).
  • Queues: Uses Laravel’s queue system for Oh Dear pings (supports Horizon, database, or Redis queues).
  • Migrations: Standard Laravel migration system (publishable via vendor:publish).
• Database: Compatible with MySQL, PostgreSQL, SQLite (via Eloquent models).
• External Services: Oh Dear integration requires:
  • HTTP connectivity to ohdear.app.
  • API token with cron-job-monitoring permissions.

Migration Path

1. Assessment Phase:

   • Audit existing scheduled tasks in app/Console/Kernel.php for naming clarity and grace time needs.
   • Review current observability tools (e.g., logs, metrics) to identify gaps this package fills.

2. Pilot Deployment:

   • Install in a staging environment:

     composer require spatie/laravel-schedule-monitor
     php artisan vendor:publish --provider="Spatie\ScheduleMonitor\ScheduleMonitorServiceProvider" --tag="schedule-monitor-migrations"
     php artisan migrate
     

   • Configure OH_DEAR_API_TOKEN and OH_DEAR_MONITOR_ID (if using Oh Dear).
   • Run php artisan schedule-monitor:sync and verify with schedule-monitor:list.

3. Gradual Rollout:

   • Phase 1: Monitor critical tasks (e.g., payment processing, reports) with explicit names and grace times.
   • Phase 2: Enable Oh Dear integration for production tasks.
   • Phase 3: Store output in DB for debugging (opt-in via storeOutputInDb()).

4. Production Cutover:

   • Automate schedule-monitor:sync in deployment scripts.
   • Set up daily pruning for log items:

     // app/Console/Kernel.php
     $schedule->command('model:prune', ['--model' => \Spatie\ScheduleMonitor\Models\MonitoredScheduledTaskLogItem::class])->daily();
     

Compatibility

• Laravel Versions: Officially supports Laravel 10/11; v2 supports Laravel 8.
• PHP Versions: Requires PHP 8.1+ (Laravel 10/11 baseline).
• Queue Drivers: Works with all Laravel-supported queues (database, Redis, Horizon).
• Multitenancy: Explicit support for Spatie’s multitenancy package (add PingOhDearJob to not_tenant_aware_jobs).

Sequencing

1. Pre-requisites:

   • Laravel application with scheduled tasks defined.
   • Database with write permissions for new tables.
   • (Optional) Oh Dear account and API token.

2. Installation Order:

   • Composer install → Publish migrations/config → Run migrations → Configure .env.
   • Test in staging → Sync schedule → Validate logs.

3. Post-Installation:

   • Set up monitoring for Oh Dear pings (e.g., queue monitoring).
   • Configure alerts for failed pings (e.g., PagerDuty via Oh Dear webhooks).

Operational Impact

Maintenance

• Configuration Drift: Monitor config/schedule-monitor.php for changes (e.g., grace time, log retention).
• Schema Updates: Track Spatie’s releases for migration changes (low risk; MIT license).
• Oh Dear Dependencies: Renew API tokens if Oh Dear rotates them (check schedule-monitor:verify).
• Log Pruning: Ensure the model:prune command runs daily (cron job or Laravel scheduler).

Support

• Troubleshooting:
  • Failed Pings: Enable OH_DEAR_DEBUG_LOGGING=true for diagnostics.
  • Missing Logs: Verify task names are unique and monitorName() is used where needed.
  • Sync Issues: Check Oh Dear monitor ID and API token with schedule-monitor:verify.
• Alert Fatigue: Adjust grace times or disable Oh Dear for non-critical tasks to reduce noise.
• Customization: Extend models or commands for bespoke logging (e.g., additional metadata).

Scaling

• Log Volume: For >10K tasks/month, consider:
  • Partitioning monitored_scheduled_task_log_items by created_at.
  • Archiving old logs to cold storage (e.g., S3 via Laravel’s filesystem).
• Queue Scaling: Oh Dear pings should use a dedicated queue with sufficient workers (e.g., 1 worker per 1