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

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);
+    }
+}

src/SDK/Trace/Sampler/_register.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+\OpenTelemetry\SDK\Registry::registerSamplerFactory('always_on', \OpenTelemetry\SDK\Trace\Sampler\AlwaysOnSamplerFactory::class);
+\OpenTelemetry\SDK\Registry::registerSamplerFactory('always_off', \OpenTelemetry\SDK\Trace\Sampler\AlwaysOffSamplerFactory::class);
+\OpenTelemetry\SDK\Registry::registerSamplerFactory('traceidratio', \OpenTelemetry\SDK\Trace\Sampler\TraceIdRatioBasedSamplerFactory::class);
+\OpenTelemetry\SDK\Registry::registerSamplerFactory('parentbased_always_on', \OpenTelemetry\SDK\Trace\Sampler\ParentBasedAlwaysOnSamplerFactory::class);
+\OpenTelemetry\SDK\Registry::registerSamplerFactory('parentbased_always_off', \OpenTelemetry\SDK\Trace\Sampler\ParentBasedAlwaysOffSamplerFactory::class);
+\OpenTelemetry\SDK\Registry::registerSamplerFactory('parentbased_traceidratio', \OpenTelemetry\SDK\Trace\Sampler\ParentBasedTraceIdRatioSamplerFactory::class);

src/SDK/Trace/SamplerFactory.php

@@ -6,38 +6,22 @@
 
 use InvalidArgumentException;
 use OpenTelemetry\SDK\Common\Configuration\Configuration;
-use OpenTelemetry\SDK\Common\Configuration\KnownValues as Values;
 use OpenTelemetry\SDK\Common\Configuration\Variables as Env;
-use OpenTelemetry\SDK\Trace\Sampler\AlwaysOffSampler;
-use OpenTelemetry\SDK\Trace\Sampler\AlwaysOnSampler;
-use OpenTelemetry\SDK\Trace\Sampler\ParentBased;
-use OpenTelemetry\SDK\Trace\Sampler\TraceIdRatioBasedSampler;
+use OpenTelemetry\SDK\Registry;
+use RuntimeException;
 
 class SamplerFactory
 {
-    private const TRACEIDRATIO_PREFIX = 'traceidratio';
-
     public function create(): SamplerInterface
     {
         $name = Configuration::getString(Env::OTEL_TRACES_SAMPLER);
 
-        if (str_contains($name, self::TRACEIDRATIO_PREFIX)) {
-            $arg = Configuration::getRatio(Env::OTEL_TRACES_SAMPLER_ARG);
+        try {
+            $factory = Registry::samplerFactory($name);
 
-            switch ($name) {
-                case Values::VALUE_TRACE_ID_RATIO:
-                    return new TraceIdRatioBasedSampler($arg);
-                case Values::VALUE_PARENT_BASED_TRACE_ID_RATIO:
-                    return new ParentBased(new TraceIdRatioBasedSampler($arg));
-            }
+            return $factory->create();
+        } catch (RuntimeException) {
+            throw new InvalidArgumentException(sprintf('Unknown sampler: %s', $name));
         }
-
-        return match ($name) {
-            Values::VALUE_ALWAYS_ON => new AlwaysOnSampler(),
-            Values::VALUE_ALWAYS_OFF => new AlwaysOffSampler(),
-            Values::VALUE_PARENT_BASED_ALWAYS_ON => new ParentBased(new AlwaysOnSampler()),
-            Values::VALUE_PARENT_BASED_ALWAYS_OFF => new ParentBased(new AlwaysOffSampler()),
-            default => throw new InvalidArgumentException(sprintf('Unknown sampler: %s', $name)),
-        };
     }
 }