Bake pause/resume into SpansRecorder with a depth counter

The PausableRecorder trait could only handle a single ignored event with
nothing nested under it. Anything trickier (a normal recordStart/recordEnd
under a pause, or a second ignored event) silently desynced the resume.

Pause/resume is now a feature of SpansRecorder itself. Static $pauseOwner and
$pauseDepth track ownership and call depth across the recorder hierarchy.
startSpan and endSpan carry the counter math: increments while owner-paused
do not produce real spans, and resume fires the moment depth returns to zero.
Lifecycle::flush() clears the static state at every subtask/request boundary
so long-running runtimes cannot leak pause state across executions.

Author: rubenvanassche

src/Concerns/Recorders/PausableRecorder.php

@@ -4,7 +4,6 @@
 
 use Spatie\FlareClient\AttributesProviders\PhpCommandAttributesProvider;
 use Spatie\FlareClient\AttributesProviders\SymfonyInputCommandAttributesProvider;
-use Spatie\FlareClient\Concerns\Recorders\PausableRecorder;
 use Spatie\FlareClient\Contracts\CommandAttributesProvider;
 use Spatie\FlareClient\Contracts\EntryPointHandlerProvider;
 use Spatie\FlareClient\EntryPoint\EntryPointResolver;
@@ -19,8 +18,6 @@
 
 class CommandRecorder extends SpansRecorder
 {
-    use PausableRecorder;
-
     /** @var array<int, string> */
     protected array $ignoredCommands = [];
 
@@ -152,12 +149,6 @@ public function recordEnd(
         int $exitCode = 0,
         array $attributes = []
     ): ?Span {
-        if ($this->pausedTrace()) {
-            $this->resumeTrace();
-
-            return null;
-        }
-
         return $this->endSpan(additionalAttributes: [
             'process.exit_code' => $exitCode,
             ...$attributes,

src/Recorders/CommandRecorder/CommandRecorder.php

@@ -3,7 +3,6 @@
 namespace Spatie\FlareClient\Recorders\JobRecorder;
 
 use Spatie\FlareClient\AttributesProviders\PhpJobAttributesProvider;
-use Spatie\FlareClient\Concerns\Recorders\PausableRecorder;
 use Spatie\FlareClient\Contracts\EntryPointHandlerProvider;
 use Spatie\FlareClient\Contracts\JobAttributesProvider;
 use Spatie\FlareClient\EntryPoint\EntryPoint;
@@ -25,8 +24,6 @@
 
 class JobRecorder extends SpansRecorder
 {
-    use PausableRecorder;
-
     /** @var array<int, string> */
     protected array $ignoredClasses = [];
 
@@ -125,12 +122,6 @@ public function recordStartFromJob(
 
     public function recordEnd(array $attributes = []): ?Span
     {
-        if ($this->pausedTrace()) {
-            $this->resumeTrace();
-
-            return null;
-        }
-
         $span = $this->endSpan(
             additionalAttributes: $attributes,
             includeMemoryUsage: true,
@@ -147,12 +138,6 @@ public function recordFailed(
         Throwable $exception,
         array $attributes = [],
     ): ?Span {
-        if ($this->pausedTrace()) {
-            $this->resumeTrace();
-
-            return null;
-        }
-
         $throwableClass = $exception::class;
 
         $trackingUuid = $this->tracer->ids->uuid();

src/Recorders/JobRecorder/JobRecorder.php

@@ -3,7 +3,6 @@
 namespace Spatie\FlareClient\Recorders\QueueRecorder;
 
 use Spatie\FlareClient\AttributesProviders\PhpJobAttributesProvider;
-use Spatie\FlareClient\Concerns\Recorders\PausableRecorder;
 use Spatie\FlareClient\Contracts\JobAttributesProvider;
 use Spatie\FlareClient\Enums\RecorderType;
 use Spatie\FlareClient\Enums\SpanType;
@@ -15,8 +14,6 @@
 
 class QueueRecorder extends SpansRecorder
 {
-    use PausableRecorder;
-
     /** @var array<int, string> */
     protected array $ignoredClasses = [];
 
@@ -74,12 +71,6 @@ public function recordStartFromQueuedJob(
 
     public function recordEnd(array $attributes = []): ?Span
     {
-        if ($this->pausedTrace()) {
-            $this->resumeTrace();
-
-            return null;
-        }
-
         return $this->endSpan(additionalAttributes: $attributes);
     }
 

src/Recorders/QueueRecorder/QueueRecorder.php

@@ -25,6 +25,10 @@ abstract class SpansRecorder extends Recorder implements SpansRecorderContract
     /** @var array<Span> */
     protected array $stack = [];
 
+    protected static ?SpansRecorder $pauseOwner = null;
+
+    protected static int $pauseDepth = 0;
+
     public function __construct(
         protected Tracer $tracer,
         protected BackTracer $backTracer,
@@ -69,6 +73,12 @@ final protected function startSpan(
             throw new InvalidArgumentException('Either $nameAndAttributes must be set, or both $name and $attributes must be set.');
         }
 
+        if (self::$pauseOwner === $this) {
+            self::$pauseDepth++;
+
+            return null;
+        }
+
         $shouldTrace = $this->withTraces && $this->tracer->sampling;
         $shouldReport = $this->shouldReport();
 
@@ -120,6 +130,10 @@ final protected function endSpan(
         ?Closure $spanCallback = null,
         bool $includeMemoryUsage = false,
     ): ?Span {
+        if ($this->consumePauseEnd()) {
+            return null;
+        }
+
         $span = array_pop($this->stack);
 
         if ($span === null) {
@@ -183,17 +197,17 @@ final protected function span(
             time: $start,
         );
 
-        if ($span === null) {
-            return null;
-        }
-
         $this->endSpan(
             time: $end,
             additionalAttributes: $additionalAttributes === null ? [] : $additionalAttributes,
             spanCallback: $spanCallback,
             includeMemoryUsage: $includeMemoryUsage,
         );
 
+        if ($span === null) {
+            return null;
+        }
+
         if ($this->withTraces && $this->tracer->sampling === true) {
             $this->backtraceEntry($span);
         }
@@ -205,4 +219,47 @@ final public function getSpans(): array
     {
         return $this->entries;
     }
+
+    public static function resetPauseState(): void
+    {
+        self::$pauseOwner = null;
+        self::$pauseDepth = 0;
+    }
+
+    protected function pauseTrace(): void
+    {
+        if (self::$pauseOwner === $this) {
+            self::$pauseDepth++;
+
+            return;
+        }
+
+        if (self::$pauseOwner !== null) {
+            return;
+        }
+
+        self::$pauseOwner = $this;
+        self::$pauseDepth = 1;
+
+        $this->tracer->pauseSampling();
+    }
+
+    private function consumePauseEnd(): bool
+    {
+        if (self::$pauseOwner !== $this) {
+            return false;
+        }
+
+        self::$pauseDepth--;
+
+        if (self::$pauseDepth > 0) {
+            return true;
+        }
+
+        self::$pauseOwner = null;
+
+        $this->tracer->resumeSampling();
+
+        return true;
+    }
 }

src/Recorders/SpansRecorder.php

@@ -10,6 +10,7 @@
 use Spatie\FlareClient\Enums\SpanType;
 use Spatie\FlareClient\Logger;
 use Spatie\FlareClient\Memory\Memory;
+use Spatie\FlareClient\Recorders\SpansRecorder;
 use Spatie\FlareClient\Resources\Resource;
 use Spatie\FlareClient\Spans\Span;
 use Spatie\FlareClient\Time\Time;
@@ -391,6 +392,8 @@ public function flush(): void
         $this->sentReports->clear();
         $this->recorders->reset();
 
+        SpansRecorder::resetPauseState();
+
         $this->applicationSpan = null;
         $this->registeringSpan = null;
         $this->bootingSpan = null;

src/Support/Lifecycle.php

@@ -5,6 +5,7 @@
 use Spatie\FlareClient\Flare;
 use Spatie\FlareClient\FlareConfig;
 use Spatie\FlareClient\FlareProvider;
+use Spatie\FlareClient\Recorders\SpansRecorder;
 use Spatie\FlareClient\Support\Container;
 use Spatie\FlareClient\Tests\Shared\FakeApi;
 use Spatie\FlareClient\Tests\Shared\FakeIds;
@@ -21,6 +22,7 @@
     FakeIds::reset();
     FakeMemory::reset();
     FakeSampler::reset();
+    SpansRecorder::resetPauseState();
 })->in(__DIR__);
 
 function makePathsRelative(string $text): string