Add option to disable debug scopes (#1205)

src/Context/Context.php

@@ -5,6 +5,9 @@
 namespace OpenTelemetry\Context;
 
 use function assert;
+use const FILTER_VALIDATE_BOOLEAN;
+use function filter_var;
+use function ini_get;
 use function spl_object_id;
 
 /**
@@ -80,12 +83,19 @@ public static function getCurrent(): ContextInterface
     public function activate(): ScopeInterface
     {
         $scope = self::storage()->attach($this);
-        /** @psalm-suppress RedundantCondition */
-        assert((bool) $scope = new DebugScope($scope));
+        /** @psalm-suppress RedundantCondition @phpstan-ignore-next-line */
+        assert(self::debugScopesDisabled() || $scope = new DebugScope($scope));
 
         return $scope;
     }
 
+    private static function debugScopesDisabled(): bool
+    {
+        $disabled = $_SERVER['OTEL_PHP_DEBUG_SCOPES_DISABLED'] ?? ini_get('OTEL_PHP_DEBUG_SCOPES_DISABLED');
+
+        return filter_var($disabled, FILTER_VALIDATE_BOOLEAN);
+    }
+
     public function withContextValue(ImplicitContextKeyedInterface $value): ContextInterface
     {
         return $value->storeInContext($this);

src/Context/README.md

@@ -31,6 +31,12 @@ try {
 
 It is recommended to use a `try-finally` statement after `::activate()` to ensure that the created scope is properly `::detach()`ed.
 
+### Debug scopes
+
+By default, scopes created by `::activate()` warn on invalid and missing calls to `::detach()` in non-production
+environments. This feature can be disabled by setting the environment variable `OTEL_PHP_DEBUG_SCOPES_DISABLED` to a
+truthy value. Disabling is only recommended for applications using `exit` / `die` to prevent unavoidable notices.
+
 ## Async applications
 
 ### Fiber support

tests/Unit/Context/DebugScopeTest.php

@@ -4,7 +4,9 @@
 
 namespace OpenTelemetry\Tests\Unit\Context;
 
+use function ini_set;
 use OpenTelemetry\Context\Context;
+use OpenTelemetry\Context\DebugScope;
 use PHPUnit\Framework\Exception as PHPUnitFrameworkException;
 use PHPUnit\Framework\TestCase;
 
@@ -13,6 +15,55 @@
  */
 final class DebugScopeTest extends TestCase
 {
+
+    /**
+     * @covers \OpenTelemetry\Context\Context::activate
+     * @covers \OpenTelemetry\Context\Context::debugScopesDisabled
+     */
+    public function test_debug_scope_enabled_by_default(): void
+    {
+        $scope = Context::getCurrent()->activate();
+
+        try {
+            self::assertInstanceOf(DebugScope::class, $scope);
+        } finally {
+            $scope->detach();
+        }
+    }
+
+    /**
+     * @covers \OpenTelemetry\Context\Context::activate
+     */
+    public function test_disable_debug_scope_using_assertion_mode(): void
+    {
+        ini_set('zend.assertions', '0');
+        $scope = Context::getCurrent()->activate();
+
+        try {
+            self::assertNotInstanceOf(DebugScope::class, $scope);
+        } finally {
+            ini_set('zend.assertions', '1');
+            $scope->detach();
+        }
+    }
+
+    /**
+     * @covers \OpenTelemetry\Context\Context::activate
+     * @covers \OpenTelemetry\Context\Context::debugScopesDisabled
+     * @backupGlobals
+     */
+    public function test_disable_debug_scope_using_otel_php_debug_scopes_disabled(): void
+    {
+        $_SERVER['OTEL_PHP_DEBUG_SCOPES_DISABLED'] = 'true';
+        $scope = Context::getCurrent()->activate();
+
+        try {
+            self::assertNotInstanceOf(DebugScope::class, $scope);
+        } finally {
+            $scope->detach();
+        }
+    }
+
     public function test_detached_scope_detach(): void
     {
         $scope1 = Context::getCurrent()->activate();