Monitor Command

Purpose and Scope

The MonitorCommand provides real-time monitoring of queue sizes across multiple connections and queues. It displays queue metrics in a tabular format and dispatches QueueBusy events when queue sizes exceed configured thresholds, enabling automated alerting and scaling decisions.

This document covers the queue:monitor command implementation. For continuous job processing, see Work Command. For listing failed jobs, see Failed Job Management Commands.

Sources: src/Console/MonitorCommand.php1-115

Command Overview

The MonitorCommand class is located at src/Console/MonitorCommand.php15 and extends Hyperf's Command class. It integrates with three core services via constructor injection:

Dependency	Type	Purpose
$manager	Factory (QueueManager)	Retrieves queue connections and queries queue sizes
$events	EventDispatcherInterface	Dispatches QueueBusy events for alerting
$config	ConfigInterface	Resolves default connection configuration

Command Signature

queue:monitor {queues} [--max=1000]

Parameter	Type	Required	Description
queues	argument	Yes	Comma-separated list of queues to monitor
--max	option	No	Maximum queue size threshold before alert (default: 1000)

Sources: src/Console/MonitorCommand.php22-29 src/Console/MonitorCommand.php39-45

Command Execution Flow

Sources: src/Console/MonitorCommand.php50-57 src/Console/MonitorCommand.php63-86 src/Console/MonitorCommand.php91-94 src/Console/MonitorCommand.php99-114

Queue Specification Format

The command accepts queues in two formats:

1. Queue name only: queue_name - Uses default connection from configuration
2. Connection-prefixed: connection_name:queue_name - Uses specified connection

Multiple queues are separated by commas. The parsing logic at src/Console/MonitorCommand.php63-86 handles this:

Sources: src/Console/MonitorCommand.php63-72

Queue Metrics Collection

For each parsed queue, the command collects six metrics by querying the QueueManager:

The collected data structure at src/Console/MonitorCommand.php73-84:

Field	Source Method	Description
connection	Parsed from input	Connection name
queue	Parsed from input	Queue name
size	connection()->size()	Total number of jobs in queue
pending	connection()->pendingSize()	Jobs ready for processing
delayed	connection()->delayedSize()	Jobs scheduled for future execution
reserved	connection()->reservedSize()	Jobs currently being processed
oldest_pending	connection()->creationTimeOfOldestPendingJob()	Creation timestamp of oldest pending job
status	Calculated	ALERT if size >= max, otherwise OK

Sources: src/Console/MonitorCommand.php73-84

Output Display

The command displays results in a table format using Hyperf's table rendering at src/Console/MonitorCommand.php91-94:

The Status column uses colored output formatting:

• ALERT: <fg=yellow;options=bold>ALERT</> - Yellow, bold text when size >= max threshold
• OK: <fg=green;options=bold>OK</> - Green, bold text when size < max threshold

Sources: src/Console/MonitorCommand.php34 src/Console/MonitorCommand.php81-83 src/Console/MonitorCommand.php91-94

Event Dispatching System

When a queue exceeds the threshold, the command dispatches a QueueBusy event to enable automated responses:

The event dispatching logic at src/Console/MonitorCommand.php99-114:

1. Iterates through all monitored queues
2. Skips queues with OK status at src/Console/MonitorCommand.php102-104
3. Creates QueueBusy event with connection, queue name, and size at src/Console/MonitorCommand.php107-111
4. Dispatches event via EventDispatcherInterface at src/Console/MonitorCommand.php106

QueueBusy Event Structure

The QueueBusy event is created at src/Console/MonitorCommand.php107-111 with three properties:

Applications can listen for this event to implement custom alerting, auto-scaling, or monitoring dashboards.

Sources: src/Console/MonitorCommand.php99-114 src/Console/MonitorCommand.php11

Component Interactions

Sources: src/Console/MonitorCommand.php39-45 src/Console/MonitorCommand.php50-57

Usage Examples

Example 1: Monitor Single Queue

This monitors the default queue on the default connection with a threshold of 1000 jobs.

Example 2: Monitor Multiple Queues

Monitors three queues (emails, sms, notifications) on the default connection.

Example 3: Monitor Queues on Different Connections

Monitors:

• emails queue on redis connection
• exports queue on database connection
• reports queue on redis connection

Example 4: Custom Threshold

Monitors the high-priority queue with a lower threshold of 100 jobs, triggering alerts for queues with 100+ jobs.

Example 5: Low-Latency Monitoring

Monitors a realtime queue with a very low threshold of 10 jobs, useful for latency-sensitive queues that should remain nearly empty.

Sources: src/Console/MonitorCommand.php22-24

Integration with Monitoring Systems

The command is designed for scheduled execution via cron or systemd timers. Common patterns:

Cron-Based Monitoring

Event Listener Example

Applications register event listeners to respond to QueueBusy events:

Sources: src/Console/MonitorCommand.php11 src/Console/MonitorCommand.php99-114

Design Considerations

Single Execution Model

Unlike WorkCommand which runs continuously, MonitorCommand executes once and exits at src/Console/MonitorCommand.php50-57 This design:

• Enables flexible scheduling via external tools
• Prevents resource leaks from long-running processes
• Allows parallel monitoring of different queue sets
• Simplifies error handling and recovery

Connection Pooling

The command queries multiple connections efficiently. Each connection request at src/Console/MonitorCommand.php76-80 uses the QueueManager's connection pooling, reusing established connections across multiple queue queries on the same connection.

Metric Query Performance

The command makes 5 separate method calls per queue (src/Console/MonitorCommand.php76-80):

• size() - Total jobs
• pendingSize() - Available jobs
• delayedSize() - Scheduled jobs
• reservedSize() - Processing jobs
• creationTimeOfOldestPendingJob() - Age metric

For drivers like Redis, these operations leverage Lua scripts for atomic queries. For database drivers, they execute as separate SELECT queries. Consider monitoring performance when checking many queues frequently.

Sources: src/Console/MonitorCommand.php50-57 src/Console/MonitorCommand.php76-80