Split sampling rules into typed subclasses

composer.json

@@ -61,7 +61,7 @@
     "minimum-stability": "dev",
     "extra": {
         "branch-alias": {
-            "dev-main": "1.3.x-dev"
+            "dev-main": "3.x-dev"
         }
     }
 }

phpstan-baseline.neon

@@ -95,11 +95,6 @@ parameters:
 			count: 1
 			path: src/Recorders/SpanEventsRecorder.php
 
-		-
-			message: "#^Unsafe usage of new static\\(\\)\\.$#"
-			count: 8
-			path: src/Sampling/SamplingRule.php
-
 		-
 			message: "#^Instanceof between \\*NEVER\\* and Spatie\\\\FlareClient\\\\Spans\\\\SpanEvent will always evaluate to false\\.$#"
 			count: 1

src/AttributesProviders/PhpCommandAttributesProvider.php

@@ -30,4 +30,19 @@ public function commandClass(): ?string
     {
         return $this->commandClass;
     }
+
+    public function entryPointHandlerIdentifier(): ?string
+    {
+        return $this->command;
+    }
+
+    public function entryPointHandlerName(): ?string
+    {
+        return $this->commandClass;
+    }
+
+    public function entryPointHandlerType(): ?string
+    {
+        return 'php_command';
+    }
 }

src/AttributesProviders/PhpJobAttributesProvider.php

@@ -26,4 +26,19 @@ public function jobClass(): ?string
     {
         return $this->jobClass;
     }
+
+    public function entryPointHandlerIdentifier(): ?string
+    {
+        return $this->jobName;
+    }
+
+    public function entryPointHandlerName(): ?string
+    {
+        return $this->jobClass;
+    }
+
+    public function entryPointHandlerType(): ?string
+    {
+        return 'php_job';
+    }
 }

src/AttributesProviders/SymfonyInputCommandAttributesProvider.php

@@ -3,10 +3,9 @@
 namespace Spatie\FlareClient\AttributesProviders;
 
 use Spatie\FlareClient\Contracts\CommandAttributesProvider;
-use Spatie\FlareClient\Contracts\EntryPointHandlerProvider;
 use Symfony\Component\Console\Input\InputInterface;
 
-class SymfonyInputCommandAttributesProvider implements CommandAttributesProvider, EntryPointHandlerProvider
+class SymfonyInputCommandAttributesProvider implements CommandAttributesProvider
 {
     public function __construct(
         protected InputInterface $input,

src/Contracts/CommandAttributesProvider.php

@@ -2,7 +2,7 @@
 
 namespace Spatie\FlareClient\Contracts;
 
-interface CommandAttributesProvider extends AttributesProvider
+interface CommandAttributesProvider extends AttributesProvider, EntryPointHandlerProvider
 {
     public function command(): string;
 

src/Contracts/JobAttributesProvider.php

@@ -2,9 +2,6 @@
 
 namespace Spatie\FlareClient\Contracts;
 
-interface JobAttributesProvider extends AttributesProvider
+interface JobAttributesProvider extends QueuedJobAttributesProvider, EntryPointHandlerProvider
 {
-    public function jobName(): string;
-
-    public function jobClass(): ?string;
 }

src/Contracts/QueuedJobAttributesProvider.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Spatie\FlareClient\Contracts;
+
+interface QueuedJobAttributesProvider extends AttributesProvider
+{
+    public function jobName(): string;
+
+    public function jobClass(): ?string;
+}

src/Contracts/SamplingAttributesProvider.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Spatie\FlareClient\Contracts;
+
+/**
+ * Implemented by attribute providers (route, command, job, ...) that want to
+ * expose a small map of attributes for sampling rules to match against,
+ * separately from the full attribute payload produced by toArray(). Keep the
+ * returned values cheap to compute — this runs on every entry-point handler
+ * resolution, including for traces that may still get dropped.
+ */
+interface SamplingAttributesProvider
+{
+    /** @return array<string, mixed> */
+    public function samplingAttributes(): array;
+}

src/EntryPoint/EntryPoint.php

@@ -2,6 +2,9 @@
 
 namespace Spatie\FlareClient\EntryPoint;
 
+use Spatie\FlareClient\Contracts\AttributesProvider;
+use Spatie\FlareClient\Contracts\EntryPointHandlerProvider;
+use Spatie\FlareClient\Contracts\SamplingAttributesProvider;
 use Spatie\FlareClient\Enums\EntryPointType;
 
 class EntryPoint
@@ -14,6 +17,9 @@ class EntryPoint
 
     public ?string $handlerType;
 
+    /** @var array<string, mixed> */
+    public array $samplingAttributes = [];
+
     public function __construct(
         public EntryPointType $type,
         public string $value,
@@ -25,17 +31,33 @@ public function updateValue(string $value): void
         $this->value = $value;
     }
 
+    /** @param array<string, mixed> $samplingAttributes */
     public function setHandler(
         string $handlerIdentifier,
         ?string $handlerName,
         ?string $handlerType,
+        array $samplingAttributes = [],
     ): void {
         $this->handlerIdentifier = $handlerIdentifier;
         $this->handlerName = $handlerName;
         $this->handlerType = $handlerType;
+        $this->samplingAttributes = $samplingAttributes;
         $this->handlerResolved = true;
     }
 
+    public function setHandlerFromAttributesProvider(
+        AttributesProvider&EntryPointHandlerProvider $provider,
+    ): void {
+        $this->setHandler(
+            handlerIdentifier: $provider->entryPointHandlerIdentifier() ?? 'unknown',
+            handlerName: $provider->entryPointHandlerName(),
+            handlerType: $provider->entryPointHandlerType() ?? 'unknown',
+            samplingAttributes: $provider instanceof SamplingAttributesProvider
+                ? $provider->samplingAttributes()
+                : [],
+        );
+    }
+
     /** @return array<string, string|null> */
     public function toAttributes(): array
     {

src/Recorders/CommandRecorder/CommandRecorder.php

@@ -5,7 +5,6 @@
 use Spatie\FlareClient\AttributesProviders\PhpCommandAttributesProvider;
 use Spatie\FlareClient\AttributesProviders\SymfonyInputCommandAttributesProvider;
 use Spatie\FlareClient\Contracts\CommandAttributesProvider;
-use Spatie\FlareClient\Contracts\EntryPointHandlerProvider;
 use Spatie\FlareClient\EntryPoint\EntryPointResolver;
 use Spatie\FlareClient\Enums\RecorderType;
 use Spatie\FlareClient\Enums\SpanType;
@@ -54,15 +53,7 @@ public function recordStart(
         $entryPoint = $this->entryPointResolver->get();
 
         if (! $entryPoint->handlerResolved) {
-            $entryPointProvider = $commandAttributesProvider instanceof EntryPointHandlerProvider
-                ? $commandAttributesProvider
-                : null;
-
-            $entryPoint->setHandler(
-                handlerIdentifier: $entryPointProvider?->entryPointHandlerIdentifier() ?? $command,
-                handlerName: $entryPointProvider?->entryPointHandlerName() ?? $commandClass,
-                handlerType: $entryPointProvider?->entryPointHandlerType() ?? 'php_command',
-            );
+            $entryPoint->setHandlerFromAttributesProvider($commandAttributesProvider);
         }
 
         $this->tracer->reevaluateSampling();

src/Recorders/JobRecorder/JobRecorder.php

@@ -3,7 +3,6 @@
 namespace Spatie\FlareClient\Recorders\JobRecorder;
 
 use Spatie\FlareClient\AttributesProviders\PhpJobAttributesProvider;
-use Spatie\FlareClient\Contracts\EntryPointHandlerProvider;
 use Spatie\FlareClient\Contracts\JobAttributesProvider;
 use Spatie\FlareClient\EntryPoint\EntryPoint;
 use Spatie\FlareClient\EntryPoint\EntryPointResolver;
@@ -82,13 +81,7 @@ public function recordStart(
             value: $jobClass ?? $jobName,
         );
 
-        $entryPointProvider = $jobAttributesProvider instanceof EntryPointHandlerProvider ? $jobAttributesProvider : null;
-
-        $entryPoint->setHandler(
-            handlerIdentifier: $entryPointProvider?->entryPointHandlerIdentifier() ?? $jobName,
-            handlerName: $entryPointProvider?->entryPointHandlerName() ?? $jobClass,
-            handlerType: $entryPointProvider?->entryPointHandlerType() ?? 'php_job',
-        );
+        $entryPoint->setHandlerFromAttributesProvider($jobAttributesProvider);
 
         if ($this->lifecycle->usesSubtasks) {
             $this->entryPointResolver->set($entryPoint);

src/Recorders/QueueRecorder/QueueRecorder.php

@@ -3,7 +3,7 @@
 namespace Spatie\FlareClient\Recorders\QueueRecorder;
 
 use Spatie\FlareClient\AttributesProviders\PhpJobAttributesProvider;
-use Spatie\FlareClient\Contracts\JobAttributesProvider;
+use Spatie\FlareClient\Contracts\QueuedJobAttributesProvider;
 use Spatie\FlareClient\Enums\RecorderType;
 use Spatie\FlareClient\Enums\SpanType;
 use Spatie\FlareClient\Recorders\SpansRecorder;
@@ -36,7 +36,7 @@ protected function configure(array $config): void
     }
 
     public function recordStart(
-        JobAttributesProvider $provider,
+        QueuedJobAttributesProvider $provider,
         array $attributes = [],
     ): ?Span {
         $jobName = $provider->jobName();

src/Recorders/RoutingRecorder/RoutingRecorder.php

@@ -143,15 +143,15 @@ public function recordRoutingEnd(
 
         $entryPoint = $this->entryPointResolver->get();
 
-        if (! $entryPoint->handlerResolved) {
-            $entryPointProvider = $routeAttributesProvider instanceof EntryPointHandlerProvider
-                ? $routeAttributesProvider
-                : null;
+        if (! $entryPoint->handlerResolved && $routeAttributesProvider instanceof EntryPointHandlerProvider) {
+            $entryPoint->setHandlerFromAttributesProvider($routeAttributesProvider);
+        }
 
+        if (! $entryPoint->handlerResolved) {
             $entryPoint->setHandler(
-                handlerIdentifier: $entryPointProvider?->entryPointHandlerIdentifier() ?? 'unknown',
-                handlerName: $entryPointProvider?->entryPointHandlerName(),
-                handlerType: $entryPointProvider?->entryPointHandlerType() ?? 'php_request',
+                handlerIdentifier: 'unknown',
+                handlerName: null,
+                handlerType: 'php_request',
             );
         }
 
@@ -167,7 +167,10 @@ public function recordRoutingEnd(
 
         return $this->endSpan(
             time: $time,
-            additionalAttributes: $attributes,
+            additionalAttributes: fn () => [
+                ...$routeAttributesProvider->toArray(),
+                ...$attributes,
+            ],
         );
     }
 

src/Recorders/SpansRecorder.php

@@ -146,6 +146,14 @@ final protected function endSpan(
             $spanCallback($span);
         }
 
+        $shouldTrace = $this->withTraces
+            && $this->tracer->sampling
+            && ! $this->tracer->disabled;
+
+        if (! $shouldTrace && ! $this->shouldReport()) {
+            return $span;
+        }
+
         if (is_callable($additionalAttributes)) {
             $additionalAttributes = $additionalAttributes();
         }
@@ -154,14 +162,10 @@ final protected function endSpan(
             $span->addAttributes($additionalAttributes);
         }
 
-        if ($this->withTraces === false
-            || $this->tracer->sampling === false
-            || $this->tracer->disabled === true) {
-            return $span;
+        if ($shouldTrace) {
+            $this->tracer->endSpan($span, includeMemoryUsage: $includeMemoryUsage);
         }
 
-        $this->tracer->endSpan($span, includeMemoryUsage: $includeMemoryUsage);
-
         return $span;
     }
 

src/Sampling/DeferrableSampler.php

@@ -6,7 +6,7 @@
 
 interface DeferrableSampler extends Sampler
 {
-    public function isPending(): bool;
+    public function isDeferred(): bool;
 
     public function reevaluate(EntryPoint $entryPoint): bool;
 

src/Sampling/DeferredSamplerRule.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace Spatie\FlareClient\Sampling;
+
+interface DeferredSamplerRule
+{
+}