[Core] Tracing updates

Signed-off-by: Paul Van Eck <[email protected]>

Author: pvaneck

.vscode/cspell.json

@@ -353,6 +353,7 @@
     "onmicrosoft",
     "openai",
     "OPENAI",
+    "otel",
     "otlp",
     "OTLP",
     "owasp",

sdk/core/azure-core/CHANGELOG.md

@@ -4,12 +4,33 @@
 
 ### Features Added
 
+- Added native OpenTelemetry tracing to Azure Core which enables users to use OpenTelemetry to trace Azure SDK operations without needing to install a plugin. #39563
+    - A new `TracerProvider` class was added, allowing SDK developers to pass in various metadata to the OpenTelemetry tracer and spans.
+    - `OpenTelemetryTracer` and `OpenTelemetrySpan` classes were added to the `azure.core.tracing` namespace.
+    - A `TracingOptions` TypedDict class was added to define the options that SDK users can use to configure tracing per-operation. These options include the ability to enable or disable tracing, set additional attributes on spans, and disable recording exceptions as events on spans.
+    - The `tracing_enabled` setting on the global `settings` object is now respected and can be used to enable or disable native tracing for all SDKs.
+        - If `setting.tracing_implementation` is set, it will take precedence over the native core tracing.
+    - The `DistributedTracingPolicy` and `distributed_trace`/`distributed_trace_async` decorators now uses the OpenTelemetry tracer if it is available and enabled.
+
 ### Breaking Changes
 
+- Inside `DistributedTracingPolicy`, some tracing modifications have been made to converge with the OpenTelemetry stable HTTP semantic conventions. #39563
+    - The **span name** for HTTP requests will now be set to just the HTTP method by default (previously the path was included).
+    - The following span attributes were renamed:
+        - `http.method` -> `http.request.method`
+        - `http.url` -> `url.full`
+        - `http.status_code` -> `http.response.status_code`
+        - `http.user_agent` -> `user_agent.original`
+        - `net.peer.name` -> `server.address`
+        - `net.peer.port` -> `server.port`
+- Removed automatic tracing enablement for the OpenTelemetry plugin if `opentelemetry` was imported. #39563
+
 ### Bugs Fixed
 
 ### Other Changes
 
+- Added `opentelemetry-api` as an optional dependency for tracing. #39563
+
 ## 1.32.0 (2024-10-31)
 
 ### Features Added

sdk/core/azure-core/azure/core/pipeline/policies/_distributed_tracing.py

@@ -39,11 +39,14 @@
 from azure.core.rest import HttpResponse, HttpRequest
 from azure.core.settings import settings
 from azure.core.tracing import SpanKind
+from ...tracing._tracer import default_tracer_provider, TracerProvider
+from ...tracing._models import TracingOptions
 
 if TYPE_CHECKING:
-    from azure.core.tracing._abstract_span import (
+    from ...tracing._abstract_span import (
         AbstractSpan,
     )
+    from ...tracing.opentelemetry_span import OpenTelemetrySpan
 
 HTTPResponseType = TypeVar("HTTPResponseType", HttpResponse, LegacyHttpResponse)
 HTTPRequestType = TypeVar("HTTPRequestType", HttpRequest, LegacyHttpRequest)
@@ -61,10 +64,7 @@ def _default_network_span_namer(http_request: HTTPRequestType) -> str:
     :returns: The string to use as network span name
     :rtype: str
     """
-    path = urllib.parse.urlparse(http_request.url).path
-    if not path:
-        path = "/"
-    return path
+    return http_request.method
 
 
 class DistributedTracingPolicy(SansIOHTTPPolicy[HTTPRequestType, HTTPResponseType]):
@@ -77,35 +77,91 @@ class DistributedTracingPolicy(SansIOHTTPPolicy[HTTPRequestType, HTTPResponseTyp
     """
 
     TRACING_CONTEXT = "TRACING_CONTEXT"
+
+    # Current HTTP semantic conventions
+    _HTTP_RESEND_COUNT = "http.request.resend_count"
+    _USER_AGENT_ORIGINAL = "user_agent.original"
+    _HTTP_REQUEST_METHOD = "http.request.method"
+    _URL_FULL = "url.full"
+    _HTTP_RESPONSE_STATUS_CODE = "http.response.status_code"
+    _SERVER_ADDRESS = "server.address"
+    _SERVER_PORT = "server.port"
+    _ERROR_TYPE = "error.type"
+
+    # Legacy HTTP semantic conventions
+    _HTTP_USER_AGENT = "http.user_agent"
+    _HTTP_METHOD = "http.method"
+    _HTTP_URL = "http.url"
+    _HTTP_STATUS_CODE = "http.status_code"
+    _NET_PEER_NAME = "net.peer.name"
+    _NET_PEER_PORT = "net.peer.port"
+
+    # Azure attributes
     _REQUEST_ID = "x-ms-client-request-id"
     _RESPONSE_ID = "x-ms-request-id"
-    _HTTP_RESEND_COUNT = "http.request.resend_count"
+    _REQUEST_ID_ATTR = "az.client_request_id"
+    _RESPONSE_ID_ATTR = "az.service_request_id"
 
-    def __init__(self, **kwargs: Any):
+    def __init__(self, *, tracer_provider: Optional[TracerProvider] = None, **kwargs: Any):
         self._network_span_namer = kwargs.get("network_span_namer", _default_network_span_namer)
         self._tracing_attributes = kwargs.get("tracing_attributes", {})
+        self._tracer_provider = tracer_provider
 
     def on_request(self, request: PipelineRequest[HTTPRequestType]) -> None:
         ctxt = request.context.options
         try:
-            span_impl_type = settings.tracing_implementation()
-            if span_impl_type is None:
+            tracing_options: TracingOptions = ctxt.pop("tracing_options", {})
+            tracing_enabled = settings.tracing_enabled()
+
+            # User can explicitly disable tracing for this request.
+            user_enabled = tracing_options.get("enabled")
+            if user_enabled is False:
                 return
 
+            # If tracing is disabled globally and user didn't explicitly enable it, don't trace.
+            if not tracing_enabled and user_enabled is None:
+                return
+
+            span_impl_type = settings.tracing_implementation()
             namer = ctxt.pop("network_span_namer", self._network_span_namer)
             tracing_attributes = ctxt.pop("tracing_attributes", self._tracing_attributes)
             span_name = namer(request.http_request)
 
-            span = span_impl_type(name=span_name, kind=SpanKind.CLIENT)
-            for attr, value in tracing_attributes.items():
-                span.add_attribute(attr, value)
-            span.start()
+            span_attributes = {**tracing_attributes, **tracing_options.get("attributes", {})}
+
+            if span_impl_type:
+                # If the plugin is enabled, prioritize it over the core tracing.
+                span = span_impl_type(name=span_name, kind=SpanKind.CLIENT)
+                for attr, value in span_attributes.items():
+                    span.add_attribute(attr, value)  # type: ignore
 
-            headers = span.to_header()
-            request.http_request.headers.update(headers)
+                headers = span.to_header()
+                request.http_request.headers.update(headers)
+
+                request.context[self.TRACING_CONTEXT] = span
+            else:
+                # Otherwise, use the core tracing.
+                tracer = (
+                    self._tracer_provider.get_tracer()
+                    if self._tracer_provider
+                    else default_tracer_provider.get_tracer()
+                )
+                if not tracer:
+                    return
+
+                core_span = tracer.start_span(
+                    name=span_name,
+                    kind=SpanKind.CLIENT,
+                    attributes=span_attributes,
+                    record_exception=tracing_options.get("record_exception", True),
+                )
+
+                trace_context_headers = tracer.get_trace_context()
+                request.http_request.headers.update(trace_context_headers)
+                request.context[self.TRACING_CONTEXT] = core_span
 
-            request.context[self.TRACING_CONTEXT] = span
         except Exception as err:  # pylint: disable=broad-except
+            print(err)
             _LOGGER.warning("Unable to start network span: %s", err)
 
     def end_span(
@@ -126,21 +182,26 @@ def end_span(
         if self.TRACING_CONTEXT not in request.context:
             return
 
-        span: "AbstractSpan" = request.context[self.TRACING_CONTEXT]
+        span = request.context[self.TRACING_CONTEXT]
         http_request: Union[HttpRequest, LegacyHttpRequest] = request.http_request
         if span is not None:
-            span.set_http_attributes(http_request, response=response)
+            self._set_http_attributes(span, request=http_request, response=response)
+            set_attribute_func = (
+                getattr(span, "add_attribute") if hasattr(span, "add_attribute") else getattr(span, "set_attribute")
+            )
+            end_func = getattr(span, "finish", None) or getattr(span, "end")
+
             if request.context.get("retry_count"):
-                span.add_attribute(self._HTTP_RESEND_COUNT, request.context["retry_count"])
+                set_attribute_func(self._HTTP_RESEND_COUNT, request.context["retry_count"])
             request_id = http_request.headers.get(self._REQUEST_ID)
             if request_id is not None:
-                span.add_attribute(self._REQUEST_ID, request_id)
+                set_attribute_func(self._REQUEST_ID_ATTR, request_id)
             if response and self._RESPONSE_ID in response.headers:
-                span.add_attribute(self._RESPONSE_ID, response.headers[self._RESPONSE_ID])
+                set_attribute_func(self._RESPONSE_ID_ATTR, response.headers[self._RESPONSE_ID])
             if exc_info:
                 span.__exit__(*exc_info)
             else:
-                span.finish()
+                end_func()
 
     def on_response(
         self,
@@ -151,3 +212,43 @@ def on_response(
 
     def on_exception(self, request: PipelineRequest[HTTPRequestType]) -> None:
         self.end_span(request, exc_info=sys.exc_info())
+
+    def _set_http_attributes(
+        self,
+        span: Union["AbstractSpan", "OpenTelemetrySpan"],
+        request: Union[HttpRequest, LegacyHttpRequest],
+        response: Optional[HTTPResponseType] = None,
+    ) -> None:
+        """
+        Add correct attributes for a http client span.
+
+        :param span: The span to add attributes to.
+        :type span: ~azure.core.tracing.AbstractSpan or ~azure.core.tracing.opentelemetry_span.OpenTelemetrySpan
+        :param request: The request made
+        :type request: azure.core.rest.HttpRequest
+        :param response: The response received from the server. Is None if no response received.
+        :type response: ~azure.core.pipeline.transport.HttpResponse or ~azure.core.pipeline.transport.AsyncHttpResponse
+        """
+        set_attribute_func = (
+            getattr(span, "add_attribute") if hasattr(span, "add_attribute") else getattr(span, "set_attribute")
+        )
+
+        set_attribute_func(self._HTTP_REQUEST_METHOD, request.method)
+        set_attribute_func(self._URL_FULL, request.url)
+
+        parsed_url = urllib.parse.urlparse(request.url)
+        if parsed_url.hostname:
+            set_attribute_func(self._SERVER_ADDRESS, parsed_url.hostname)
+        if parsed_url.port and parsed_url.port not in [80, 443]:
+            set_attribute_func(self._SERVER_PORT, parsed_url.port)
+
+        user_agent = request.headers.get("User-Agent")
+        if user_agent:
+            set_attribute_func(self._USER_AGENT_ORIGINAL, user_agent)
+        if response and response.status_code:
+            set_attribute_func(self._HTTP_RESPONSE_STATUS_CODE, response.status_code)
+            if response.status_code >= 400:
+                set_attribute_func(self._ERROR_TYPE, str(response.status_code))
+        else:
+            set_attribute_func(self._HTTP_RESPONSE_STATUS_CODE, 504)
+            set_attribute_func(self._ERROR_TYPE, "504")

sdk/core/azure-core/azure/core/settings.py

@@ -30,7 +30,6 @@
 from enum import Enum
 import logging
 import os
-import sys
 from typing import (
     Type,
     Optional,
@@ -91,6 +90,24 @@ def convert_bool(value: Union[str, bool]) -> bool:
     raise ValueError("Cannot convert {} to boolean value".format(value))
 
 
+def convert_tracing_enabled(value: Optional[Union[str, bool]]) -> bool:
+    """Convert tracing value to bool with regard to tracing implementation.
+
+    :param value: the value to convert
+    :type value: str or bool or None
+    :returns: A boolean value matching the intent of the input
+    :rtype: bool
+    :raises ValueError: If conversion to bool fails
+    """
+    if value is None:
+        # If tracing_enabled was not explicitly set to a boolean, determine tracing enablement
+        # based on tracing_implementation being set.
+        if settings.tracing_implementation():
+            return True
+        return False
+    return convert_bool(value)
+
+
 _levels = {
     "CRITICAL": logging.CRITICAL,
     "ERROR": logging.ERROR,
@@ -184,18 +201,6 @@ def _get_opentelemetry_span() -> Optional[Type[AbstractSpan]]:
         return None
 
 
-def _get_opencensus_span_if_opencensus_is_imported() -> Optional[Type[AbstractSpan]]:
-    if "opencensus" not in sys.modules:
-        return None
-    return _get_opencensus_span()
-
-
-def _get_opentelemetry_span_if_opentelemetry_is_imported() -> Optional[Type[AbstractSpan]]:
-    if "opentelemetry" not in sys.modules:
-        return None
-    return _get_opentelemetry_span()
-
-
 _tracing_implementation_dict: Dict[str, Callable[[], Optional[Type[AbstractSpan]]]] = {
     "opencensus": _get_opencensus_span,
     "opentelemetry": _get_opentelemetry_span,
@@ -218,9 +223,7 @@ def convert_tracing_impl(value: Optional[Union[str, Type[AbstractSpan]]]) -> Opt
 
     """
     if value is None:
-        return (
-            _get_opentelemetry_span_if_opentelemetry_is_imported() or _get_opencensus_span_if_opencensus_is_imported()
-        )
+        return None
 
     if not isinstance(value, str):
         return value
@@ -504,11 +507,11 @@ def _config(self, props: Mapping[str, Any]) -> Tuple[Any, ...]:
         default=logging.INFO,
     )
 
-    tracing_enabled: PrioritizedSetting[Union[str, bool], bool] = PrioritizedSetting(
+    tracing_enabled: PrioritizedSetting[Optional[Union[str, bool]], bool] = PrioritizedSetting(
         "tracing_enabled",
         env_var="AZURE_TRACING_ENABLED",
-        convert=convert_bool,
-        default=False,
+        convert=convert_tracing_enabled,
+        default=None,
     )
 
     tracing_implementation: PrioritizedSetting[

sdk/core/azure-core/azure/core/tracing/__init__.py

@@ -6,7 +6,8 @@
     AbstractSpan,
     SpanKind,
     HttpSpanMixin,
-    Link,
 )
+from ._models import Link, SpanKind, StatusCode, TracingOptions
+from ._tracer import TracerProvider
 
-__all__ = ["AbstractSpan", "SpanKind", "HttpSpanMixin", "Link"]
+__all__ = ["AbstractSpan", "HttpSpanMixin", "Link", "SpanKind", "StatusCode", "TracingOptions", "TracerProvider"]