feat(api-core): implement OtelUnaryClientInterceptor and feature gating

Refactored OtelSpanEnricher to OtelUnaryClientInterceptor to act as a span creator (Pure API approach). Integrated feature gating helpers to control tracing. Added dynamic attribute extraction from gRPC metadata. Cleaned up dead code and added samples.

Author: chalmerlowe

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

@@ -1,22 +1,9 @@
-from .options import (
-    clear_test_env_overrides,
-    is_signal_enabled,
-    set_test_env_override,
-)
-
 try:
     # Tell flake8 that it's okay this is unused, it's just being exposed to the package namespace.
-    from .tracing import OtelSpanEnricher  # noqa: F401
+    from .tracing import OtelUnaryClientInterceptor  # noqa: F401
 
     __all__ = [
-        "is_signal_enabled",
-        "set_test_env_override",
-        "clear_test_env_overrides",
-        "OtelSpanEnricher",
+        "OtelUnaryClientInterceptor",
     ]
 except ImportError:
-    __all__ = [
-        "is_signal_enabled",
-        "set_test_env_override",
-        "clear_test_env_overrides",
-    ]
+    __all__ = []

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

@@ -20,56 +20,77 @@
 from opentelemetry import trace
 
 
-class OtelSpanEnricher(grpc.UnaryUnaryClientInterceptor):
-    """A gRPC client interceptor that enriches the active OpenTelemetry span.
+class OtelUnaryClientInterceptor(grpc.UnaryUnaryClientInterceptor):
+    """A gRPC client interceptor that creates OpenTelemetry spans for outgoing requests.
 
-    This interceptor relies on the standard OpenTelemetry gRPC instrumentor
-    to create the baseline span. It runs in the interceptor chain to inject
-    additional Google Cloud specific domain attributes.
+    This interceptor explicitly creates a standard SpanKind.CLIENT span for each network attempt
+    and enriches it with standard Google Cloud attributes.
     """
 
     def __init__(
         self,
         static_attributes: Optional[Dict[str, Any]] = None,
-        attribute_extractor: Optional[
-            Callable[[Any, grpc.ClientCallDetails], Dict[str, Any]]
-        ] = None,
     ):
-        """Initializes the OtelSpanEnricher.
+        """Initializes the OtelUnaryClientInterceptor.
 
         Args:
             static_attributes: Standard static attributes to attach to every span.
                 E.g. {"gcp.client.repo": "googleapis/google-cloud-python"}
-            attribute_extractor: A callable that extracts dynamic attributes from
-                the request and client call details.
         """
         self._static_attributes = static_attributes or {}
-        self._attribute_extractor = attribute_extractor
 
     def intercept_unary_unary(
         self,
         continuation: Callable[[grpc.ClientCallDetails, Any], Any],
         client_call_details: grpc.ClientCallDetails,
         request: Any,
     ) -> Any:
-        span = trace.get_current_span()
-
-        if span.is_recording():
-            # Inject static attributes
-            for key, val in self._static_attributes.items():
-                span.set_attribute(key, val)
-
-            # Extract and inject dynamic attributes
-            if self._attribute_extractor:
-                try:
-                    dynamic_attrs = self._attribute_extractor(
-                        request, client_call_details
-                    )
-                    for key, val in dynamic_attrs.items():
-                        if val is not None:
-                            span.set_attribute(key, val)
-                except Exception:
-                    # Prevent custom extractor exceptions from failing the RPC
-                    pass
-
-        return continuation(client_call_details, request)
+        from google.api_core._feature_gating_helpers import resolve_feature_flags
+
+        # For now, we only check environment variables as we don't have access to ClientOptions here.
+        # To support programmatic configuration, we would need to pass it during Client
+        # initialization.
+        # TODO: we need to refactor resolve_feature_flags to allows feature_key to be optional.
+        enabled = resolve_feature_flags(
+            env_var="GOOGLE_CLOUD_PYTHON_TRACING_ENABLED",
+            feature_key="tracer_provider",
+        )
+
+        if not enabled:
+            return continuation(client_call_details, request)
+
+        tracer = trace.get_tracer(__name__)
+
+        # Determine span name (e.g., from client_call_details.method)
+        span_name = client_call_details.method
+
+        with tracer.start_as_current_span(
+            span_name, kind=trace.SpanKind.CLIENT
+        ) as span:
+            if span.is_recording():
+                # Inject static attributes
+                for key, val in self._static_attributes.items():
+                    span.set_attribute(key, val)
+
+                # Extract dynamic attributes from metadata
+                for key, value in client_call_details.metadata:
+                    if key == "x-goog-request-params":
+                        try:
+                            # x-goog-request-params is urlencoded string of key=value pairs separated by &
+                            params = dict(
+                                p.split("=") for p in value.split("&") if "=" in p
+                            )
+
+                            # Standard resource identifiers are usually in 'name' or 'parent'
+                            resource_id = params.get("name") or params.get("parent")
+                            if resource_id:
+                                span.set_attribute(
+                                    "gcp.resource.destination.id", resource_id
+                                )
+                        except Exception:
+                            # Fail open if parsing fails to avoid breaking the request
+                            pass
+
+                span.set_attribute("rpc.system.name", "grpc")
+
+            return continuation(client_call_details, request)

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

@@ -0,0 +1,52 @@
+import os
+
+from google.cloud import translate_v3
+from google.cloud.translate_v3.types import translation_service
+
+# 🚀 1. ACTIVATE MONKEY PATCHING (Auto-Instrumentation)
+# This reaches into the gRPC library and wraps standard functions dynamically.
+from opentelemetry.instrumentation.grpc import GrpcInstrumentorClient
+
+GrpcInstrumentorClient().instrument()
+print("✅ gRPC Client Auto-Instrumentation activated!")
+
+# 2. Standard OTel SDK Setup (Same as before, so we can see the console output)
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
+
+print("Initializing TracerProvider...")
+provider = TracerProvider()
+exporter = ConsoleSpanExporter()
+provider.add_span_processor(SimpleSpanProcessor(exporter))
+trace.set_tracer_provider(provider)
+print("TracerProvider initialized.")
+
+# 3. Instantiate Client (Standard GAPIC, NO manual instrumentation used here)
+print("Instantiating TranslationServiceClient...")
+client = translate_v3.TranslationServiceClient()
+print("TranslationServiceClient instantiated.")
+
+# 4. Create Request
+project_id = os.environ.get("GOOGLE_CLOUD_PROJECT", "callovian")
+parent = f"projects/{project_id}/locations/global"
+
+request = translation_service.TranslateTextRequest(
+    contents=["Hello, world!", "OpenTelemetry is braw!"],
+    target_language_code="es",
+    source_language_code="en",
+    model=f"{parent}/models/general/nmt",
+    mime_type="text/plain",
+    parent=parent,
+)
+
+# 5. Call API
+print("Sending translate request...")
+try:
+    response = client.translate_text(request)
+    print("Translation Response received.")
+    print(f"Translated text: {response.translations[0].translated_text}")
+except Exception as e:
+    print(f"API Call failed: {e}")
+
+print("Done. Check console output for traces.")

packages/google-api-core/samples/sample_auto_translate_trace.py

@@ -0,0 +1,41 @@
+import os
+
+from google.cloud import translate_v3
+from google.cloud.translate_v3.types import translation_service
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
+
+# 1. Setup OTel with Console Exporter
+provider = TracerProvider()
+exporter = ConsoleSpanExporter()
+provider.add_span_processor(SimpleSpanProcessor(exporter))
+trace.set_tracer_provider(provider)
+
+# 2. Instantiate Client
+# Using standard Application Default Credentials (ADC).
+client = translate_v3.TranslationServiceClient()
+
+# 3. Create Request
+project_id = os.environ.get("GOOGLE_CLOUD_PROJECT", "callovian")
+parent = f"projects/{project_id}/locations/global"
+
+request = translation_service.TranslateTextRequest(
+    contents=["Hello, world!", "OpenTelemetry is braw!"],
+    target_language_code="es",
+    source_language_code="en",
+    model=f"{parent}/models/general/nmt",
+    mime_type="text/plain",
+    parent=parent,
+)
+
+# 4. Call API
+print("Sending translate request...")
+try:
+    response = client.translate_text(request)
+    print("Translation Response received.")
+    print(f"Translated text: {response.translations[0].translated_text}")
+except Exception as e:
+    print(f"API Call failed (expected if no real credentials): {e}")
+
+print("Done. Check console output for traces.")