feat(sdk): add custom sampler registry support

Add ability to register custom sampler factories via the Registry,
allowing users to extend the SDK with custom sampling strategies.

Implementation:
- Add SamplerFactoryInterface for sampler factory contracts
- Add factory classes for all built-in samplers (AlwaysOn, AlwaysOff,
  TraceIdRatioBased, ParentBased variants)
- Add Registry::registerSamplerFactory() and Registry::samplerFactory()
- Refactor SamplerFactory to use the registry instead of hardcoded logic
- Add _register.php to auto-register built-in sampler factories

Tests:
- Add unit tests for all sampler factory classes
- Add registry tests for sampler factory registration
- Add tests for custom sampler registration with clobber behavior

Author: cedricziel

composer.json

@@ -74,6 +74,7 @@
             "src/SDK/Metrics/MetricExporter/_register.php",
             "src/SDK/Propagation/_register.php",
             "src/SDK/Trace/SpanExporter/_register.php",
+            "src/SDK/Trace/Sampler/_register.php",
             "src/SDK/Common/Dev/Compatibility/_load.php",
             "src/SDK/Common/Util/functions.php",
             "src/SDK/_autoload.php"

phpstan.neon.dist

@@ -62,3 +62,11 @@ parameters:
             message: "#^Caught class .* not found\\.#"
             paths:
                 - src/Config/SDK/Configuration/Environment/Adapter/
+        -
+            message: "#Call to an undefined method Symfony\\\\Component\\\\Config\\\\Definition\\\\Builder\\\\NodeParentInterface::.+\\(\\)#"
+            paths:
+                - src/Config/SDK
+        -
+            message: "#PHPDoc tag @extends contains generic type Symfony\\\\Component\\\\Config\\\\Definition\\\\Builder\\\\.*NodeDefinition<.*> but class .* is not generic#"
+            paths:
+                - src/Config/SDK

src/SDK/Registry.php

@@ -10,6 +10,7 @@
 use OpenTelemetry\SDK\Logs\LogRecordExporterFactoryInterface;
 use OpenTelemetry\SDK\Metrics\MetricExporterFactoryInterface;
 use OpenTelemetry\SDK\Resource\ResourceDetectorInterface;
+use OpenTelemetry\SDK\Trace\Sampler\SamplerFactoryInterface;
 use OpenTelemetry\SDK\Trace\SpanExporter\SpanExporterFactoryInterface;
 use RuntimeException;
 use TypeError;
@@ -28,6 +29,7 @@ class Registry
     private static array $logRecordExporterFactories = [];
     private static array $resourceDetectors = [];
     private static array $responsePropagators = [];
+    private static array $samplerFactories = [];
 
     /**
      * @param TransportFactoryInterface|class-string<TransportFactoryInterface> $factory
@@ -134,6 +136,27 @@ public static function registerResponsePropagator(string $name, ResponsePropagat
         self::$responsePropagators[$name] = $responsePropagator;
     }
 
+    /**
+     * @param SamplerFactoryInterface|class-string<SamplerFactoryInterface> $factory
+     * @throws TypeError
+     */
+    public static function registerSamplerFactory(string $sampler, SamplerFactoryInterface|string $factory, bool $clobber = false): void
+    {
+        if (!$clobber && array_key_exists($sampler, self::$samplerFactories)) {
+            return;
+        }
+        if (!is_subclass_of($factory, SamplerFactoryInterface::class)) {
+            throw new TypeError(
+                sprintf(
+                    'Cannot register sampler factory: %s must exist and implement %s',
+                    is_string($factory) ? $factory : $factory::class,
+                    SamplerFactoryInterface::class
+                )
+            );
+        }
+        self::$samplerFactories[$sampler] = $factory;
+    }
+
     public static function spanExporterFactory(string $exporter): SpanExporterFactoryInterface
     {
         if (!array_key_exists($exporter, self::$spanExporterFactories)) {
@@ -221,4 +244,16 @@ public static function resourceDetectors(): array
     {
         return array_values(self::$resourceDetectors);
     }
+
+    public static function samplerFactory(string $sampler): SamplerFactoryInterface
+    {
+        if (!array_key_exists($sampler, self::$samplerFactories)) {
+            throw new RuntimeException('Sampler factory not registered for: ' . $sampler);
+        }
+        $class = self::$samplerFactories[$sampler];
+        $factory = (is_callable($class)) ? $class : new $class();
+        assert($factory instanceof SamplerFactoryInterface);
+
+        return $factory;
+    }
 }

src/SDK/Trace/Sampler/AlwaysOffSamplerFactory.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\SDK\Trace\Sampler;
+
+use OpenTelemetry\SDK\Trace\SamplerInterface;
+
+class AlwaysOffSamplerFactory implements SamplerFactoryInterface
+{
+    #[\Override]
+    public function create(): SamplerInterface
+    {
+        return new AlwaysOffSampler();
+    }
+}

src/SDK/Trace/Sampler/AlwaysOnSamplerFactory.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\SDK\Trace\Sampler;
+
+use OpenTelemetry\SDK\Trace\SamplerInterface;
+
+class AlwaysOnSamplerFactory implements SamplerFactoryInterface
+{
+    #[\Override]
+    public function create(): SamplerInterface
+    {
+        return new AlwaysOnSampler();
+    }
+}

src/SDK/Trace/Sampler/ParentBasedAlwaysOffSamplerFactory.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\SDK\Trace\Sampler;
+
+use OpenTelemetry\SDK\Trace\SamplerInterface;
+
+class ParentBasedAlwaysOffSamplerFactory implements SamplerFactoryInterface
+{
+    #[\Override]
+    public function create(): SamplerInterface
+    {
+        return new ParentBased(new AlwaysOffSampler());
+    }
+}

src/SDK/Trace/Sampler/ParentBasedAlwaysOnSamplerFactory.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\SDK\Trace\Sampler;
+
+use OpenTelemetry\SDK\Trace\SamplerInterface;
+
+class ParentBasedAlwaysOnSamplerFactory implements SamplerFactoryInterface
+{
+    #[\Override]
+    public function create(): SamplerInterface
+    {
+        return new ParentBased(new AlwaysOnSampler());
+    }
+}

src/SDK/Trace/Sampler/ParentBasedTraceIdRatioSamplerFactory.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\SDK\Trace\Sampler;
+
+use OpenTelemetry\SDK\Common\Configuration\Configuration;
+use OpenTelemetry\SDK\Common\Configuration\Variables;
+use OpenTelemetry\SDK\Trace\SamplerInterface;
+
+class ParentBasedTraceIdRatioSamplerFactory implements SamplerFactoryInterface
+{
+    #[\Override]
+    public function create(): SamplerInterface
+    {
+        $ratio = Configuration::getRatio(Variables::OTEL_TRACES_SAMPLER_ARG);
+
+        return new ParentBased(new TraceIdRatioBasedSampler($ratio));
+    }
+}

src/SDK/Trace/Sampler/SamplerFactoryInterface.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\SDK\Trace\Sampler;
+
+use OpenTelemetry\SDK\Trace\SamplerInterface;
+
+interface SamplerFactoryInterface
+{
+    public function create(): SamplerInterface;
+}

src/SDK/Trace/Sampler/TraceIdRatioBasedSamplerFactory.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\SDK\Trace\Sampler;
+
+use OpenTelemetry\SDK\Common\Configuration\Configuration;
+use OpenTelemetry\SDK\Common\Configuration\Variables;
+use OpenTelemetry\SDK\Trace\SamplerInterface;
+
+class TraceIdRatioBasedSamplerFactory implements SamplerFactoryInterface
+{
+    #[\Override]
+    public function create(): SamplerInterface
+    {
+        $ratio = Configuration::getRatio(Variables::OTEL_TRACES_SAMPLER_ARG);
+
+        return new TraceIdRatioBasedSampler($ratio);
+    }
+}