Add queue job lifecycle events for monitoring integration

Add events at key lifecycle points to enable integration with monitoring
tools like Sentry:

- Queue.Job.created: Fired when a job is added to the queue (producer)
- Queue.Job.started: Fired when a worker begins processing a job (consumer)
- Queue.Job.completed: Fired when a job finishes successfully
- Queue.Job.failed: Fired on every job failure (not just when exhausted)

These events provide the necessary hooks for implementing Sentry's queue
monitoring feature or similar monitoring tools. The job entity included
in each event provides all data needed for tracing (job ID, task name,
payload, attempts, timestamps).

Refs: LordSimal/cakephp-sentry#17

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: dereuromark

docs/sections/misc.md

@@ -51,6 +51,64 @@ This includes also failed ones if not filtered further using `where()` condition
 
 ## Events
 The Queue plugin dispatches events to allow you to hook into the queue processing lifecycle.
+These events are useful for monitoring, logging, and integrating with external services like Sentry.
+
+### Queue.Job.created
+This event is triggered when a new job is added to the queue (producer side).
+
+```php
+use Cake\Event\EventInterface;
+use Cake\Event\EventManager;
+
+EventManager::instance()->on('Queue.Job.created', function (EventInterface $event) {
+    $job = $event->getData('job');
+    // Track job creation for monitoring
+});
+```
+
+Event data:
+- `job`: The `QueuedJob` entity that was created
+
+### Queue.Job.started
+This event is triggered when a worker begins processing a job (consumer side).
+
+```php
+EventManager::instance()->on('Queue.Job.started', function (EventInterface $event) {
+    $job = $event->getData('job');
+    // Start tracing/monitoring span
+});
+```
+
+Event data:
+- `job`: The `QueuedJob` entity being processed
+
+### Queue.Job.completed
+This event is triggered when a job finishes successfully.
+
+```php
+EventManager::instance()->on('Queue.Job.completed', function (EventInterface $event) {
+    $job = $event->getData('job');
+    // Mark trace as successful
+});
+```
+
+Event data:
+- `job`: The `QueuedJob` entity that completed
+
+### Queue.Job.failed
+This event is triggered when a job fails (on every failure attempt).
+
+```php
+EventManager::instance()->on('Queue.Job.failed', function (EventInterface $event) {
+    $job = $event->getData('job');
+    $failureMessage = $event->getData('failureMessage');
+    // Mark trace as failed, log error
+});
+```
+
+Event data:
+- `job`: The `QueuedJob` entity that failed
+- `failureMessage`: The error message from the failure
 
 ### Queue.Job.maxAttemptsExhausted
 This event is triggered when a job has failed and exhausted all of its configured retry attempts.
@@ -81,10 +139,21 @@ EventManager::instance()->on('Queue.Job.maxAttemptsExhausted', function (EventIn
 });
 ```
 
-The event data contains:
+Event data:
 - `job`: The `QueuedJob` entity that failed
 - `failureMessage`: The error message from the last failure
 
+### Monitoring Integration (Sentry, etc.)
+
+These events enable integration with monitoring tools like Sentry's queue monitoring feature.
+The job entity provides all necessary data for tracing:
+
+- `$job->id` - Message identifier (`messaging.message.id`)
+- `$job->job_task` - Queue/topic name (`messaging.destination.name`)
+- `$job->data` - Payload for calculating message size (`messaging.message.body.size`)
+- `$job->attempts` - Retry count (`messaging.message.retry.count`)
+- `$job->created`, `$job->notbefore`, `$job->fetched` - For calculating receive latency (`messaging.message.receive.latency`)
+
 ## Notes
 
 `<TaskName>` is the complete class name without the Task suffix (e.g. Example or PluginName.Example).

src/Model/Table/QueuedJobsTable.php

@@ -6,7 +6,9 @@
 use ArrayObject;
 use Cake\Core\Configure;
 use Cake\Core\Plugin;
+use Cake\Event\Event;
 use Cake\Event\EventInterface;
+use Cake\Event\EventManager;
 use Cake\I18n\DateTime;
 use Cake\ORM\Query\SelectQuery;
 use Cake\ORM\Table;
@@ -216,8 +218,14 @@ public function createJob(string $jobTask, array|object|null $data = null, array
 		}
 
 		$queuedJob = $this->newEntity($queuedJob);
+		$queuedJob = $this->saveOrFail($queuedJob);
 
-		return $this->saveOrFail($queuedJob);
+		$event = new Event('Queue.Job.created', $this, [
+			'job' => $queuedJob,
+		]);
+		EventManager::instance()->dispatch($event);
+
+		return $queuedJob;
 	}
 
 	/**

src/Queue/Processor.php

@@ -213,6 +213,11 @@ protected function runJob(QueuedJob $queuedJob, string $pid): void {
 		$this->log('job ' . $queuedJob->job_task . ', id ' . $queuedJob->id, $pid, false);
 		$taskName = $queuedJob->job_task;
 
+		$event = new Event('Queue.Job.started', $this, [
+			'job' => $queuedJob,
+		]);
+		EventManager::instance()->dispatch($event);
+
 		$return = $failureMessage = null;
 		try {
 			$this->time = time();
@@ -242,6 +247,12 @@ protected function runJob(QueuedJob $queuedJob, string $pid): void {
 			$this->log('job ' . $queuedJob->job_task . ', id ' . $queuedJob->id . ' failed and ' . $failedStatus, $pid);
 			$this->io->out('Job did not finish, ' . $failedStatus . ' after try ' . $queuedJob->attempts . '.');
 
+			$event = new Event('Queue.Job.failed', $this, [
+				'job' => $queuedJob,
+				'failureMessage' => $failureMessage,
+			]);
+			EventManager::instance()->dispatch($event);
+
 			// Dispatch event when job has exhausted all retries
 			if ($failedStatus === 'aborted') {
 				$event = new Event('Queue.Job.maxAttemptsExhausted', $this, [
@@ -255,6 +266,12 @@ protected function runJob(QueuedJob $queuedJob, string $pid): void {
 		}
 
 		$this->QueuedJobs->markJobDone($queuedJob);
+
+		$event = new Event('Queue.Job.completed', $this, [
+			'job' => $queuedJob,
+		]);
+		EventManager::instance()->dispatch($event);
+
 		$this->io->out('Job Finished.');
 		$this->currentJob = null;
 	}

tests/TestCase/Model/Table/QueuedJobsTableTest.php

@@ -11,6 +11,8 @@
 
 use Cake\Core\Configure;
 use Cake\Datasource\ConnectionManager;
+use Cake\Event\EventList;
+use Cake\Event\EventManager;
 use Cake\I18n\DateTime;
 use Cake\ORM\TableRegistry;
 use Cake\TestSuite\TestCase;
@@ -752,6 +754,23 @@ public function testGetStats() {
 		$this->assertWithinRange(7200, (int)$queuedJob->fetchdelay, 1);
 	}
 
+	/**
+	 * Test that Queue.Job.created event is fired when a job is created
+	 *
+	 * @return void
+	 */
+	public function testJobCreatedEvent() {
+		// Set up event tracking
+		$eventList = new EventList();
+		EventManager::instance()->setEventList($eventList);
+
+		// Create a job
+		$job = $this->QueuedJobs->createJob('Queue.Example', ['test' => 'data']);
+
+		// Check that the created event was dispatched
+		$this->assertEventFired('Queue.Job.created');
+	}
+
 	/**
 	 * Helper method for skipping tests that need a real connection.
 	 *

tests/TestCase/Queue/ProcessorTest.php

@@ -286,6 +286,117 @@ public function testWorkerTimeoutHandlingIntegration() {
 		}
 	}
 
+	/**
+	 * Test that Queue.Job.started event is fired when job begins processing
+	 *
+	 * @return void
+	 */
+	public function testJobStartedEvent() {
+		// Set up event tracking
+		$eventList = new EventList();
+		EventManager::instance()->setEventList($eventList);
+
+		// Create a job
+		$QueuedJobs = $this->getTableLocator()->get('Queue.QueuedJobs');
+		$job = $QueuedJobs->createJob('Queue.Example', [], ['priority' => 1]);
+
+		// Create processor with mock task
+		$out = new ConsoleOutput();
+		$err = new ConsoleOutput();
+		$processor = $this->getMockBuilder(Processor::class)
+			->setConstructorArgs([new Io(new ConsoleIo($out, $err)), new NullLogger()])
+			->onlyMethods(['loadTask'])
+			->getMock();
+
+		// Create a mock task that succeeds (run method is void, so no return)
+		$mockTask = $this->getMockBuilder(\Queue\Queue\Task\ExampleTask::class)
+			->setConstructorArgs([new Io(new ConsoleIo($out, $err)), new NullLogger()])
+			->onlyMethods(['run'])
+			->getMock();
+
+		$processor->method('loadTask')->willReturn($mockTask);
+
+		// Run the job
+		$this->invokeMethod($processor, 'runJob', [$job, 'test-pid']);
+
+		// Check that the started event was dispatched
+		$this->assertEventFired('Queue.Job.started');
+	}
+
+	/**
+	 * Test that Queue.Job.completed event is fired when job finishes successfully
+	 *
+	 * @return void
+	 */
+	public function testJobCompletedEvent() {
+		// Set up event tracking
+		$eventList = new EventList();
+		EventManager::instance()->setEventList($eventList);
+
+		// Create a job
+		$QueuedJobs = $this->getTableLocator()->get('Queue.QueuedJobs');
+		$job = $QueuedJobs->createJob('Queue.Example', [], ['priority' => 1]);
+
+		// Create processor with mock task
+		$out = new ConsoleOutput();
+		$err = new ConsoleOutput();
+		$processor = $this->getMockBuilder(Processor::class)
+			->setConstructorArgs([new Io(new ConsoleIo($out, $err)), new NullLogger()])
+			->onlyMethods(['loadTask'])
+			->getMock();
+
+		// Create a mock task that succeeds (run method is void, so no return)
+		$mockTask = $this->getMockBuilder(\Queue\Queue\Task\ExampleTask::class)
+			->setConstructorArgs([new Io(new ConsoleIo($out, $err)), new NullLogger()])
+			->onlyMethods(['run'])
+			->getMock();
+
+		$processor->method('loadTask')->willReturn($mockTask);
+
+		// Run the job
+		$this->invokeMethod($processor, 'runJob', [$job, 'test-pid']);
+
+		// Check that the completed event was dispatched
+		$this->assertEventFired('Queue.Job.completed');
+	}
+
+	/**
+	 * Test that Queue.Job.failed event is fired when job fails
+	 *
+	 * @return void
+	 */
+	public function testJobFailedEvent() {
+		// Set up event tracking
+		$eventList = new EventList();
+		EventManager::instance()->setEventList($eventList);
+
+		// Create a job that will fail
+		$QueuedJobs = $this->getTableLocator()->get('Queue.QueuedJobs');
+		$job = $QueuedJobs->createJob('Queue.RetryExample', [], ['priority' => 1]);
+
+		// Create processor with mock task that fails
+		$out = new ConsoleOutput();
+		$err = new ConsoleOutput();
+		$processor = $this->getMockBuilder(Processor::class)
+			->setConstructorArgs([new Io(new ConsoleIo($out, $err)), new NullLogger()])
+			->onlyMethods(['loadTask'])
+			->getMock();
+
+		$mockTask = $this->getMockBuilder(RetryExampleTask::class)
+			->setConstructorArgs([new Io(new ConsoleIo($out, $err)), new NullLogger()])
+			->onlyMethods(['run'])
+			->getMock();
+		$mockTask->method('run')->willThrowException(new RuntimeException('Task failed'));
+
+		$processor->method('loadTask')->willReturn($mockTask);
+
+		// Run the job (it will fail)
+		$this->invokeMethod($processor, 'runJob', [$job, 'test-pid']);
+
+		// Check that the failed event was dispatched
+		$this->assertEventFired('Queue.Job.failed');
+	}
+
 	/**
 	 * Test setPhpTimeout with new config names
 	 *