Merge pull request #38 from flownative/task/event-breadcrumbs

Add log entries as breadcrumbs for Sentry events

Author: kdambekalns

Classes/Log/SentryFileBackend.php

@@ -15,14 +15,13 @@
 
 use Flownative\Sentry\SentryClientTrait;
 use Neos\Flow\Log\Backend\FileBackend;
-use Sentry\Severity;
+use Sentry\Breadcrumb;
+use Sentry\SentrySdk;
 
 class SentryFileBackend extends FileBackend
 {
     use SentryClientTrait;
 
-    private bool $capturingMessage = false;
-
     /**
      * Appends the given message along with the additional information into the log.
      *
@@ -36,29 +35,50 @@ class SentryFileBackend extends FileBackend
      */
     public function append(string $message, int $severity = LOG_INFO, $additionalData = null, ?string $packageKey = null, ?string $className = null, ?string $methodName = null): void
     {
-        if ($this->capturingMessage) {
-            return;
+        try {
+            SentrySdk::getCurrentHub()->addBreadcrumb(
+                new Breadcrumb(
+                    $this->getBreadcrumbLevel($severity),
+                    $this->getBreadcrumbType($severity),
+                    basename($this->logFileUrl),
+                    $message,
+                    ($additionalData ?? []) + array_filter([
+                        'packageKey' => $packageKey, 'className' => $className, 'methodName' => $methodName
+                    ]),
+                    time()
+                )
+            );
+        } catch (\Throwable $throwable) {
+            parent::append(
+                sprintf('%s (%s)', $throwable->getMessage(), $throwable->getCode()),
+                LOG_WARNING,
+                null,
+                'Flownative.Sentry',
+                __CLASS__,
+                __METHOD__
+            );
         }
 
-        try {
-            $this->capturingMessage = true;
+        parent::append($message, $severity, $additionalData, $packageKey, $className, $methodName);
+    }
 
-            $sentryClient = self::getSentryClient();
-            if ($severity <= LOG_NOTICE && $sentryClient) {
-                $sentrySeverity = match ($severity) {
-                    LOG_WARNING => Severity::warning(),
-                    LOG_ERR => Severity::error(),
-                    LOG_CRIT, LOG_ALERT, LOG_EMERG => Severity::fatal(),
-                    default => Severity::info(),
-                };
+    private function getBreadcrumbLevel(int $severity): string
+    {
+        return match ($severity) {
+            LOG_EMERG, LOG_ALERT, LOG_CRIT => Breadcrumb::LEVEL_FATAL,
+            LOG_ERR => Breadcrumb::LEVEL_ERROR,
+            LOG_WARNING => Breadcrumb::LEVEL_WARNING,
+            LOG_NOTICE, LOG_INFO => Breadcrumb::LEVEL_INFO,
+            default => Breadcrumb::LEVEL_DEBUG,
+        };
+    }
 
-                $sentryClient->captureMessage($message, $sentrySeverity, ['Additional Data' => $additionalData]);
-            }
-            parent::append($message, $severity, $additionalData, $packageKey, $className, $methodName);
-        } catch (\Throwable $throwable) {
-            echo sprintf('SentryFileBackend: %s (%s)', $throwable->getMessage(), $throwable->getCode());
-        } finally {
-            $this->capturingMessage = false;
+    private function getBreadcrumbType(int $severity): string
+    {
+        if ($severity >= LOG_ERR) {
+            return Breadcrumb::TYPE_ERROR;
         }
+
+        return Breadcrumb::TYPE_DEFAULT;
     }
 }

Configuration/Settings.yaml

@@ -10,8 +10,11 @@ Flownative:
 Neos:
   Flow:
     log:
-      systemLogger:
-        backend: Flownative\Sentry\Log\SentryFileBackend
+      psr3:
+        Neos\Flow\Log\PsrLoggerFactory:
+          systemLogger:
+            default:
+              class: 'Flownative\Sentry\Log\SentryFileBackend'
       throwables:
         storageClass: 'Flownative\Sentry\Log\SentryStorage'
         optionsByImplementation:

README.md

@@ -88,6 +88,45 @@ data" section in Sentry.
 Note that the array must only contain values of simple types, such as
 strings, booleans or integers.
 
+## Logging integration
+
+### Breadcrumb handler
+
+This package configures a logging backend to add messages as breadcrumbs to
+be sent to Sentry when an exception happens. This provides more information
+on what happened before an exception.
+
+If you want to include the security and query logging into this handling,
+feel free to add this to the Flow settings:
+
+```yaml
+Neos:
+  Flow:
+    log:
+      psr3:
+        Neos\Flow\Log\PsrLoggerFactory:
+          securityLogger:
+            default:
+              class: 'Flownative\Sentry\Log\SentryFileBackend'
+          sqlLogger:
+            default:
+              class: 'Flownative\Sentry\Log\SentryFileBackend'
+```
+
+For more information on breadcrumbs see the Sentry documentation at
+https://docs.sentry.io/platforms/php/enriching-events/breadcrumbs/
+
+### Monolog
+
+In case you want to store all log messages in Sentry, one way is to configure
+Flow to use monolog for logging and then add the `Sentry\Monolog\Handler` to
+the setup.
+
+Keep in mind that the breadcrumb handler provided by this package might be
+disabled when doing this, depending on your configuration. Sentry provides
+a monolog integration for that purpose, see `Sentry\Monolog\BreadcrumbHandler`
+and https://docs.sentry.io/platforms/php/integrations/monolog/. 
+
 ## Testing the Client
 
 This package provides a command controller which allows you to log a