Laravel Schedule Monitor Laravel Package

Technical Evaluation

Architecture Fit

• Laravel-Native Integration: The package is designed specifically for Laravel’s built-in task scheduling system (artisan schedule), making it a seamless fit for Laravel applications. It leverages Laravel’s Eloquent models, queues, and command structure, ensuring minimal architectural disruption.
• Observability-First: Aligns with modern DevOps practices by providing structured logging, metrics (execution time, memory usage), and alerting capabilities. This is particularly valuable for microservices, batch processing, or high-availability systems where task reliability is critical.
• Extensibility: Supports customization via config files, model overrides, and method chaining (e.g., monitorName(), graceTimeInMinutes()), allowing TPMs to adapt it to specific use cases without forking the package.

Integration Feasibility

• Low Friction: Requires only:
  1. Composer installation.
  2. Database migrations (minimal schema changes).
  3. Configuration (primarily Oh Dear API tokens if used).
• Non-Invasive: Does not modify core Laravel behavior; hooks into the existing Schedule facade and job lifecycle. Existing scheduled tasks continue to work unchanged.
• Dependency Lightweight: Adds only two Eloquent models (MonitoredScheduledTask, MonitoredScheduledTaskLogItem) and a single queue job (PingOhDearJob), with no external dependencies beyond Laravel itself and Oh Dear (optional).

Technical Risk

• Database Bloat: Logs accumulate over time (configurable via delete_log_items_older_than_days). Requires proactive pruning (e.g., daily model:prune command) to avoid performance degradation in high-volume environments.
• Oh Dear Dependency: While optional, the Oh Dear integration introduces:
  • External API calls (network latency, rate limits).
  • Potential false positives if grace time is misconfigured.
  • Cost implications if using Oh Dear’s paid tier for advanced features (e.g., Slack/SMS alerts).
• Multitenancy Edge Cases: If using spatie/laravel-multitenancy, the PingOhDearJob must be explicitly whitelisted in not_tenant_aware_jobs to avoid tenant context errors.
• Legacy Laravel Support: While the package supports Laravel 8+ (via v2), older versions (e.g., Laravel 7) may require additional polyfills or manual adjustments.

Key Questions for TPM

1. Observability Goals:
   • What are the primary use cases for monitoring (e.g., debugging failures, SLA compliance, capacity planning)?
   • Are there existing tools (e.g., Prometheus, Datadog) that could conflict or duplicate functionality?
2. Alerting Strategy:
   • Should Oh Dear be the sole alerting mechanism, or should logs trigger internal alerts (e.g., Slack via Laravel Notifications)?
   • What grace time thresholds are appropriate for different task types (e.g., 5 mins for CLI commands vs. 30 mins for long-running jobs)?
3. Operational Overhead:
   • How will log pruning be automated (e.g., cron job, Laravel Horizon)?
   • Who will manage Oh Dear API tokens and monitor IDs (DevOps vs. TPM)?
4. Scaling:
   • For high-frequency tasks (e.g., every minute), will the database or queue become a bottleneck?
   • Should log retention be adjusted (e.g., 7 days vs. 30) based on compliance or debugging needs?
5. Customization Needs:
   • Are there tasks that should be excluded from monitoring (e.g., health checks)?
   • Should output storage (storeOutputInDb) be enabled for all tasks or only critical ones?

Integration Approach

Stack Fit

• Laravel Ecosystem: Perfectly aligned with Laravel’s scheduling system (artisan schedule), queue workers, and Eloquent ORM. No additional infrastructure (e.g., Kubernetes, Docker) is required beyond a standard Laravel deployment.
• Queue Systems: Works with Laravel’s default queue (database, Redis, etc.) or Horizon for PingOhDearJob. Recommends a dedicated queue for Oh Dear pings to avoid contention.
• Database: Compatible with all Laravel-supported databases (MySQL, PostgreSQL, SQLite). Schema is simple (two tables) and can be extended for custom fields.
• CI/CD: Sync command (schedule-monitor:sync) should be triggered post-deploy to ensure Oh Dear and local logs are up to date.

Migration Path

1. Pilot Phase:
   • Install in a staging environment and monitor a subset of non-critical tasks (e.g., report generation).
   • Validate log accuracy and Oh Dear sync (if used) with the schedule-monitor:list and schedule-monitor:verify commands.
2. Gradual Rollout:
   • Enable monitoring for high-priority tasks first (e.g., payment processing, data syncs).
   • Use doNotMonitor() for tasks where observability is already handled (e.g., by third-party tools).
3. Oh Dear Onboarding:
   • Set up Oh Dear monitors before syncing to avoid misconfigured alerts.
   • Test the OH_DEAR_DEBUG_LOGGING flag in staging to debug connectivity issues.

Compatibility

• Laravel Versions: Officially supports Laravel 8+ (v2). For Laravel 7, use v1 or apply minor patches.
• PHP Versions: Requires PHP 8.0+ (aligned with Laravel’s minimum requirements).
• Queue Drivers: Tested with database, Redis, and SQS. For self-hosted queues, ensure PingOhDearJob is compatible with the driver’s retry logic.
• Multitenancy: Explicit support for spatie/laravel-multitenancy via config. For other multitenancy solutions (e.g., Stancl/Tenant), manual tenant context handling may be needed.

Sequencing

1. Pre-Installation:
   • Review existing scheduled tasks in app/Console/Kernel.php to identify naming conventions and grace time requirements.
   • Decide on Oh Dear integration (if needed) and configure API tokens/monitor IDs.
2. Installation:
   • Run migrations and publish config.
   • Configure log pruning in app/Console/Kernel.php (e.g., daily model:prune).
3. Sync and Validate:
   • Run schedule-monitor:sync in staging and verify with schedule-monitor:list.
   • Test Oh Dear sync with schedule-monitor:verify.
4. Production Rollout:
   • Add schedule-monitor:sync to deployment scripts.
   • Monitor database growth and queue performance post-launch.

Operational Impact

Maintenance

• Low Touch: Minimal ongoing maintenance required beyond:
  • Periodic log pruning (automated via model:prune).
  • Oh Dear API token rotation (if using).
  • Occasional syncs post-config changes (e.g., new tasks added).
• Configuration Drift: Changes to task names or grace times in Kernel.php require a sync to update Oh Dear and local logs.
• Dependency Updates: Monitor Spatie’s releases for Laravel version compatibility (e.g., PHP 8.2+ features).

Support

• Debugging: Provides rich logs (execution time, memory, output) for troubleshooting failed tasks. Oh Dear’s UI can also visualize historical trends.
• Alert Fatigue: Configure grace times carefully to avoid false positives (e.g., a 1-hour task with a 5-minute grace time will trigger alerts frequently).
• Oh Dear Limitations: Users must manage their own Oh Dear account/subscriptions. Support tickets may require coordination between Laravel and Oh Dear teams.

Scaling

• Database:
  • Log table growth can be mitigated by adjusting delete_log_items_older_than_days (default: 30).
  • For high-volume tasks (e.g., >1000 runs/day), consider archiving logs to cold storage (e.g., S3) after pruning.
• Queue:
  • PingOhDearJob should use a dedicated queue to avoid delays during peak traffic.
  • Monitor queue backlogs for slow Oh Dear API responses (e.g., network issues).
• Performance:
  • Log queries (e.g., schedule-monitor:list) may slow down with large log tables. Indexes on task_name and created_at are recommended.
  • For read-heavy workloads, consider caching frequent queries (e.g., last 24 hours of task status).

Failure Modes