feat(otel): align resolve_feature_flags with strict LLD requirements

Author: chalmerlowe

packages/google-api-core/google/api_core/observability/__init__.py

@@ -1,11 +1,11 @@
 from .options import (
     clear_test_env_overrides,
-    is_signal_enabled,
+    resolve_feature_flags,
     set_test_env_override,
 )
 
 __all__ = [
-    "is_signal_enabled",
+    "resolve_feature_flags",
     "set_test_env_override",
     "clear_test_env_overrides",
 ]

packages/google-api-core/google/api_core/observability/options.py

@@ -74,55 +74,60 @@ def _get_env_bool(name: str) -> Optional[bool]:
 
 def _get_env_bool_with_dev_fallback(name: str) -> Optional[bool]:
     """Retrieve the boolean value of an environment variable, checking experimental fallbacks first."""
-    if name.startswith("GOOGLE_CLOUD_"):
-        exp_name = name.replace("GOOGLE_CLOUD_", "GOOGLE_CLOUD_EXPERIMENTAL_", 1)
+    if name.startswith("GOOGLE_SDK_"):
+        exp_name = name.replace("GOOGLE_SDK_", "GOOGLE_SDK_EXPERIMENTAL_", 1)
         val = _get_env_bool(exp_name)
         if val is not None:
             return val
     return _get_env_bool(name)
 
 
-def is_signal_enabled(
-    signal_type: str,
+def resolve_feature_flags(
+    feature_name: str,
     client_options: Optional[Union[Dict[str, Any], Any]] = None,
     default: bool = False,
 ) -> bool:
     """Determines if a telemetry signal is enabled.
 
     Resolves settings in the following order of precedence:
     1. Programmatic overrides in client_options (checks tracer_provider)
-    2. Language-wide Environment Variable: GOOGLE_CLOUD_PYTHON_TRACING_ENABLED
+    2. Language-wide Environment Variable: GOOGLE_SDK_PYTHON_TRACING_ENABLED
        (natively checks for a variant with an "EXPERIMENTAL" token first)
     3. Default fallback
 
     Args:
-        signal_type: The signal type: must be 'tracing'.
+        feature_name: The feature name: must be 'tracing'.
         client_options: A dictionary or object containing client configuration.
         default: Fallback boolean if no options or env variables match.
 
     Returns:
         bool: True if the signal is resolved to enabled, False otherwise.
     """
-    if signal_type != "tracing":
+    if feature_name != "tracing":
         raise ValueError(
-            f"Invalid signal_type: {signal_type!r}. Only 'tracing' is supported at this time."
+            f"Invalid feature_name: {feature_name!r}. Only 'tracing' is supported at this time."
         )
 
-    # 1. Resolve Programmatic Options First
+    # 1. Experimental Gate
+    exp_var = "GOOGLE_SDK_EXPERIMENTAL_PYTHON_TRACING_ENABLED"
+    exp_val = _get_env_bool(exp_var)
+
+    has_provider = False
     if client_options is not None:
         options_dict = (
             client_options
             if isinstance(client_options, dict)
             else getattr(client_options, "__dict__", {})
         )
-
         if options_dict.get("tracer_provider") is not None:
-            return True
+            has_provider = True
 
-    # 2. Check Language-Wide Environment Variable
-    val = _get_env_bool_with_dev_fallback("GOOGLE_CLOUD_PYTHON_TRACING_ENABLED")
-    if val is not None:
-        return val
+    if exp_val is not True:
+        if has_provider:
+            raise ValueError(
+                f"Experimental feature {feature_name!r} requires {exp_var} to be set to 'true' to use programmatic providers."
+            )
+        return False # Blocked
 
-    # 3. Default Fallback
-    return default
+    # If we are here, exp_val IS True.
+    return True

packages/google-api-core/tests/unit/observability/test_options.py

@@ -13,7 +13,6 @@
 # limitations under the License.
 
 import pytest
-
 from google.api_core.observability import options
 from google.api_core.observability.options import (
     _get_env_bool,
@@ -104,68 +103,71 @@ def test_get_env_bool_with_dev_fallback_other_prefix(monkeypatch):
 
 
 @pytest.mark.parametrize(
-    "signal_type, env_vars, client_options, default_val, expected",
+    "feature_name, env_vars, client_options, default_val, expected",
     [
         # Default fallback tests
         ("tracing", {}, None, False, False),
-        ("tracing", {}, None, True, True),
-        # Global env var
-        ("tracing", {"GOOGLE_CLOUD_PYTHON_TRACING_ENABLED": True}, None, False, True),
-        ("tracing", {"GOOGLE_CLOUD_PYTHON_TRACING_ENABLED": False}, None, True, False),
+        # Default=True is ignored if blocked
+        ("tracing", {}, None, True, False),
+        # Global GA env var is ignored if experimental flag is missing
+        ("tracing", {"GOOGLE_SDK_PYTHON_TRACING_ENABLED": True}, None, False, False),
+        ("tracing", {"GOOGLE_SDK_PYTHON_TRACING_ENABLED": False}, None, True, False),
         # Experimental fallback
         (
             "tracing",
-            {"GOOGLE_CLOUD_EXPERIMENTAL_PYTHON_TRACING_ENABLED": True},
+            {"GOOGLE_SDK_EXPERIMENTAL_PYTHON_TRACING_ENABLED": True},
             None,
             False,
             True,
         ),
         (
             "tracing",
-            {"GOOGLE_CLOUD_EXPERIMENTAL_PYTHON_TRACING_ENABLED": False},
+            {"GOOGLE_SDK_EXPERIMENTAL_PYTHON_TRACING_ENABLED": False},
             None,
             True,
             False,
         ),
-        # Implicit opt-in with provider
-        (
-            "tracing",
-            {"GOOGLE_CLOUD_PYTHON_TRACING_ENABLED": False},
-            {"tracer_provider": object()},
-            False,
-            True,
-        ),
         # Programmatic boolean flags are NOT supported in client_options
         # (should default/fallback to False)
         (
             "tracing",
-            {"GOOGLE_CLOUD_PYTHON_TRACING_ENABLED": False},
+            {"GOOGLE_SDK_PYTHON_TRACING_ENABLED": False},
             {"enable_metrics": True},
             False,
             False,
         ),
         (
             "tracing",
-            {"GOOGLE_CLOUD_PYTHON_TRACING_ENABLED": False},
+            {"GOOGLE_SDK_PYTHON_TRACING_ENABLED": False},
             {"enable_tracing": True},
             False,
             False,
         ),
     ],
 )
-def test_is_signal_enabled(
-    signal_type, env_vars, client_options, default_val, expected
+def test_resolve_feature_flags(
+    feature_name, env_vars, client_options, default_val, expected
 ):
     # Setup environment variables using our test overrides
     for k, v in env_vars.items():
         set_test_env_override(k, v)
 
-    result = options.is_signal_enabled(
-        signal_type, client_options=client_options, default=default_val
+    result = options.resolve_feature_flags(
+        feature_name, client_options=client_options, default=default_val
     )
     assert result is expected
 
 
-def test_is_signal_enabled_invalid_signal():
+def test_resolve_feature_flags_invalid_signal():
     with pytest.raises(ValueError, match="Only 'tracing' is supported"):
-        options.is_signal_enabled("metrics")
+        options.resolve_feature_flags("metrics")
+
+
+def test_resolve_feature_flags_experimental_gate_blocks_provider():
+    """Verify that programmatic provider is blocked for experimental features without env var."""
+    # Assume 'tracing' is experimental for this test.
+    # We pass tracer_provider but do NOT set GOOGLE_SDK_EXPERIMENTAL_PYTHON_TRACING_ENABLED
+    client_options = {"tracer_provider": object()}
+
+    with pytest.raises(ValueError, match="Experimental feature"):
+        options.resolve_feature_flags("tracing", client_options=client_options)