adding a configuration for disabling auto-instrumentations (#909)

* adding a configuration for disabling auto-instrumentations
addressing review feedback from pdelewski, provide a mechanism that can be used to disable auto-instrumentation packages
without actually uninstalling them.
A new variable, OTEL_PHP_DISABLED_INSTRUMENTATIONS, has been added which accepts a list of instrumentation names to be disabled.
Each instrumentation can call Instrumentation::isDisabled to determine if they should bail without registering hooks.

* moving instrumentation disabled into Sdk class

README.md

@@ -20,6 +20,7 @@
 - [Getting started](#getting-started)
   - [Instrumenting an application](#using-opentelemetry-in-an-application)
   - [Instrumenting a library](#using-opentelemetry-to-instrument-a-library)
+  - [Configuration](#configuration)
   - [Trace signals](#trace-signals)
     - [Auto-instrumentation](#auto-instrumentation)
     - [Framework instrumentation](#framework-instrumentation)
@@ -243,6 +244,21 @@ SDK autoloading must be enabled via the `OTEL_PHP_AUTOLOAD_ENABLED` setting, and
 
 See [autoload_sdk.php example](./examples/autoload_sdk.php)
 
+## Configuration
+
+The SDK supports most of the configurations described in the specification: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/sdk-environment-variables.md#general-sdk-configuration
+
+There are also a number of PHP-specific configurations:
+
+| Name                                | Default value | Values                                                     | Example        | Description                                         |
+|-------------------------------------|---------------|------------------------------------------------------------|----------------|-----------------------------------------------------|
+| OTEL_PHP_TRACES_PROCESSOR           | batch         | batch, simple                                              | simple         | Span processor selection                            |
+| OTEL_PHP_DETECTORS                  | all           | env, host, os, process, process_runtime, sdk, sdk_provided | env,os,process | Resource detector selection                         |
+| OTEL_PHP_AUTOLOAD_ENABLED           | false         | true, false                                                | true           | Enable/disable SDK autoloading                      |
+| OTEL_PHP_DISABLED_INSTRUMENTATIONS  | []            | Instrumentation name(s)                                    | psr15,psr18    | Disable one or more installed auto-instrumentations |
+
+Configurations can be provided as environment variables, or via `php.ini` (or a file included by `php.ini`)
+
 ## Trace signals
 
 ### Auto-instrumentation

src/SDK/Common/Configuration/Defaults.php

@@ -94,4 +94,5 @@ interface Defaults
     public const OTEL_PHP_TRACES_PROCESSOR = 'batch';
     public const OTEL_PHP_DETECTORS = 'all';
     public const OTEL_PHP_AUTOLOAD_ENABLED = 'false';
+    public const OTEL_PHP_DISABLED_INSTRUMENTATIONS = [];
 }

src/SDK/Common/Configuration/ValueTypes.php

@@ -109,4 +109,5 @@ interface ValueTypes
      */
     public const OTEL_PHP_TRACES_PROCESSOR = VariableTypes::ENUM;
     public const OTEL_PHP_DETECTORS = VariableTypes::LIST;
+    public const OTEL_PHP_DISABLED_INSTRUMENTATIONS = VariableTypes::LIST;
 }

src/SDK/Common/Configuration/Variables.php

@@ -111,4 +111,5 @@ interface Variables
     public const OTEL_PHP_TRACES_PROCESSOR = 'OTEL_PHP_TRACES_PROCESSOR';
     public const OTEL_PHP_DETECTORS = 'OTEL_PHP_DETECTORS';
     public const OTEL_PHP_AUTOLOAD_ENABLED = 'OTEL_PHP_AUTOLOAD_ENABLED';
+    public const OTEL_PHP_DISABLED_INSTRUMENTATIONS = 'OTEL_PHP_DISABLED_INSTRUMENTATIONS';
 }

src/SDK/Sdk.php

@@ -31,6 +31,14 @@ class Sdk
         return Configuration::getBoolean(Variables::OTEL_SDK_DISABLED);
     }
 
+    /**
+     * Tests whether an auto-instrumentation package has been disabled by config
+     */
+    public static function isInstrumentationDisabled(string $name): bool
+    {
+        return in_array($name, Configuration::getList(Variables::OTEL_PHP_DISABLED_INSTRUMENTATIONS));
+    }
+
     public static function builder(): SdkBuilder
     {
         return new SdkBuilder();

tests/Unit/SDK/SdkTest.php

@@ -6,6 +6,7 @@ namespace OpenTelemetry\Tests\Unit\SDK;
 
 use AssertWell\PHPUnitGlobalState\EnvironmentVariables;
 use OpenTelemetry\Context\Propagation\TextMapPropagatorInterface;
+use OpenTelemetry\SDK\Common\Configuration\Variables;
 use OpenTelemetry\SDK\Metrics\MeterProviderInterface;
 use OpenTelemetry\SDK\Sdk;
 use OpenTelemetry\SDK\SdkBuilder;
@@ -45,6 +46,26 @@ class SdkTest extends TestCase
         ];
     }
 
+    /**
+     * @dataProvider instrumentationDisabledProvider
+     */
+    public function test_is_instrumentation_disabled(string $value, string $name, bool $expected): void
+    {
+        $this->setEnvironmentVariable(Variables::OTEL_PHP_DISABLED_INSTRUMENTATIONS, $value);
+
+        $this->assertSame($expected, Sdk::isInstrumentationDisabled($name));
+    }
+
+    public function instrumentationDisabledProvider(): array
+    {
+        return [
+            ['foo,bar', 'foo', true],
+            ['foo,bar', 'bar', true],
+            ['', 'foo', false],
+            ['foo', 'foo', true],
+        ];
+    }
+
     public function test_builder(): void
     {
         $this->assertInstanceOf(SdkBuilder::class, Sdk::builder());