Improve storage integration

CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## Unreleased
+
+### Features
+
+- The filesystem adapters for the `sentry` driver now extend the well-known Laravel classes they decorate,
+  `Illuminate\Filesystem\FilesystemAdapter` and `Illuminate\Filesystem\AwsS3V3Adapter`.
+
+  Enabling the feature can be simplified by wrapping the configuration for all disks
+  with a call to `Sentry\Laravel\Features\Storage\Integration::configureDisks()`
+  in your `config/filesystems.php` file:
+
+  ```php
+  'disks' => Sentry\Laravel\Features\Storage\Integration::configureDisks([
+      'local' => [
+          'driver' => 'local',
+          'root' => storage_path('app'),
+          'throw' => false,
+      ],
+
+      // ...
+  ], /* enableSpans: */ true, /* enableBreadcrumbs: */ true),
+  ```
+
+  Alternatively, you can enable this feature only for select disks:
+
+  ```php
+  'disks' => [
+      'local' => [
+          'driver' => 'local',
+          'root' => storage_path('app'),
+          'throw' => false,
+      ],
+
+      's3' => Sentry\Laravel\Features\Storage\Integration::configureDisk('s3', [
+          // ...
+      ], /* enableSpans: */ true, /* enableBreadcrumbs: */ true),
+  ],
+  ```
+
+  By default, both spans and breadcrumbs are enabled.
+  You may disable them by passing the second argument `$enableSpans` or the third argument `$enableBreadcrumbs`.
+
 ## 3.7.3
 
 The Sentry SDK team is happy to announce the immediate availability of Sentry Laravel SDK v3.7.3.

src/Sentry/Laravel/Features/Storage/CloudFilesystemDecorator.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace Sentry\Laravel\Features\Storage;
+
+trait CloudFilesystemDecorator
+{
+    use FilesystemDecorator;
+
+    public function url($path)
+    {
+        return $this->withSentry(__FUNCTION__, func_get_args(), $path, compact('path'));
+    }
+}

src/Sentry/Laravel/Features/Storage/FilesystemAdapterDecorator.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace Sentry\Laravel\Features\Storage;
+
+trait FilesystemAdapterDecorator
+{
+    use CloudFilesystemDecorator;
+
+    public function assertExists($path, $content = null)
+    {
+        return $this->withSentry(__FUNCTION__, func_get_args(), $path, compact('path'));
+    }
+
+    public function assertMissing($path)
+    {
+        return $this->withSentry(__FUNCTION__, func_get_args(), $path, compact('path'));
+    }
+
+    public function assertDirectoryEmpty($path)
+    {
+        return $this->withSentry(__FUNCTION__, func_get_args(), $path, compact('path'));
+    }
+
+    public function temporaryUrl($path, $expiration, array $options = [])
+    {
+        return $this->withSentry(__FUNCTION__, func_get_args(), $path, compact('path', 'expiration', 'options'));
+    }
+
+    public function temporaryUploadUrl($path, $expiration, array $options = [])
+    {
+        return $this->withSentry(__FUNCTION__, func_get_args(), $path, compact('path', 'expiration', 'options'));
+    }
+}

src/Sentry/Laravel/Features/Storage/FilesystemDecorator.php

@@ -0,0 +1,188 @@
+<?php
+
+namespace Sentry\Laravel\Features\Storage;
+
+use Illuminate\Contracts\Filesystem\Filesystem;
+use Sentry\Breadcrumb;
+use Sentry\Laravel\Integration;
+use Sentry\Laravel\Util\Filesize;
+use Sentry\Tracing\SpanContext;
+use function Sentry\trace;
+
+/**
+ * Decorates the underlying filesystem by wrapping all calls to it with tracing.
+ *
+ * Parameters such as paths, directories or options are attached to the span as data,
+ * parameters that contain file contents are omitted due to potential problems with
+ * payload size or sensitive data.
+ */
+trait FilesystemDecorator
+{
+    /** @var Filesystem */
+    protected $filesystem;
+
+    /** @var array */
+    protected $defaultData;
+
+    /** @var bool */
+    protected $recordSpans;
+
+    /** @var bool */
+    protected $recordBreadcrumbs;
+
+    /**
+     * Execute the method on the underlying filesystem and wrap it with tracing and log a breadcrumb.
+     *
+     * @param list<mixed> $args
+     * @param array<string, mixed> $data
+     *
+     * @return mixed
+     */
+    protected function withSentry(string $method, array $args, ?string $description, array $data)
+    {
+        $op = "file.{$method}"; // See https://develop.sentry.dev/sdk/performance/span-operations/#web-server
+        $data = array_merge($data, $this->defaultData);
+
+        if ($this->recordBreadcrumbs) {
+            Integration::addBreadcrumb(new Breadcrumb(
+                Breadcrumb::LEVEL_INFO,
+                Breadcrumb::TYPE_DEFAULT,
+                $op,
+                $description,
+                $data
+            ));
+        }
+
+        if ($this->recordSpans) {
+            $spanContext = new SpanContext;
+            $spanContext->setOp($op);
+            $spanContext->setData($data);
+            $spanContext->setDescription($description);
+
+            return trace(function () use ($method, $args) {
+                return $this->filesystem->{$method}(...$args);
+            }, $spanContext);
+        }
+
+        return $this->filesystem->{$method}(...$args);
+    }
+
+    public function exists($path)
+    {
+        return $this->withSentry(__FUNCTION__, func_get_args(), $path, compact('path'));
+    }
+
+    public function get($path)
+    {
+        return $this->withSentry(__FUNCTION__, func_get_args(), $path, compact('path'));
+    }
+
+    public function readStream($path)
+    {
+        return $this->withSentry(__FUNCTION__, func_get_args(), $path, compact('path'));
+    }
+
+    public function put($path, $contents, $options = [])
+    {
+        $description = is_string($contents) ? sprintf('%s (%s)', $path, Filesize::toHuman(strlen($contents))) : $path;
+
+        return $this->withSentry(__FUNCTION__, func_get_args(), $description, compact('path', 'options'));
+    }
+
+    public function writeStream($path, $resource, array $options = [])
+    {
+        return $this->withSentry(__FUNCTION__, func_get_args(), $path, compact('path', 'options'));
+    }
+
+    public function getVisibility($path)
+    {
+        return $this->withSentry(__FUNCTION__, func_get_args(), $path, compact('path'));
+    }
+
+    public function setVisibility($path, $visibility)
+    {
+        return $this->withSentry(__FUNCTION__, func_get_args(), $path, compact('path', 'visibility'));
+    }
+
+    public function prepend($path, $data, $separator = PHP_EOL)
+    {
+        $description = is_string($data) ? sprintf('%s (%s)', $path, Filesize::toHuman(strlen($data))) : $path;
+
+        return $this->withSentry(__FUNCTION__, func_get_args(), $description, compact('path'));
+    }
+
+    public function append($path, $data, $separator = PHP_EOL)
+    {
+        $description = is_string($data) ? sprintf('%s (%s)', $path, Filesize::toHuman(strlen($data))) : $path;
+
+        return $this->withSentry(__FUNCTION__, func_get_args(), $description, compact('path'));
+    }
+
+    public function delete($paths)
+    {
+        if (is_array($paths)) {
+            $data = compact('paths');
+            $description = sprintf('%s paths', count($paths));
+        } else {
+            $data = ['path' => $paths];
+            $description = $paths;
+        }
+
+        return $this->withSentry(__FUNCTION__, func_get_args(), $description, $data);
+    }
+
+    public function copy($from, $to)
+    {
+        return $this->withSentry(__FUNCTION__, func_get_args(), sprintf('from "%s" to "%s"', $from, $to), compact('from', 'to'));
+    }
+
+    public function move($from, $to)
+    {
+        return $this->withSentry(__FUNCTION__, func_get_args(), sprintf('from "%s" to "%s"', $from, $to), compact('from', 'to'));
+    }
+
+    public function size($path)
+    {
+        return $this->withSentry(__FUNCTION__, func_get_args(), $path, compact('path'));
+    }
+
+    public function lastModified($path)
+    {
+        return $this->withSentry(__FUNCTION__, func_get_args(), $path, compact('path'));
+    }
+
+    public function files($directory = null, $recursive = false)
+    {
+        return $this->withSentry(__FUNCTION__, func_get_args(), $directory, compact('directory', 'recursive'));
+    }
+
+    public function allFiles($directory = null)
+    {
+        return $this->withSentry(__FUNCTION__, func_get_args(), $directory, compact('directory'));
+    }
+
+    public function directories($directory = null, $recursive = false)
+    {
+        return $this->withSentry(__FUNCTION__, func_get_args(), $directory, compact('directory', 'recursive'));
+    }
+
+    public function allDirectories($directory = null)
+    {
+        return $this->withSentry(__FUNCTION__, func_get_args(), $directory, compact('directory'));
+    }
+
+    public function makeDirectory($path)
+    {
+        return $this->withSentry(__FUNCTION__, func_get_args(), $path, compact('path'));
+    }
+
+    public function deleteDirectory($directory)
+    {
+        return $this->withSentry(__FUNCTION__, func_get_args(), $directory, compact('directory'));
+    }
+
+    public function __call($name, $arguments)
+    {
+        return $this->filesystem->{$name}(...$arguments);
+    }
+}

src/Sentry/Laravel/Features/Storage/Integration.php

@@ -5,6 +5,8 @@
 use Illuminate\Contracts\Filesystem\Cloud as CloudFilesystem;
 use Illuminate\Contracts\Filesystem\Filesystem;
 use Illuminate\Contracts\Foundation\Application;
+use Illuminate\Filesystem\AwsS3V3Adapter;
+use Illuminate\Filesystem\FilesystemAdapter;
 use Illuminate\Filesystem\FilesystemManager;
 use RuntimeException;
 use Sentry\Laravel\Features\Feature;
@@ -22,11 +24,6 @@ public function isApplicable(): bool
     }
 
     public function register(): void
-    {
-        $this->registerDiskDriver();
-    }
-
-    private function registerDiskDriver(): void
     {
         $this->container()->afterResolving(FilesystemManager::class, function (FilesystemManager $filesystemManager): void {
             $filesystemManager->extend(
@@ -57,18 +54,81 @@ function (Application $application, array $config) use ($filesystemManager): Fil
                         return $this->resolve($disk);
                     })->bindTo($filesystemManager, FilesystemManager::class);
 
+                    /** @var Filesystem $originalFilesystem */
                     $originalFilesystem = $diskResolver($disk, $config);
 
                     $defaultData = ['disk' => $disk, 'driver' => $config['driver']];
 
                     $recordSpans = $config['sentry_enable_spans'] ?? $this->isTracingFeatureEnabled(self::FEATURE_KEY);
                     $recordBreadcrumbs = $config['sentry_enable_breadcrumbs'] ?? $this->isBreadcrumbFeatureEnabled(self::FEATURE_KEY);
 
-                    return $originalFilesystem instanceof CloudFilesystem
-                        ? new SentryCloudFilesystem($originalFilesystem, $defaultData, $recordSpans, $recordBreadcrumbs)
-                        : new SentryFilesystem($originalFilesystem, $defaultData, $recordSpans, $recordBreadcrumbs);
+                    if ($originalFilesystem instanceof AwsS3V3Adapter) {
+                        return new SentryS3V3Adapter($originalFilesystem, $defaultData, $recordSpans, $recordBreadcrumbs);
+                    }
+
+                    if ($originalFilesystem instanceof FilesystemAdapter) {
+                        return new SentryFilesystemAdapter($originalFilesystem, $defaultData, $recordSpans, $recordBreadcrumbs);
+                    }
+
+                    if ($originalFilesystem instanceof CloudFilesystem) {
+                        return new SentryCloudFilesystem($originalFilesystem, $defaultData, $recordSpans, $recordBreadcrumbs);
+                    }
+
+                    return new SentryFilesystem($originalFilesystem, $defaultData, $recordSpans, $recordBreadcrumbs);
                 }
             );
         });
     }
+
+    /**
+     * Decorates the configuration for a single disk with Sentry driver configuration.
+
+     * This replaces the driver with a custom driver that will capture performance traces and breadcrumbs.
+     *
+     * The custom driver will be an instance of @see \Sentry\Laravel\Features\Storage\SentryS3V3Adapter
+     * if the original driver is an @see \Illuminate\Filesystem\AwsS3V3Adapter,
+     * and an instance of @see \Sentry\Laravel\Features\Storage\SentryFilesystemAdapter
+     * if the original driver is an @see \Illuminate\Filesystem\FilesystemAdapter.
+     * If the original driver is neither of those, it will be @see \Sentry\Laravel\Features\Storage\SentryFilesystem
+     * or @see \Sentry\Laravel\Features\Storage\SentryCloudFilesystem based on the contract of the original driver.
+     *
+     * You might run into problems if you expect another specific driver class.
+     *
+     * @param array<string, mixed> $diskConfig
+     *
+     * @return array<string, mixed>
+     */
+    public static function configureDisk(string $diskName, array $diskConfig, bool $enableSpans = true, bool $enableBreadcrumbs = true): array
+    {
+        $currentDriver = $diskConfig['driver'];
+
+        if ($currentDriver !== self::STORAGE_DRIVER_NAME) {
+            $diskConfig['driver'] = self::STORAGE_DRIVER_NAME;
+            $diskConfig['sentry_disk_name'] = $diskName;
+            $diskConfig['sentry_original_driver'] = $currentDriver;
+            $diskConfig['sentry_enable_spans'] = $enableSpans;
+            $diskConfig['sentry_enable_breadcrumbs'] = $enableBreadcrumbs;
+        }
+
+        return $diskConfig;
+    }
+
+    /**
+     * Decorates the configuration for all disks with Sentry driver configuration.
+     *
+     * @see self::configureDisk()
+     *
+     * @param array<string, array<string, mixed>> $diskConfigs
+     *
+     * @return array<string, array<string, mixed>>
+     */
+    public static function configureDisks(array $diskConfigs, bool $enableSpans = true, bool $enableBreadcrumbs = true): array
+    {
+        $diskConfigsWithSentryDriver = [];
+        foreach ($diskConfigs as $diskName => $diskConfig) {
+            $diskConfigsWithSentryDriver[$diskName] = static::configureDisk($diskName, $diskConfig, $enableSpans, $enableBreadcrumbs);
+        }
+
+        return $diskConfigsWithSentryDriver;
+    }
 }