Log why an event was dropped

README.md

@@ -212,6 +212,23 @@ final class AddCustomerToConversionsApiEvent
 You can also replace a step instead of adding to it: alias `PixelProviderInterface`, `FbpContextInterface` or
 `FbcContextInterface` to your own service, or register a listener above the corresponding populate priority.
 
+### Why did my event not show up?
+
+Every listener that drops an event says so at debug level on the `setono_meta_conversions_api` Monolog channel: the
+bot filter, the user agent filters, the no-pixels check, and each of the three consent gates. The send handler logs a
+warning when a pixel has no access token.
+
+```yaml
+# config/packages/monolog.yaml
+monolog:
+    handlers:
+        meta:
+            type: stream
+            path: '%kernel.logs_dir%/meta.log'
+            level: debug
+            channels: ['setono_meta_conversions_api']
+```
+
 ### Events that are not raised in a browser request
 
 The pipeline assumes the event belongs to the request being handled. `PopulateRequestPropertiesSubscriber` therefore

src/EventSubscriber/AddEventToTagBagSubscriber.php

@@ -4,6 +4,8 @@
 
 namespace Setono\MetaConversionsApiBundle\EventSubscriber;
 
+use Psr\Log\LoggerInterface;
+use Psr\Log\NullLogger;
 use Setono\MetaConversionsApi\Event\Parameters;
 use Setono\MetaConversionsApi\Generator\FbqGeneratorInterface;
 use Setono\MetaConversionsApiBundle\ConsentChecker\ConsentCheckerInterface;
@@ -15,11 +17,15 @@
 
 final class AddEventToTagBagSubscriber implements EventSubscriberInterface
 {
+    private readonly LoggerInterface $logger;
+
     public function __construct(
         private readonly TagBagInterface $tagBag,
         private readonly FbqGeneratorInterface $fbqGenerator,
         private readonly ConsentCheckerInterface $consentChecker,
+        ?LoggerInterface $logger = null,
     ) {
+        $this->logger = $logger ?? new NullLogger();
     }
 
     public static function getSubscribedEvents(): array
@@ -32,6 +38,11 @@ public static function getSubscribedEvents(): array
     public function add(ConversionsApiEventRaised $event): void
     {
         if (!$this->consentChecker->isGranted()) {
+            $this->logger->debug('The event {event_name} ({event_id}) was not rendered client side because consent was not granted', [
+                'event_name' => $event->event->eventName,
+                'event_id' => $event->event->eventId,
+            ]);
+
             return;
         }
 

src/EventSubscriber/AddLibraryToTagBagSubscriber.php

@@ -4,6 +4,8 @@
 
 namespace Setono\MetaConversionsApiBundle\EventSubscriber;
 
+use Psr\Log\LoggerInterface;
+use Psr\Log\NullLogger;
 use Setono\MetaConversionsApi\Generator\FbqGeneratorInterface;
 use Setono\MetaConversionsApiBundle\ConsentChecker\ConsentCheckerInterface;
 use Setono\MetaConversionsApiBundle\Provider\PixelProviderInterface;
@@ -17,12 +19,16 @@
 
 final class AddLibraryToTagBagSubscriber implements EventSubscriberInterface
 {
+    private readonly LoggerInterface $logger;
+
     public function __construct(
         private readonly TagBagInterface $tagBag,
         private readonly FbqGeneratorInterface $fbqGenerator,
         private readonly ConsentCheckerInterface $consentChecker,
         private readonly PixelProviderInterface $pixelProvider,
+        ?LoggerInterface $logger = null,
     ) {
+        $this->logger = $logger ?? new NullLogger();
     }
 
     public static function getSubscribedEvents(): array
@@ -39,11 +45,15 @@ public function add(RequestEvent $event): void
         }
 
         if (!$this->consentChecker->isGranted()) {
+            $this->logger->debug('The Meta pixel library was not rendered because consent was not granted');
+
             return;
         }
 
         $pixels = $this->pixelProvider->getPixels();
         if ([] === $pixels) {
+            $this->logger->debug('The Meta pixel library was not rendered because no pixels are available. Did you configure any?');
+
             return;
         }
 

src/EventSubscriber/DispatchOnCommandBusSubscriber.php

@@ -4,6 +4,8 @@
 
 namespace Setono\MetaConversionsApiBundle\EventSubscriber;
 
+use Psr\Log\LoggerInterface;
+use Psr\Log\NullLogger;
 use Setono\MetaConversionsApiBundle\ConsentChecker\ConsentCheckerInterface;
 use Setono\MetaConversionsApiBundle\Event\ConversionsApiEventRaised;
 use Setono\MetaConversionsApiBundle\Message\Command\SendEvent;
@@ -12,10 +14,14 @@
 
 final class DispatchOnCommandBusSubscriber implements EventSubscriberInterface
 {
+    private readonly LoggerInterface $logger;
+
     public function __construct(
         private readonly MessageBusInterface $commandBus,
         private readonly ConsentCheckerInterface $consentChecker,
+        ?LoggerInterface $logger = null,
     ) {
+        $this->logger = $logger ?? new NullLogger();
     }
 
     public static function getSubscribedEvents(): array
@@ -28,6 +34,11 @@ public static function getSubscribedEvents(): array
     public function dispatch(ConversionsApiEventRaised $event): void
     {
         if (!$this->consentChecker->isGranted()) {
+            $this->logger->debug('The event {event_name} ({event_id}) was not sent server side because consent was not granted', [
+                'event_name' => $event->event->eventName,
+                'event_id' => $event->event->eventId,
+            ]);
+
             return;
         }
 

src/EventSubscriber/FilterBotsSubscriber.php

@@ -4,15 +4,22 @@
 
 namespace Setono\MetaConversionsApiBundle\EventSubscriber;
 
+use Psr\Log\LoggerInterface;
+use Psr\Log\NullLogger;
 use Setono\BotDetectionBundle\BotDetector\BotDetectorInterface;
 use Setono\MetaConversionsApi\Event\Event;
 use Setono\MetaConversionsApiBundle\Event\ConversionsApiEventRaised;
 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 
 final class FilterBotsSubscriber implements EventSubscriberInterface
 {
-    public function __construct(private readonly BotDetectorInterface $botDetector)
-    {
+    private readonly LoggerInterface $logger;
+
+    public function __construct(
+        private readonly BotDetectorInterface $botDetector,
+        ?LoggerInterface $logger = null,
+    ) {
+        $this->logger = $logger ?? new NullLogger();
     }
 
     public static function getSubscribedEvents(): array
@@ -31,6 +38,12 @@ public function filter(ConversionsApiEventRaised $event): void
         }
 
         if ($this->botDetector->isBotRequest()) {
+            $this->logger->debug('The event {event_name} ({event_id}) was dropped because the request comes from a bot: {user_agent}', [
+                'event_name' => $event->event->eventName,
+                'event_id' => $event->event->eventId,
+                'user_agent' => $event->event->userData->clientUserAgent,
+            ]);
+
             $event->stopPropagation();
         }
     }

src/EventSubscriber/FilterConfiguredUserAgentsSubscriber.php

@@ -4,6 +4,8 @@
 
 namespace Setono\MetaConversionsApiBundle\EventSubscriber;
 
+use Psr\Log\LoggerInterface;
+use Psr\Log\NullLogger;
 use Setono\MetaConversionsApiBundle\Event\ConversionsApiEventRaised;
 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 
@@ -14,13 +16,17 @@ final class FilterConfiguredUserAgentsSubscriber implements EventSubscriberInter
      */
     private readonly ?string $pattern;
 
+    private readonly LoggerInterface $logger;
+
     /**
      * @param list<string> $userAgents Regular expression fragments without delimiters
      *
      * @throws \InvalidArgumentException if the fragments do not compile into a valid regular expression
      */
-    public function __construct(array $userAgents)
+    public function __construct(array $userAgents, ?LoggerInterface $logger = null)
     {
+        $this->logger = $logger ?? new NullLogger();
+
         if ([] === $userAgents) {
             $this->pattern = null;
 
@@ -60,6 +66,12 @@ public function filter(ConversionsApiEventRaised $event): void
         }
 
         if (1 === preg_match($this->pattern, $userAgent)) {
+            $this->logger->debug('The event {event_name} ({event_id}) was dropped because the user agent matches the configured filters: {user_agent}', [
+                'event_name' => $event->event->eventName,
+                'event_id' => $event->event->eventId,
+                'user_agent' => $userAgent,
+            ]);
+
             $event->stopPropagation();
         }
     }

src/EventSubscriber/FilterEmptyUserAgentSubscriber.php

@@ -4,12 +4,21 @@
 
 namespace Setono\MetaConversionsApiBundle\EventSubscriber;
 
+use Psr\Log\LoggerInterface;
+use Psr\Log\NullLogger;
 use Setono\MetaConversionsApi\Event\Event;
 use Setono\MetaConversionsApiBundle\Event\ConversionsApiEventRaised;
 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 
 final class FilterEmptyUserAgentSubscriber implements EventSubscriberInterface
 {
+    private readonly LoggerInterface $logger;
+
+    public function __construct(?LoggerInterface $logger = null)
+    {
+        $this->logger = $logger ?? new NullLogger();
+    }
+
     public static function getSubscribedEvents(): array
     {
         return [
@@ -28,6 +37,11 @@ public function filter(ConversionsApiEventRaised $event): void
 
         $userAgent = $event->event->userData->clientUserAgent;
         if (null === $userAgent || '' === $userAgent) {
+            $this->logger->debug('The event {event_name} ({event_id}) was dropped because the request has no user agent', [
+                'event_name' => $event->event->eventName,
+                'event_id' => $event->event->eventId,
+            ]);
+
             $event->stopPropagation();
         }
     }

src/EventSubscriber/StopPropagationIfNoPixelsHasBeenAddedSubscriber.php

@@ -4,11 +4,20 @@
 
 namespace Setono\MetaConversionsApiBundle\EventSubscriber;
 
+use Psr\Log\LoggerInterface;
+use Psr\Log\NullLogger;
 use Setono\MetaConversionsApiBundle\Event\ConversionsApiEventRaised;
 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 
 final class StopPropagationIfNoPixelsHasBeenAddedSubscriber implements EventSubscriberInterface
 {
+    private readonly LoggerInterface $logger;
+
+    public function __construct(?LoggerInterface $logger = null)
+    {
+        $this->logger = $logger ?? new NullLogger();
+    }
+
     public static function getSubscribedEvents(): array
     {
         return [
@@ -19,6 +28,11 @@ public static function getSubscribedEvents(): array
     public function filter(ConversionsApiEventRaised $event): void
     {
         if ([] === $event->event->pixels) {
+            $this->logger->debug('The event {event_name} ({event_id}) was dropped because no pixels are associated with it. Did you configure any?', [
+                'event_name' => $event->event->eventName,
+                'event_id' => $event->event->eventId,
+            ]);
+
             $event->stopPropagation();
         }
     }

src/Resources/config/services/conditional/client_side.xml

@@ -7,17 +7,21 @@
             <argument type="service" id="setono_tag_bag.tag_bag"/>
             <argument type="service" id="Setono\MetaConversionsApi\Generator\FbqGeneratorInterface"/>
             <argument type="service" id="Setono\MetaConversionsApiBundle\ConsentChecker\ConsentCheckerInterface"/>
+            <argument type="service" id="logger" on-invalid="null"/>
 
             <tag name="kernel.event_subscriber"/>
+            <tag name="monolog.logger" channel="setono_meta_conversions_api"/>
         </service>
 
         <service id="Setono\MetaConversionsApiBundle\EventSubscriber\AddLibraryToTagBagSubscriber">
             <argument type="service" id="setono_tag_bag.tag_bag"/>
             <argument type="service" id="Setono\MetaConversionsApi\Generator\FbqGeneratorInterface"/>
-            <argument type="service" id="Setono\MetaConversionsApiBundle\ConsentChecker\ConsentCheckerInterface" on-invalid="null"/>
+            <argument type="service" id="Setono\MetaConversionsApiBundle\ConsentChecker\ConsentCheckerInterface"/>
             <argument type="service" id="Setono\MetaConversionsApiBundle\Provider\PixelProviderInterface"/>
+            <argument type="service" id="logger" on-invalid="null"/>
 
             <tag name="kernel.event_subscriber"/>
+            <tag name="monolog.logger" channel="setono_meta_conversions_api"/>
         </service>
     </services>
 </container>

src/Resources/config/services/conditional/server_side.xml

@@ -6,8 +6,10 @@
         <service id="Setono\MetaConversionsApiBundle\EventSubscriber\DispatchOnCommandBusSubscriber">
             <argument type="service" id="setono_meta_conversions_api.message_bus"/>
             <argument type="service" id="Setono\MetaConversionsApiBundle\ConsentChecker\ConsentCheckerInterface"/>
+            <argument type="service" id="logger" on-invalid="null"/>
 
             <tag name="kernel.event_subscriber"/>
+            <tag name="monolog.logger" channel="setono_meta_conversions_api"/>
         </service>
 
         <service id="Setono\MetaConversionsApiBundle\Message\Handler\SendEventHandler">

src/Resources/config/services/event_subscriber.xml

@@ -5,18 +5,25 @@
     <services>
         <service id="Setono\MetaConversionsApiBundle\EventSubscriber\FilterBotsSubscriber">
             <argument type="service" id="setono_bot_detection.bot_detector.default"/>
+            <argument type="service" id="logger" on-invalid="null"/>
 
             <tag name="kernel.event_subscriber"/>
+            <tag name="monolog.logger" channel="setono_meta_conversions_api"/>
         </service>
 
         <service id="Setono\MetaConversionsApiBundle\EventSubscriber\FilterConfiguredUserAgentsSubscriber">
             <argument>%setono_meta_conversions_api.filters.user_agent%</argument>
+            <argument type="service" id="logger" on-invalid="null"/>
 
             <tag name="kernel.event_subscriber"/>
+            <tag name="monolog.logger" channel="setono_meta_conversions_api"/>
         </service>
 
         <service id="Setono\MetaConversionsApiBundle\EventSubscriber\FilterEmptyUserAgentSubscriber">
+            <argument type="service" id="logger" on-invalid="null"/>
+
             <tag name="kernel.event_subscriber"/>
+            <tag name="monolog.logger" channel="setono_meta_conversions_api"/>
         </service>
 
         <service id="Setono\MetaConversionsApiBundle\EventSubscriber\PopulateFbpAndFbcPropertiesSubscriber">
@@ -47,7 +54,10 @@
         </service>
 
         <service id="Setono\MetaConversionsApiBundle\EventSubscriber\StopPropagationIfNoPixelsHasBeenAddedSubscriber">
+            <argument type="service" id="logger" on-invalid="null"/>
+
             <tag name="kernel.event_subscriber"/>
+            <tag name="monolog.logger" channel="setono_meta_conversions_api"/>
         </service>
 
         <service id="Setono\MetaConversionsApiBundle\EventSubscriber\StoreFbcSubscriber">