feat(observability): simplify options resolver to tracing-only

Author: chalmerlowe

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

@@ -1,8 +1,7 @@
 """Observability environment variable and client options resolution helpers."""
 
 import os
-import warnings
-from typing import Any, Dict, List, Optional, Union
+from typing import Any, Dict, Optional, Union
 
 # Allowed truthy and falsy patterns for environment variables
 _TRUTHY_VALUES = ("y", "yes", "t", "true", "on", "1")
@@ -66,15 +65,30 @@ def _get_env_bool_with_dev_fallback(name: str) -> Optional[bool]:
 
 
 def is_signal_enabled(
-    service_name: str,
     signal_type: str,
     client_options: Optional[Union[Dict[str, Any], Any]] = None,
     default: bool = False,
-    legacy_vars: Optional[List[str]] = None,
 ) -> bool:
-    """Determines if a telemetry signal is enabled."""
-    service_upper = service_name.upper().replace("-", "_")
-    signal_upper = signal_type.upper()
+    """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
+       (natively checks for an EXPERIMENTAL prefix variant first)
+    3. Default fallback
+
+    Args:
+        signal_type: The signal type: must be 'tracing'.
+        client_options: A dictionary or object representing 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":
+        raise ValueError(
+            f"Invalid signal_type: {signal_type!r}. Only 'tracing' is supported."
+        )
 
     # 1. Resolve Programmatic Options First
     if client_options is not None:
@@ -83,51 +97,14 @@ def is_signal_enabled(
             if isinstance(client_options, dict)
             else getattr(client_options, "__dict__", {})
         )
-        option_key = f"enable_{signal_type.lower()}"
-        provider_key = f"{signal_type.rstrip('s').lower()}_provider"
 
-        if options_dict.get(option_key) is not None:
-            return bool(options_dict.get(option_key))
-        if options_dict.get(provider_key) is not None:
+        if options_dict.get("tracer_provider") is not None:
             return True
 
-    # 2. Language & Service-specific
-    val = _get_env_bool_with_dev_fallback(
-        f"GOOGLE_CLOUD_PYTHON_{service_upper}_{signal_upper}_ENABLED"
-    )
-    if val is not None:
-        return val
-
-    # 3. Language-wide Global
-    val = _get_env_bool_with_dev_fallback(f"GOOGLE_CLOUD_PYTHON_{signal_upper}_ENABLED")
-    if val is not None:
-        return val
-
-    # 4. Cross-language Service-specific
-    val = _get_env_bool_with_dev_fallback(
-        f"GOOGLE_CLOUD_{service_upper}_{signal_upper}_ENABLED"
-    )
-    if val is not None:
-        return val
-
-    # 5. Cross-language Global
-    val = _get_env_bool_with_dev_fallback(f"GOOGLE_CLOUD_{signal_upper}_ENABLED")
+    # 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
 
-    # 6. Legacy Variables
-    if legacy_vars:
-        for legacy_var in legacy_vars:
-            val = _get_env_bool(legacy_var)
-            if val is not None:
-                warnings.warn(
-                    f"Environment variable {legacy_var!r} is deprecated and will be removed "
-                    "in a future release. Please migrate to the standardized "
-                    f"GOOGLE_CLOUD_PYTHON_{service_upper}_{signal_upper}_ENABLED instead.",
-                    DeprecationWarning,
-                    stacklevel=2,
-                )
-                return val
-
-    # 7. Default Fallback
+    # 3. Default Fallback
     return default

packages/google-api-core/pyproject.toml

@@ -49,7 +49,7 @@ dependencies = [
   "proto-plus >= 1.25.0, < 2.0.0; python_version >= '3.13'",
   "google-auth >= 2.14.1, < 3.0.0",
   "requests >= 2.33.0, < 3.0.0",
-  "opentelemetry-api >= 1.1.0, < 2.0.0",
+  "opentelemetry-api >= 1.27.0, < 2.0.0",
 ]
 dynamic = ["version"]
 
@@ -95,4 +95,6 @@ filterwarnings = [
   "ignore:.*custom tp_new.*in Python 3.14:DeprecationWarning",
   # Remove once https://github.com/grpc/grpc/issues/35086 is fixed (and version newer than 1.60.0 is published)
   "ignore:There is no current event loop:DeprecationWarning",
+  # Ignore external OpenTelemetry/importlib.metadata SelectableGroups warning
+  "ignore:.*SelectableGroups dict interface is deprecated:DeprecationWarning",
 ]

packages/google-api-core/testing/constraints-3.10.txt

@@ -12,4 +12,4 @@ requests==2.33.0
 grpcio==1.41.0
 grpcio-status==1.41.0
 proto-plus==1.24.0
-opentelemetry-api==1.1.0
+opentelemetry-api==1.27.0

packages/google-api-core/testing/constraints-async-rest-3.10.txt

@@ -13,4 +13,4 @@ grpcio==1.41.0
 grpcio-status==1.41.0
 proto-plus==1.24.0
 aiohttp==3.13.4
-opentelemetry-api==1.1.0
+opentelemetry-api==1.27.0

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

@@ -70,65 +70,67 @@ def test_get_env_bool(monkeypatch):
 
 
 @pytest.mark.parametrize(
-    "env_vars, client_options, default_val, expected",
+    "signal_type, env_vars, client_options, default_val, expected",
     [
         # Default fallback tests
-        ({}, None, False, False),
-        ({}, None, True, True),
-        # Service-specific env var
-        ({"GOOGLE_CLOUD_PYTHON_TRANSLATE_TRACES_ENABLED": True}, None, False, True),
-        ({"GOOGLE_CLOUD_PYTHON_TRANSLATE_TRACES_ENABLED": False}, None, True, False),
+        ("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),
         # Experimental fallback
         (
-            {"GOOGLE_CLOUD_EXPERIMENTAL_PYTHON_TRANSLATE_TRACES_ENABLED": True},
+            "tracing",
+            {"GOOGLE_CLOUD_EXPERIMENTAL_PYTHON_TRACING_ENABLED": True},
             None,
             False,
             True,
         ),
-        # Precedence: Service specific overrides global
         (
-            {
-                "GOOGLE_CLOUD_PYTHON_TRACES_ENABLED": True,
-                "GOOGLE_CLOUD_PYTHON_TRANSLATE_TRACES_ENABLED": False,
-            },
+            "tracing",
+            {"GOOGLE_CLOUD_EXPERIMENTAL_PYTHON_TRACING_ENABLED": False},
             None,
-            False,
+            True,
             False,
         ),
+        # Implicit opt-in with provider
         (
-            {
-                "GOOGLE_CLOUD_PYTHON_TRACES_ENABLED": False,
-                "GOOGLE_CLOUD_PYTHON_TRANSLATE_TRACES_ENABLED": True,
-            },
-            None,
+            "tracing",
+            {"GOOGLE_CLOUD_PYTHON_TRACING_ENABLED": False},
+            {"tracer_provider": object()},
             False,
             True,
         ),
-        # Precedence: Client options override env vars
+        # Programmatic boolean flags are NOT supported (should default/fallback)
         (
-            {"GOOGLE_CLOUD_PYTHON_TRANSLATE_TRACES_ENABLED": False},
+            "tracing",
+            {"GOOGLE_CLOUD_PYTHON_TRACING_ENABLED": False},
             {"enable_traces": True},
             False,
-            True,
+            False,
+        ),
+        (
+            "tracing",
+            {"GOOGLE_CLOUD_PYTHON_TRACING_ENABLED": False},
+            {"enable_tracing": True},
+            False,
+            False,
         ),
     ],
 )
-def test_is_signal_enabled(env_vars, client_options, default_val, expected):
+def test_is_signal_enabled(
+    signal_type, 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(
-        "translate", "traces", client_options=client_options, default=default_val
+        signal_type, client_options=client_options, default=default_val
     )
     assert result is expected
 
 
-def test_legacy_var_with_warning():
-    set_test_env_override("LEGACY_TRACE_VAR", True)
-
-    with pytest.warns(DeprecationWarning, match="LEGACY_TRACE_VAR"):
-        result = options.is_signal_enabled(
-            "translate", "traces", legacy_vars=["LEGACY_TRACE_VAR"]
-        )
-        assert result is True
+def test_is_signal_enabled_invalid_signal():
+    with pytest.raises(ValueError, match="Only 'tracing' is supported"):
+        options.is_signal_enabled("traces")