Console Scheduling Monitoring

Purpose and Scope

The ConsoleSchedulingFeature integrates Sentry's cron monitoring functionality with Hypervel's task scheduler. It enables monitoring of scheduled tasks by sending check-in events to Sentry, tracking whether tasks run on schedule, complete successfully, or fail. The feature also creates performance traces for scheduled tasks when tracing is enabled.

This document covers the check-in system, the sentryMonitor macro, slug generation, and background task handling. For general feature system architecture, see page 3.1 (Feature System Overview). For information about other monitoring features, see page 3.2 (Cache Monitoring), page 3.3 (Queue Monitoring), and page 3.4 (Redis Monitoring).

Architecture Overview

The ConsoleSchedulingFeature operates by:

1. Adding a sentryMonitor macro to Hypervel's SchedulingEvent class during registration
2. Listening to scheduled task lifecycle events during boot
3. Creating and updating Sentry check-ins as tasks execute
4. Creating performance traces for task execution when tracing is enabled

Sources: src/Features/ConsoleSchedulingFeature.php1-326

Feature Applicability

The feature is active when either tracing or breadcrumbs are enabled for console_scheduling in the configuration.

Sources: src/Features/ConsoleSchedulingFeature.php114-118

The sentryMonitor Macro

The sentryMonitor macro is added to the SchedulingEvent class during the registration phase. This macro allows developers to opt scheduled tasks into Sentry monitoring by chaining it onto task definitions.

Macro Signature

sentryMonitor(
 ?string $monitorSlug = null,
 ?int $checkInMargin = null,
 ?int $maxRuntime = null,
 bool $updateMonitorConfig = true,
 ?int $failureIssueThreshold = null,
 ?int $recoveryThreshold = null
): SchedulingEvent

Parameters

Parameter	Type	Default	Description
$monitorSlug	?string	null	Custom slug for the monitor. If null, auto-generated from command/description
$checkInMargin	?int	null	Minutes before expected check-in when Sentry should alert
$maxRuntime	?int	null	Maximum expected runtime in minutes
$updateMonitorConfig	bool	true	Whether to update monitor configuration on each check-in
$failureIssueThreshold	?int	null	Number of consecutive failures before creating an issue
$recoveryThreshold	?int	null	Number of successful check-ins required to mark monitor as recovered

Macro Behavior

The macro registers three callbacks on the SchedulingEvent:

1. Before callback: Starts a check-in with in_progress status before task execution
2. On success callback: Finishes the check-in with ok status after successful completion
3. On failure callback: Finishes the check-in with error status if the task fails

Sources: src/Features/ConsoleSchedulingFeature.php67-111

Slug Requirement

If $monitorSlug is null, the macro requires either the command or description property to be set on the SchedulingEvent. Otherwise, it throws a RuntimeException requesting a manual slug.

Sources: src/Features/ConsoleSchedulingFeature.php76-80

Check-In Lifecycle

Sources: src/Features/ConsoleSchedulingFeature.php44-111 src/Features/ConsoleSchedulingFeature.php169-253

Check-In Creation and Management

Creating Check-Ins

Check-ins are created by the createCheckIn() method, which constructs a Sentry\CheckIn object with the following information:

• Slug: Limited to 128 characters
• Status: in_progress, ok, or error
• ID: For continuation of existing check-ins (from cache for background tasks)
• Release: From Sentry client options
• Environment: From Sentry client options

Sources: src/Features/ConsoleSchedulingFeature.php263-274

Monitor Configuration

When $updateMonitorConfig is true (default) or when the slug is auto-generated, the feature creates a MonitorConfig with:

• Schedule: Crontab expression from the scheduled task
• Check-in margin: Time before expected execution when alerts should fire
• Max runtime: Maximum expected execution time
• Timezone: From the scheduled task's timezone property
• Failure issue threshold: Consecutive failures before creating an issue
• Recovery threshold: Successful runs required to mark as recovered

Sources: src/Features/ConsoleSchedulingFeature.php186-203

Sending Check-Ins

Check-ins are sent to Sentry by creating a check-in event and capturing it through the Hub:

$event = SentryEvent::createCheckIn();
$event->setCheckIn($checkIn);
SentrySdk::getCurrentHub()->captureEvent($event);

Sources: src/Features/ConsoleSchedulingFeature.php255-261

Background Task Handling

For tasks that run in the background ($scheduled->runInBackground === true), the feature uses caching to persist check-in IDs across process boundaries.

Cache Key Construction

Cache keys are constructed using the task's mutex name and the check-in slug to avoid collisions:

'sentry:checkIn:' . sha1("{$mutex}:{$slug}")

The mutex name is unique per scheduled task and varies based on the task's execution frequency and parameters.

Sources: src/Features/ConsoleSchedulingFeature.php276-280

Cache TTL

Check-in IDs are stored in the cache with a TTL of $scheduled->expiresAt * 60 seconds, matching the task's expiration time.

Sources: src/Features/ConsoleSchedulingFeature.php209-211

Configuring Cache Store

The cache store can be configured using the useCacheStore() method:

If not specified, the default cache store is used.

Sources: src/Features/ConsoleSchedulingFeature.php135-138

Automatic Slug Generation

When $monitorSlug is null, the feature automatically generates a slug from the scheduled task's properties.

Slug Generation Logic

Slug Patterns

Task Type	Source	Example Input	Example Output
Command	command property	php artisan inspire	scheduled_inspire
Job	description property	App\Jobs\ProcessData	scheduled_processdata_jobs_app
Closure	Fallback	N/A	scheduled_closure

Sources: src/Features/ConsoleSchedulingFeature.php282-308

Class Name Reversal

For job classes, the namespace is reversed to put the class name at the beginning of the slug, preventing it from being cut off if the slug is truncated:

App\Jobs\ProcessData → processdata_jobs_app → scheduled_processdata_jobs_app

Sources: src/Features/ConsoleSchedulingFeature.php286-289

Tracing Integration

In addition to check-ins, the feature creates performance traces for scheduled tasks by listening to Hypervel's scheduling events.

Transaction Creation

Transaction Naming

Transactions are named using the command name extracted from the task:

1. For commands: Extracts the command after removing the PHP binary and artisan binary paths
2. For jobs: Uses the job class name from the description property
3. For closures: Uses the literal string "Closure"

Sources: src/Features/ConsoleSchedulingFeature.php140-155 src/Features/ConsoleSchedulingFeature.php310-320

Transaction Completion

Sources: src/Features/ConsoleSchedulingFeature.php157-167

Span Stack Management

The feature uses the TracksPushedScopesAndSpans trait to manage the span stack, ensuring proper cleanup even if errors occur.

Sources: src/Features/ConsoleSchedulingFeature.php31

Event Listener Registration

During the boot phase, the feature registers three event listeners:

Event	Handler	Purpose
ScheduledTaskStarting	handleScheduledTaskStarting()	Create transaction for tracing
ScheduledTaskFinished	handleScheduledTaskFinished()	Finish transaction with success status
ScheduledTaskFailed	handleScheduledTaskFailed()	Finish transaction with error status

The listeners are registered through Hypervel's event dispatcher.

Sources: src/Features/ConsoleSchedulingFeature.php120-128

Conditional Check-In Processing

The shouldHandleCheckIn flag controls whether check-ins are actually created and sent:

• Set to true in onBoot() when the feature is active
• Set to false in onBootInactive() when the feature is disabled
• Checked at the start of startCheckIn() and finishCheckIn()

This allows the macro to remain attached to scheduled tasks even when the feature is disabled, without generating any Sentry events.

Sources: src/Features/ConsoleSchedulingFeature.php120-133 src/Features/ConsoleSchedulingFeature.php178-180 src/Features/ConsoleSchedulingFeature.php218-220

Storage Architecture

Sources: src/Features/ConsoleSchedulingFeature.php33-38 src/Features/ConsoleSchedulingFeature.php205-211 src/Features/ConsoleSchedulingFeature.php276-280