auto-instrumentation registration

.github/workflows/php.yml

@@ -21,7 +21,7 @@ jobs:
             experimental: true
             composer_args: "--ignore-platform-reqs"
     env:
-      extensions: ast, grpc, protobuf
+      extensions: ast, grpc, opentelemetry, protobuf
 
     steps:
     - name: Set cache key

.phan/config.php

@@ -373,9 +373,9 @@
         'vendor/composer',
         'vendor/grpc/grpc/src/lib',
         'vendor/guzzlehttp',
+        'vendor/tbachert/spi/src',
         'vendor/psr',
         'vendor/php-http',
-        'vendor/phan/phan/src/Phan',
         'vendor/phpunit/phpunit/src',
         'vendor/google/protobuf/src',
     ],

composer.json

@@ -18,7 +18,7 @@
         "symfony/config": "^5.4 || ^6.4 || ^7.0",
         "symfony/polyfill-mbstring": "^1.23",
         "symfony/polyfill-php82": "^1.26",
-        "tbachert/spi": "^0.2"
+        "tbachert/spi": ">= 0.2.1"
     },
     "config": {
         "sort-packages": true,
@@ -147,7 +147,15 @@
                 "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\\Logs\\LogRecordProcessorSimple",
+
+                "OpenTelemetry\\Example\\ExampleConfigProvider"
+            ],
+            "OpenTelemetry\\API\\Instrumentation\\AutoInstrumentation\\HookManager": [
+                "OpenTelemetry\\API\\Instrumentation\\AutoInstrumentation\\ExtensionHookManager"
+            ],
+            "OpenTelemetry\\API\\Instrumentation\\AutoInstrumentation\\Instrumentation": [
+                "OpenTelemetry\\Example\\ExampleInstrumentation"
             ]
         }
     }

deptrac.yaml

@@ -25,6 +25,10 @@ deptrac:
           collectors:
               -   type: directory
                   value: src/SDK/.*
+      -   name: ConfigSDK
+          collectors:
+              -   type: directory
+                  value: src/Config/SDK/.*
       -   name: Context
           collectors:
               -   type: directory
@@ -85,21 +89,46 @@ deptrac:
               value: ^GuzzleHttp\\*
             - type: className
               value: ^Buzz\\*
+      -   name: SPI
+          collectors:
+            - type: className
+              value: ^Nevay\\SPI\\*
+      -   name: SymfonyConfig
+          collectors:
+            - type: className
+              value: ^Symfony\\Component\\Config\\*
+            - type: className
+              value: ^Symfony\\Component\\Yaml\\*
+            - type: className
+              value: ^Symfony\\Component\\VarExporter\\*
 
     ruleset:
       Context:
           - FFI
       SemConv: ~
+      ConfigSDK:
+          - SymfonyConfig
+          - API
+          - SDK
+          - SPI
+          - PsrLog
+          - Composer
+          - Context
+          - Contrib
+          - Extension
       API:
           - Context
           - PsrLog
+          - SPI
       SDK:
           - +API
+          - ConfigSDK
           - SemConv
           - PsrHttp
           - HttpPlug
           - Composer
           - HttpClients
+          - SPI
       Contrib:
           - +SDK
           - +OtelProto

docker/Dockerfile

@@ -11,6 +11,7 @@ RUN chmod +x /usr/local/bin/install-php-extensions \
         grpc \
         intl\
         opcache \
+        opentelemetry \
         pcntl \
         protobuf \
         sockets \

examples/instrumentation/configure_instrumentation.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace _;
+
+use Nevay\SPI\ServiceLoader;
+use OpenTelemetry\API\Instrumentation\AutoInstrumentation\ExtensionHookManager;
+use OpenTelemetry\API\Instrumentation\AutoInstrumentation\Instrumentation;
+use OpenTelemetry\API\Logs\NoopLoggerProvider;
+use OpenTelemetry\API\Metrics\Noop\NoopMeterProvider;
+use OpenTelemetry\API\Trace\NoopTracerProvider;
+use OpenTelemetry\Config\SDK\Configuration;
+use OpenTelemetry\Config\SDK\Configuration\Context;
+use OpenTelemetry\Example\Example;
+use const PHP_EOL;
+
+/**
+ * This example uses SPI (see root composer.json extra.spi) to configure an example auto-instrumentation from a YAML file
+ */
+// EXAMPLE_INSTRUMENTATION_SPAN_NAME=test1234 php examples/instrumentation/configure_instrumentation.php
+
+require __DIR__ . '/../../vendor/autoload.php';
+
+Configuration::parseFile(__DIR__ . '/otel-sdk.yaml')->create(new Context())->setAutoShutdown(true)->buildAndRegisterGlobal();
+$configuration = \OpenTelemetry\Config\SDK\Instrumentation::parseFile(__DIR__ . '/otel-instrumentation.yaml')->create();
+$hookManager = new ExtensionHookManager();
+$context = new \OpenTelemetry\API\Instrumentation\AutoInstrumentation\Context(new NoopTracerProvider(), new NoopMeterProvider(), new NoopLoggerProvider());
+
+foreach (ServiceLoader::load(Instrumentation::class) as $instrumentation) {
+    $instrumentation->register($hookManager, $configuration, $context);
+}
+
+echo (new Example())->test(), PHP_EOL;

examples/instrumentation/configure_instrumentation_global.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace _;
+
+use OpenTelemetry\Example\Example;
+use const PHP_EOL;
+
+/**
+ * This example uses SPI (see root composer.json extra.spi) to configure an example auto-instrumentation from a YAML file.
+ * The YAML file paths are relative to the current working directory.
+ */
+// EXAMPLE_INSTRUMENTATION_SPAN_NAME=test1234 php examples/instrumentation/configure_instrumentation_global.php
+putenv('OTEL_PHP_AUTOLOAD_ENABLED=true');
+putenv('OTEL_EXPERIMENTAL_CONFIG_FILE=examples/instrumentation/otel-sdk.yaml');
+putenv('OTEL_PHP_INSTRUMENTATION_CONFIG_FILE=examples/instrumentation/otel-instrumentation.yaml');
+
+require __DIR__ . '/../../vendor/autoload.php';
+
+echo (new Example())->test(), PHP_EOL;

examples/instrumentation/otel-instrumentation.yaml

@@ -0,0 +1,3 @@
+config:
+  - example_instrumentation:
+      span_name: ${EXAMPLE_INSTRUMENTATION_SPAN_NAME:-example span}

examples/instrumentation/otel-sdk.yaml

@@ -0,0 +1,7 @@
+file_format: '0.1'
+
+tracer_provider:
+  processors:
+  - simple:
+      exporter:
+        console: {}

examples/src/Example.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\Example;
+
+final class Example
+{
+
+    public function test(): int
+    {
+        return 42;
+    }
+}

examples/src/ExampleConfig.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\Example;
+
+use OpenTelemetry\API\Instrumentation\AutoInstrumentation\InstrumentationConfiguration;
+
+final class ExampleConfig implements InstrumentationConfiguration
+{
+
+    public function __construct(
+        public readonly string $spanName,
+        public readonly bool $enabled = true,
+    ) {
+    }
+}

examples/src/ExampleConfigProvider.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\Example;
+
+use OpenTelemetry\API\Instrumentation\AutoInstrumentation\InstrumentationConfiguration;
+use OpenTelemetry\Config\SDK\Configuration\ComponentProvider;
+use OpenTelemetry\Config\SDK\Configuration\ComponentProviderRegistry;
+use OpenTelemetry\Config\SDK\Configuration\Context;
+use OpenTelemetry\Config\SDK\Configuration\Validation;
+use Symfony\Component\Config\Definition\Builder\ArrayNodeDefinition;
+
+/**
+ * @implements ComponentProvider<InstrumentationConfiguration>
+ */
+final class ExampleConfigProvider implements ComponentProvider
+{
+
+    /**
+     * @psalm-suppress MoreSpecificImplementedParamType
+     * @param array{
+     *     span_name: string,
+     *     enabled: bool,
+     * } $properties
+     */
+    public function createPlugin(array $properties, Context $context): InstrumentationConfiguration
+    {
+        return new ExampleConfig(
+            spanName: $properties['span_name'],
+            enabled: $properties['enabled'],
+        );
+    }
+
+    /**
+     * @psalm-suppress UndefinedInterfaceMethod,PossiblyNullReference
+     */
+    public function getConfig(ComponentProviderRegistry $registry): ArrayNodeDefinition
+    {
+        $root = new ArrayNodeDefinition('example_instrumentation');
+        $root
+            ->children()
+                ->scalarNode('span_name')->isRequired()->validate()->always(Validation::ensureString())->end()->end()
+            ->end()
+            ->canBeDisabled()
+        ;
+
+        return $root;
+    }
+}

examples/src/ExampleInstrumentation.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\Example;
+
+use Exception;
+use OpenTelemetry\API\Globals;
+use OpenTelemetry\API\Instrumentation\AutoInstrumentation\ConfigurationRegistry;
+use OpenTelemetry\API\Instrumentation\AutoInstrumentation\Context as InstrumentationContext;
+use OpenTelemetry\API\Instrumentation\AutoInstrumentation\HookManager;
+use OpenTelemetry\API\Instrumentation\AutoInstrumentation\Instrumentation;
+use OpenTelemetry\API\Trace\Span;
+use OpenTelemetry\Context\Context;
+
+final class ExampleInstrumentation implements Instrumentation
+{
+
+    /**
+     * @todo can we pass in just the config for _this_ instrumentation, rather than all?
+     */
+    public function register(HookManager $hookManager, ConfigurationRegistry $configuration, InstrumentationContext $context): void
+    {
+        $config = $configuration->get(ExampleConfig::class) ?? throw new Exception('example instrumentation must be configured');
+        if (!$config->enabled) {
+            return;
+        }
+
+        $tracer = Globals::tracerProvider()->getTracer('example-instrumentation');
+
+        $hookManager->hook(
+            Example::class,
+            'test',
+            static function () use ($tracer, $config): void {
+                $context = Context::getCurrent();
+
+                $span = $tracer
+                    ->spanBuilder($config->spanName)
+                    ->setParent($context)
+                    ->startSpan();
+
+                Context::storage()->attach($span->storeInContext($context));
+            },
+            static function (): void {
+                if (!$scope = Context::storage()->scope()) {
+                    return;
+                }
+
+                $scope->detach();
+
+                $span = Span::fromContext($scope->context());
+                $span->end();
+            }
+        );
+    }
+}

psalm.xml.dist

@@ -27,6 +27,11 @@
                 <referencedClass name="GMP"/>
             </errorLevel>
         </UndefinedClass>
+        <UndefinedFunction>
+            <errorLevel type="suppress">
+                <referencedFunction name="OpenTelemetry\Instrumentation\hook"/>
+            </errorLevel>
+        </UndefinedFunction>
         <ArgumentTypeCoercion>
             <errorLevel type="suppress">
                 <directory name="./examples"/>

src/API/Globals.php

@@ -6,7 +6,7 @@
 
 use function assert;
 use Closure;
-use const E_USER_WARNING;
+use OpenTelemetry\API\Behavior\LogsMessagesTrait;
 use OpenTelemetry\API\Instrumentation\Configurator;
 use OpenTelemetry\API\Instrumentation\ContextKeys;
 use OpenTelemetry\API\Logs\EventLoggerProviderInterface;
@@ -17,13 +17,14 @@
 use OpenTelemetry\Context\Propagation\TextMapPropagatorInterface;
 use function sprintf;
 use Throwable;
-use function trigger_error;
 
 /**
  * Provides access to the globally configured instrumentation instances.
  */
 final class Globals
 {
+    use LogsMessagesTrait;
+
     /** @var Closure[] */
     private static array $initializers = [];
     private static ?self $globals = null;
@@ -67,6 +68,7 @@ public static function eventLoggerProvider(): EventLoggerProviderInterface
      *
      * @internal
      * @psalm-internal OpenTelemetry
+     * @todo In a future (breaking) change, we can remove `Registry` and globals initializers, in favor of SPI.
      */
     public static function registerInitializer(Closure $initializer): void
     {
@@ -90,7 +92,7 @@ private static function globals(): self
                 try {
                     $configurator = $initializer($configurator);
                 } catch (Throwable $e) {
-                    trigger_error(sprintf("Error during opentelemetry initialization: %s\n%s", $e->getMessage(), $e->getTraceAsString()), E_USER_WARNING);
+                    self::logWarning(sprintf("Error during opentelemetry initialization: %s\n%s", $e->getMessage(), $e->getTraceAsString()));
                 }
             }
         } finally {