use SPI to manage components

Makefile

@@ -22,6 +22,8 @@ update: ## Update dependencies
 	$(DC_RUN_PHP) env XDEBUG_MODE=off composer update
 update-lowest: ## Update dependencies to lowest supported versions
 	$(DC_RUN_PHP) env XDEBUG_MODE=off composer update --prefer-lowest
+dump: ## Dump autoload
+	$(DC_RUN_PHP) env XDEBUG_MODE=off composer dump-autoload
 test: test-unit test-integration ## Run unit and integration tests
 test-unit: ## Run unit tests
 	$(DC_RUN_PHP) env XDEBUG_MODE=coverage vendor/bin/phpunit --testsuite unit --colors=always

composer.json

@@ -60,16 +60,14 @@
         "files": [
             "src/Context/fiber/initialize_fiber_handler.php",
             "src/API/Trace/functions.php",
+            "src/Config/SDK/_register.php",
             "src/Contrib/Otlp/_register.php",
             "src/Contrib/Grpc/_register.php",
             "src/Contrib/Zipkin/_register.php",
             "src/Extension/Propagator/B3/_register.php",
             "src/Extension/Propagator/CloudTrace/_register.php",
             "src/Extension/Propagator/Jaeger/_register.php",
-            "src/SDK/Logs/Exporter/_register.php",
-            "src/SDK/Metrics/MetricExporter/_register.php",
-            "src/SDK/Propagation/_register.php",
-            "src/SDK/Trace/SpanExporter/_register.php",
+            "src/SDK/_register.php",
             "src/SDK/Common/Dev/Compatibility/_load.php",
             "src/SDK/Common/Util/functions.php",
             "src/SDK/_autoload.php"
@@ -123,51 +121,35 @@
             "target-directory": "vendor-bin",
             "forward-command": true
         },
+        "spi-config": {
+            "autoload-files": true,
+            "prune-autoload-files": [
+                "src/Contrib/Otlp/_register.php",
+                "src/Contrib/Grpc/_register.php",
+                "src/Contrib/Zipkin/_register.php",
+                "src/Extension/Propagator/B3/_register.php",
+                "src/Extension/Propagator/CloudTrace/_register.php",
+                "src/Extension/Propagator/Jaeger/_register.php",
+                "src/SDK/_register.php"
+            ]
+        },
         "spi": {
+            "OpenTelemetry\\API\\Instrumentation\\AutoInstrumentation\\HookManagerInterface": [
+              "OpenTelemetry\\API\\Instrumentation\\AutoInstrumentation\\ExtensionHookManager"
+            ],
+            "OpenTelemetry\\API\\Instrumentation\\AutoInstrumentation\\Instrumentation": [
+                "OpenTelemetry\\Example\\ExampleInstrumentation"
+            ],
+            "OpenTelemetry\\SDK\\Resource\\ResourceDetectorFactoryInterface": [
+                "OpenTelemetry\\Example\\TestResourceDetectorFactory"
+            ],
             "OpenTelemetry\\Config\\SDK\\Configuration\\ComponentProvider": [
-                "OpenTelemetry\\Config\\SDK\\ComponentProvider\\Propagator\\TextMapPropagatorB3",
-                "OpenTelemetry\\Config\\SDK\\ComponentProvider\\Propagator\\TextMapPropagatorB3Multi",
-                "OpenTelemetry\\Config\\SDK\\ComponentProvider\\Propagator\\TextMapPropagatorBaggage",
-                "OpenTelemetry\\Config\\SDK\\ComponentProvider\\Propagator\\TextMapPropagatorComposite",
-                "OpenTelemetry\\Config\\SDK\\ComponentProvider\\Propagator\\TextMapPropagatorJaeger",
-                "OpenTelemetry\\Config\\SDK\\ComponentProvider\\Propagator\\TextMapPropagatorTraceContext",
-
-                "OpenTelemetry\\Config\\SDK\\ComponentProvider\\Trace\\SamplerAlwaysOff",
-                "OpenTelemetry\\Config\\SDK\\ComponentProvider\\Trace\\SamplerAlwaysOn",
-                "OpenTelemetry\\Config\\SDK\\ComponentProvider\\Trace\\SamplerParentBased",
-                "OpenTelemetry\\Config\\SDK\\ComponentProvider\\Trace\\SamplerTraceIdRatioBased",
-                "OpenTelemetry\\Config\\SDK\\ComponentProvider\\Trace\\SpanExporterConsole",
-                "OpenTelemetry\\Config\\SDK\\ComponentProvider\\Trace\\SpanExporterOtlp",
-                "OpenTelemetry\\Config\\SDK\\ComponentProvider\\Trace\\SpanExporterZipkin",
-                "OpenTelemetry\\Config\\SDK\\ComponentProvider\\Trace\\SpanProcessorBatch",
-                "OpenTelemetry\\Config\\SDK\\ComponentProvider\\Trace\\SpanProcessorSimple",
-
-                "OpenTelemetry\\Config\\SDK\\ComponentProvider\\Metrics\\AggregationResolverDefault",
-                "OpenTelemetry\\Config\\SDK\\ComponentProvider\\Metrics\\MetricExporterConsole",
-                "OpenTelemetry\\Config\\SDK\\ComponentProvider\\Metrics\\MetricExporterOtlp",
-                "OpenTelemetry\\Config\\SDK\\ComponentProvider\\Metrics\\MetricReaderPeriodic",
-
-                "OpenTelemetry\\Config\\SDK\\ComponentProvider\\Logs\\LogRecordExporterConsole",
-                "OpenTelemetry\\Config\\SDK\\ComponentProvider\\Logs\\LogRecordExporterOtlp",
-                "OpenTelemetry\\Config\\SDK\\ComponentProvider\\Logs\\LogRecordProcessorBatch",
-                "OpenTelemetry\\Config\\SDK\\ComponentProvider\\Logs\\LogRecordProcessorSimple",
-
-                "OpenTelemetry\\Config\\SDK\\ComponentProvider\\Instrumentation\\General\\HttpConfigProvider",
-                "OpenTelemetry\\Config\\SDK\\ComponentProvider\\Instrumentation\\General\\PeerConfigProvider",
-
                 "OpenTelemetry\\Example\\ExampleConfigProvider",
-
                 "OpenTelemetry\\Tests\\Integration\\Config\\ComponentProvider\\Metrics\\AggregationResolverExplicitBucketHistogram",
                 "OpenTelemetry\\Tests\\Integration\\Config\\ComponentProvider\\Metrics\\MetricExporterPrometheus",
                 "OpenTelemetry\\Tests\\Integration\\Config\\ComponentProvider\\Metrics\\MetricReaderPull",
                 "OpenTelemetry\\Tests\\Integration\\Config\\ComponentProvider\\Propagator\\TextMapPropagatorXray",
                 "OpenTelemetry\\Tests\\Integration\\Config\\ComponentProvider\\Propagator\\TextMapPropagatorOtTrace"
-            ],
-            "OpenTelemetry\\API\\Instrumentation\\AutoInstrumentation\\HookManagerInterface": [
-              "OpenTelemetry\\API\\Instrumentation\\AutoInstrumentation\\ExtensionHookManager"
-            ],
-            "OpenTelemetry\\API\\Instrumentation\\AutoInstrumentation\\Instrumentation": [
-                "OpenTelemetry\\Example\\ExampleInstrumentation"
             ]
         }
     }

deptrac.baseline.yaml

@@ -1,8 +1,2 @@
 deptrac:
   skip_violations:
-    /src/Extension/Propagator/B3/_register.php:
-      - OpenTelemetry\SDK\Registry
-    /src/Extension/Propagator/CloudTrace/_register.php:
-      - OpenTelemetry\SDK\Registry
-    /src/Extension/Propagator/Jaeger/_register.php:
-      - OpenTelemetry\SDK\Registry

deptrac.yaml

@@ -146,6 +146,7 @@ deptrac:
           - Prometheus
       Extension:
           - +API
+          - SDK
       OtelProto:
           - GoogleProtobuf
           - Grpc

docs/upgrading.md

@@ -0,0 +1,29 @@
+# Upgrading notes for major versions
+
+## 1.x -> 2.x
+
+### API
+
+### SDK
+
+#### SDK\Registry removed
+`SDK\Registry` has been removed, and the technique of registering components (eg propagators, transports,
+auto-instrumentations) has been replaced with [Nevay/SPI](https://github.com/Nevay/spi/) ServiceLoader.
+
+The ServiceLoader should be configured through existing `_register.php` files, which should *only* contain calls to
+SPI's `ServiceLoader::register()` method.
+
+SPI has a composer plugin which will scan for `ServiceLoader::register()` calls in `autoload.files` and generate a
+`GeneratedServiceProviderData.php` file in `vendor/composer/`. The plugin will then remove those `autoload.files` entries
+from composer's generated output to avoid double-loading.
+Pre-generating the services in this way avoids a race-condition in 1.x where composer's `autoload.files` are executed in an
+undefined order, and services may not be registered in time for the SDK to use them.
+
+For SPI to work correctly, the composer plugin _should_ be allowed to run. If the plugin is not allowed to run, then
+services will still register at runtime, however this might still suffer from the same race-condition as `1.x`.
+
+#### FactoryInterfaces updated
+Various component factory interfaces (eg `TextMapPropagatorFactoryInterface`, `TransportFactoryInterface`) have been
+updated to include `priority()` and `type()` methods. These are used in conjunction with SPI ServiceLoader to associate
+a type (eg `otlp`) with a factory, and to allow SDK-provided factories to be replaced by user-provided factories (by
+providing a higher priority for the same type).

examples/autoload_sdk_with_custom_transport.php

@@ -4,6 +4,9 @@
 
 namespace OpenTelemetry\Example;
 
+use Nevay\SPI\ServiceLoader;
+use OpenTelemetry\SDK\Common\Export\TransportFactoryInterface;
+
 putenv('OTEL_PHP_AUTOLOAD_ENABLED=true');
 putenv('OTEL_TRACES_EXPORTER=otlp');
 putenv('OTEL_EXPORTER_OTLP_PROTOCOL=grpc');
@@ -45,9 +48,19 @@ public function forceFlush(?\OpenTelemetry\SDK\Common\Future\CancellationInterfa
             }
         };
     }
+
+    public function type(): string
+    {
+        return 'grpc';
+    }
+
+    public function priority(): int
+    {
+        return 100;
+    }
 };
 
-\OpenTelemetry\SDK\Registry::registerTransportFactory('grpc', $factory, true);
+ServiceLoader::register(TransportFactoryInterface::class, $factory::class);
 
 $instrumentation = new \OpenTelemetry\API\Instrumentation\CachedInstrumentation('demo');
 

examples/logs/exporters/otlp_http.php

@@ -7,7 +7,7 @@
 use OpenTelemetry\API\Logs\LogRecord;
 use OpenTelemetry\API\Logs\Severity;
 use OpenTelemetry\Contrib\Otlp\LogsExporter;
-use OpenTelemetry\Contrib\Otlp\OtlpHttpTransportFactory;
+use OpenTelemetry\SDK\Common\Export\Http\PsrTransportFactory;
 use OpenTelemetry\SDK\Common\Instrumentation\InstrumentationScopeFactory;
 use OpenTelemetry\SDK\Logs\EventLoggerProvider;
 use OpenTelemetry\SDK\Logs\LoggerProvider;
@@ -16,7 +16,7 @@
 
 require __DIR__ . '/../../../vendor/autoload.php';
 
-$transport = (new OtlpHttpTransportFactory())->create('http://collector:4318/v1/logs', 'application/json');
+$transport = (new PsrTransportFactory())->create('http://collector:4318/v1/logs', 'application/json');
 $exporter = new LogsExporter($transport);
 
 $loggerProvider = new LoggerProvider(

examples/src/ExampleConfig.php

@@ -13,4 +13,9 @@ public function __construct(
         public readonly bool $enabled = true,
     ) {
     }
+
+    public static function default(): self
+    {
+        return new self('example');
+    }
 }

examples/src/ExampleInstrumentation.php

@@ -4,7 +4,6 @@
 
 namespace OpenTelemetry\Example;
 
-use Exception;
 use OpenTelemetry\API\Configuration\ConfigProperties;
 use OpenTelemetry\API\Instrumentation\AutoInstrumentation\Context as InstrumentationContext;
 use OpenTelemetry\API\Instrumentation\AutoInstrumentation\HookManagerInterface;
@@ -16,7 +15,7 @@ final class ExampleInstrumentation implements Instrumentation
 {
     public function register(HookManagerInterface $hookManager, ConfigProperties $configuration, InstrumentationContext $context): void
     {
-        $config = $configuration->get(ExampleConfig::class) ?? throw new Exception('example instrumentation must be configured');
+        $config = $configuration->get(ExampleConfig::class) ?? ExampleConfig::default();
         if (!$config->enabled) {
             return;
         }

examples/src/TestResourceDetector.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\Example;
+
+use OpenTelemetry\SDK\Common\Attribute\Attributes;
+use OpenTelemetry\SDK\Resource\ResourceDetectorInterface;
+use OpenTelemetry\SDK\Resource\ResourceInfo;
+use OpenTelemetry\SemConv\ResourceAttributes;
+
+class TestResourceDetector implements ResourceDetectorInterface
+{
+    public function getResource(): ResourceInfo
+    {
+        $attributes = [
+            'test-resource' => 'test-value',
+        ];
+
+        return ResourceInfo::create(Attributes::create($attributes), ResourceAttributes::SCHEMA_URL);
+    }
+}

examples/src/TestResourceDetectorFactory.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\Example;
+
+use OpenTelemetry\SDK\Resource\ResourceDetectorFactoryInterface;
+use OpenTelemetry\SDK\Resource\ResourceDetectorInterface;
+
+class TestResourceDetectorFactory implements ResourceDetectorFactoryInterface
+{
+    public function create(): ResourceDetectorInterface
+    {
+        return new TestResourceDetector();
+    }
+
+    public function type(): string
+    {
+        return 'test';
+    }
+
+    public function priority(): int
+    {
+        return 0;
+    }
+}

examples/traces/exporters/otlp_http.php

@@ -6,12 +6,12 @@
 
 require __DIR__ . '/../../../vendor/autoload.php';
 
-use OpenTelemetry\Contrib\Otlp\OtlpHttpTransportFactory;
 use OpenTelemetry\Contrib\Otlp\SpanExporter;
+use OpenTelemetry\SDK\Common\Export\Http\PsrTransportFactory;
 use OpenTelemetry\SDK\Trace\SpanProcessor\SimpleSpanProcessor;
 use OpenTelemetry\SDK\Trace\TracerProvider;
 
-$transport = (new OtlpHttpTransportFactory())->create('http://collector:4318/v1/traces', 'application/x-protobuf');
+$transport = (new PsrTransportFactory())->create('http://collector:4318/v1/traces', 'application/x-protobuf');
 $exporter = new SpanExporter($transport);
 
 echo 'Starting OTLP example';

examples/traces/exporters/otlp_http_json.php

@@ -7,12 +7,12 @@
 require __DIR__ . '/../../../vendor/autoload.php';
 
 use OpenTelemetry\Contrib\Otlp\ContentTypes;
-use OpenTelemetry\Contrib\Otlp\OtlpHttpTransportFactory;
 use OpenTelemetry\Contrib\Otlp\SpanExporter;
+use OpenTelemetry\SDK\Common\Export\Http\PsrTransportFactory;
 use OpenTelemetry\SDK\Trace\SpanProcessor\SimpleSpanProcessor;
 use OpenTelemetry\SDK\Trace\TracerProvider;
 
-$transport = (new OtlpHttpTransportFactory())->create('http://collector:4318/v1/traces', ContentTypes::JSON);
+$transport = (new PsrTransportFactory())->create('http://collector:4318/v1/traces', ContentTypes::JSON);
 $exporter = new SpanExporter($transport);
 
 echo 'Starting OTLP+json example';

examples/traces/features/auto_root_span.php

@@ -11,8 +11,11 @@
 putenv('OTEL_TRACES_EXPORTER=console');
 putenv('OTEL_METRICS_EXPORTER=none');
 putenv('OTEL_LOGS_EXPORTER=console');
+putenv('OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318');
+putenv('OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf');
 putenv('OTEL_PROPAGATORS=tracecontext');
 putenv('OTEL_PHP_EXPERIMENTAL_AUTO_ROOT_SPAN=true');
+putenv('OTEL_PHP_DETECTORS=sdk,test');
 
 //Usage: php -S localhost:8080 examples/traces/features/auto_root_span.php
 

phpstan.neon.dist

@@ -50,4 +50,4 @@ parameters:
         -
             message: "#.*return with type T is not subtype.*#"
             paths:
-                - src/SDK/Common/InstrumentationScope
+                - src/SDK/Common/InstrumentationScope

src/Config/SDK/ComponentProvider/Logs/LogRecordExporterConsole.php

@@ -7,9 +7,9 @@
 use OpenTelemetry\Config\SDK\Configuration\ComponentProvider;
 use OpenTelemetry\Config\SDK\Configuration\ComponentProviderRegistry;
 use OpenTelemetry\Config\SDK\Configuration\Context;
+use OpenTelemetry\SDK\Common\Services\Loader;
 use OpenTelemetry\SDK\Logs\Exporter\ConsoleExporter;
 use OpenTelemetry\SDK\Logs\LogRecordExporterInterface;
-use OpenTelemetry\SDK\Registry;
 use Symfony\Component\Config\Definition\Builder\ArrayNodeDefinition;
 use Symfony\Component\Config\Definition\Builder\NodeBuilder;
 
@@ -23,7 +23,7 @@ final class LogRecordExporterConsole implements ComponentProvider
      */
     public function createPlugin(array $properties, Context $context): LogRecordExporterInterface
     {
-        return new ConsoleExporter(Registry::transportFactory('stream')->create(
+        return new ConsoleExporter(Loader::transportFactory('stream')->create(
             endpoint: 'php://stdout',
             contentType: 'application/json',
         ));

src/Config/SDK/ComponentProvider/Logs/LogRecordExporterOtlp.php

@@ -14,8 +14,8 @@
 use OpenTelemetry\Contrib\Otlp\OtlpUtil;
 use OpenTelemetry\Contrib\Otlp\Protocols;
 use OpenTelemetry\SDK\Common\Configuration\Parser\MapParser;
+use OpenTelemetry\SDK\Common\Services\Loader;
 use OpenTelemetry\SDK\Logs\LogRecordExporterInterface;
-use OpenTelemetry\SDK\Registry;
 use Symfony\Component\Config\Definition\Builder\ArrayNodeDefinition;
 use Symfony\Component\Config\Definition\Builder\NodeBuilder;
 
@@ -45,7 +45,7 @@ public function createPlugin(array $properties, Context $context): LogRecordExpo
 
         $headers = array_column($properties['headers'], 'value', 'name') + MapParser::parse($properties['headers_list']);
 
-        return new LogsExporter(Registry::transportFactory($protocol)->create(
+        return new LogsExporter(Loader::transportFactory($protocol)->create(
             endpoint: $properties['endpoint'] . OtlpUtil::path(Signals::LOGS, $protocol),
             contentType: Protocols::contentType($protocol),
             headers: $headers,

src/Config/SDK/ComponentProvider/Metrics/MetricExporterOtlp.php

@@ -14,9 +14,9 @@
 use OpenTelemetry\Contrib\Otlp\OtlpUtil;
 use OpenTelemetry\Contrib\Otlp\Protocols;
 use OpenTelemetry\SDK\Common\Configuration\Parser\MapParser;
+use OpenTelemetry\SDK\Common\Services\Loader;
 use OpenTelemetry\SDK\Metrics\Data\Temporality;
 use OpenTelemetry\SDK\Metrics\MetricExporterInterface;
-use OpenTelemetry\SDK\Registry;
 use Symfony\Component\Config\Definition\Builder\ArrayNodeDefinition;
 use Symfony\Component\Config\Definition\Builder\NodeBuilder;
 
@@ -54,7 +54,7 @@ public function createPlugin(array $properties, Context $context): MetricExporte
             'lowmemory' => null,
         };
 
-        return new MetricExporter(Registry::transportFactory($protocol)->create(
+        return new MetricExporter(Loader::transportFactory($protocol)->create(
             endpoint: $properties['endpoint'] . OtlpUtil::path(Signals::METRICS, $protocol),
             contentType: Protocols::contentType($protocol),
             headers: $headers,

src/Config/SDK/ComponentProvider/Trace/SpanExporterConsole.php

@@ -7,7 +7,7 @@
 use OpenTelemetry\Config\SDK\Configuration\ComponentProvider;
 use OpenTelemetry\Config\SDK\Configuration\ComponentProviderRegistry;
 use OpenTelemetry\Config\SDK\Configuration\Context;
-use OpenTelemetry\SDK\Registry;
+use OpenTelemetry\SDK\Common\Services\Loader;
 use OpenTelemetry\SDK\Trace\SpanExporter\ConsoleSpanExporter;
 use OpenTelemetry\SDK\Trace\SpanExporterInterface;
 use Symfony\Component\Config\Definition\Builder\ArrayNodeDefinition;
@@ -23,7 +23,7 @@ final class SpanExporterConsole implements ComponentProvider
      */
     public function createPlugin(array $properties, Context $context): SpanExporterInterface
     {
-        return new ConsoleSpanExporter(Registry::transportFactory('stream')->create(
+        return new ConsoleSpanExporter(Loader::transportFactory('stream')->create(
             endpoint: 'php://stdout',
             contentType: 'application/json',
         ));