add generic queue tracing feature

README.md

@@ -277,6 +277,46 @@ Finally, you have to enable the `enable_logs` flag in the Sentry SDK as well via
 ],
 ```
 
+### Queue Integration (optional)
+
+To get queue insights working, your application and/or queue plugin needs to dispatch events according to the following structure:
+
+```php
+// When a job is being enqueued
+$this->dispatchEvent('CakeSentry.Queue.enqueue', [
+    'class' => '\App\Job\ExampleJob', // optional, but recommended
+    'id' => 'unique-job-id', // optional, but recommended
+    'queue' => 'some-queue-name', // optional, defaults to 'default'
+    'data' => ['some' => 'data'], // optional, defaults to []
+]);
+
+// When a job starts processing
+$this->dispatchEvent('CakeSentry.Queue.beforeExecute', [
+    'class' => '\App\Job\ExampleJob', // optional, but recommended
+    'sentry_trace' => '<sentry-trace-header-value>', // optional
+    'sentry_baggage' => '<sentry-baggage-header-value>', // optional
+]);
+
+// When a job has been processed successfully
+$this->dispatchEvent('CakeSentry.Queue.afterExecute', [
+    'id' => 'unique-job-id', // optional, but recommended
+    'queue' => 'some-queue-name', // optional, defaults to 'default'
+    'data' => ['some' => 'data'], // optional, defaults to []
+    'execution_time' => 123, // optional, in milliseconds
+    'retry_count' => 0, // optional
+]);
+
+// When a job has failed during processing
+$this->dispatchEvent('CakeSentry.Queue.afterExecute', [
+    'id' => 'unique-job-id', // optional, but recommended
+    'queue' => 'some-queue-name', // optional, defaults to 'default'
+    'data' => ['some' => 'data'], // optional, defaults to []
+    'execution_time' => 123, // optional, in milliseconds
+    'retry_count' => 0, // optional
+    'exception' => $exception, // required, the exception that was thrown
+]);
+```
+
 ## Upgrade from 2 to 3
 
 There are a few major changes from 2.0 to 3.0

phpstan.neon

@@ -7,3 +7,5 @@ parameters:
 	ignoreErrors:
 		-
 			identifier: missingType.iterableValue
+		-
+			identifier: missingType.generics

src/CakeSentryPlugin.php

@@ -5,7 +5,9 @@
 
 use Cake\Core\BasePlugin;
 use Cake\Core\Configure;
+use Cake\Event\EventManagerInterface;
 use Cake\Http\MiddlewareQueue;
+use CakeSentry\Event\QueueEventListener;
 use CakeSentry\Middleware\CakeSentryPerformanceMiddleware;
 use CakeSentry\Middleware\CakeSentryQueryMiddleware;
 
@@ -29,4 +31,13 @@ public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue
 
         return $middlewareQueue;
     }
+
+    /**
+     * @param \Cake\Event\EventManagerInterface $eventManager
+     * @return \Cake\Event\EventManagerInterface
+     */
+    public function events(EventManagerInterface $eventManager): EventManagerInterface
+    {
+        return $eventManager->on(new QueueEventListener());
+    }
 }

src/Event/QueueEventListener.php

@@ -0,0 +1,107 @@
+<?php
+declare(strict_types=1);
+
+namespace CakeSentry\Event;
+
+use Cake\Event\Event;
+use Cake\Event\EventListenerInterface;
+use Sentry\SentrySdk;
+use Sentry\Tracing\SpanContext;
+use Sentry\Tracing\SpanStatus;
+use Sentry\Tracing\Transaction;
+use function Sentry\continueTrace;
+use function Sentry\startTransaction;
+
+class QueueEventListener implements EventListenerInterface
+{
+    protected ?Transaction $consumerTransaction = null;
+
+    /**
+     * @inheritDoc
+     */
+    public function implementedEvents(): array
+    {
+        return [
+            'CakeSentry.Queue.enqueue' => 'handleEnqueue',
+            'CakeSentry.Queue.beforeExecute' => 'handleBeforeExecute',
+            'CakeSentry.Queue.afterExecute' => 'handleAfterExecute',
+        ];
+    }
+
+    /**
+     * @param \Cake\Event\Event $event
+     * @return void
+     */
+    public function handleEnqueue(Event $event): void
+    {
+        $parentSpan = SentrySdk::getCurrentHub()->getSpan();
+        $jobData = $event->getData();
+        $jobClass = $jobData['class'] ?? 'Unknown';
+
+        if ($parentSpan === null) {
+            return;
+        }
+
+        $context = SpanContext::make()->setOp('queue.publish');
+        $span = $parentSpan->startChild($context);
+        SentrySdk::getCurrentHub()->setSpan($span);
+
+        $span
+            ->setDescription(sprintf('queue.publish %s', $jobClass))
+            ->setData([
+                'messaging.message.id' => $jobData['id'] ?? null,
+                'messaging.destination.name' => $jobData['queue'] ?? 'default',
+                'messaging.message.body.size' => strlen(json_encode($jobData['data'] ?? []) ?: ''),
+            ])
+            ->finish();
+
+        SentrySdk::getCurrentHub()->setSpan($parentSpan);
+    }
+
+    /**
+     * @param \Cake\Event\Event $event
+     * @return void
+     */
+    public function handleBeforeExecute(Event $event): void
+    {
+        $jobData = $event->getData();
+        $jobClass = $jobData['class'] ?? 'Unknown';
+
+        $context = continueTrace(
+            $jobData['sentry_trace'] ?? '',
+            $jobData['sentry_baggage'] ?? '',
+        )
+            ->setOp('queue.process')
+            ->setName($jobClass);
+
+        $this->consumerTransaction = startTransaction($context);
+        SentrySdk::getCurrentHub()->setSpan($this->consumerTransaction);
+    }
+
+    /**
+     * @param \Cake\Event\Event $event
+     * @return void
+     */
+    public function handleAfterExecute(Event $event): void
+    {
+        $jobData = $event->getData();
+        $result = $event->getResult();
+
+        if ($this->consumerTransaction === null) {
+            return;
+        }
+
+        $success = $result !== false && !isset($jobData['exception']);
+
+        $this->consumerTransaction
+            ->setData([
+                'messaging.message.id' => $jobData['id'] ?? null,
+                'messaging.destination.name' => $jobData['queue'] ?? 'default',
+                'messaging.message.body.size' => strlen(json_encode($jobData['data'] ?? []) ?: ''),
+                'messaging.message.receive.latency' => $jobData['execution_time'] ?? 0,
+                'messaging.message.retry.count' => $jobData['retry_count'] ?? 0,
+            ])
+            ->setStatus($success ? SpanStatus::ok() : SpanStatus::internalError())
+            ->finish();
+    }
+}