feat: add tracing support

.pylintrc

@@ -60,19 +60,14 @@ confidence=
 # --enable=similarities". If you want to run only the classes checker, but have
 # no Warning level messages displayed, use "--disable=all --enable=classes
 # --disable=W".
-disable=long-suffix,
-        old-ne-operator,
-        old-octal-literal,
-        non-ascii-bytes-literal,
-        raw-checker-failed,
+disable=raw-checker-failed,
         bad-inline-option,
         locally-disabled,
         file-ignored,
         suppressed-message,
         useless-suppression,
         deprecated-pragma,
         use-symbolic-message-instead,
-        eq-without-hash,
         too-few-public-methods,
         missing-module-docstring,
         missing-class-docstring,

kiota_http/_exceptions.py

@@ -0,0 +1,21 @@
+"""Exceptions raised in Kiota HTTP."""
+
+
+class KiotaHTTPXError(Exception):
+    """Base class for Kiota HTTP exceptions."""
+
+
+class BackingStoreError(KiotaHTTPXError):
+    """Raised for the backing store."""
+
+
+class DeserializationError(KiotaHTTPXError):
+    """Raised for deserialization."""
+
+
+class RequestError(KiotaHTTPXError):
+    """Raised for request building errors."""
+
+
+class RedirectError(KiotaHTTPXError):
+    """Raised when a redirect has errors."""

kiota_http/middleware/middleware.py

@@ -1,8 +1,15 @@
 import ssl
+from typing import Optional
 
 import httpx
+from opentelemetry import trace
 from urllib3 import PoolManager
 
+from .._version import VERSION
+from ..observability_options import ObservabilityOptions
+
+tracer = trace.get_tracer(ObservabilityOptions.get_tracer_instrumentation_name(), VERSION)
+
 
 class MiddlewarePipeline():
     """MiddlewarePipeline, entry point of middleware
@@ -45,6 +52,7 @@ class BaseMiddleware():
 
     def __init__(self):
         self.next = None
+        self.parent_span = None
 
     async def send(self, request, transport):
         if self.next is None:
@@ -55,3 +63,16 @@ async def send(self, request, transport):
             response.request = request
             return response
         return await self.next.send(request, transport)
+
+    def _create_observability_span(self, request, span_name: str) -> trace.Span:
+        """Gets the parent_span from the request options and creates a new span.
+        If no parent_span is found, we try to get the current span."""
+        _span = None
+        if options := getattr(request, "options", None):
+            if parent_span := options.get("parent_span", None):
+                self.parent_span = parent_span
+                _context = trace.set_span_in_context(parent_span)
+                _span = tracer.start_span(span_name, _context)
+        if _span is None:
+            _span = trace.get_current_span()
+        return _span

kiota_http/middleware/parameters_name_decoding_handler.py

@@ -6,6 +6,8 @@
 from .middleware import BaseMiddleware
 from .options import ParametersNameDecodingHandlerOption
 
+PARAMETERS_NAME_DECODING_KEY = "com.microsoft.kiota.handler.parameters_name_decoding.enable"
+
 
 class ParametersNameDecodingHandler(BaseMiddleware):
 
@@ -25,7 +27,7 @@ def __init__(
 
     async def send(
         self, request: httpx.Request, transport: httpx.AsyncBaseTransport
-    ) -> httpx.Response:  #type: ignore
+    ) -> httpx.Response:  # type: ignore
         """To execute the current middleware
 
         Args:
@@ -36,8 +38,12 @@ async def send(
             Response: The response object.
         """
         current_options = self._get_current_options(request)
+        span = self._create_observability_span(request, "ParametersNameDecodingHandler_send")
+        if current_options.enabled:
+            span.set_attribute(PARAMETERS_NAME_DECODING_KEY, current_options.enabled)
+        span.end()
 
-        updated_url: str = str(request.url)  #type: ignore
+        updated_url: str = str(request.url)  # type: ignore
         if all(
             [
                 current_options, current_options.enabled, '%' in updated_url,
@@ -59,7 +65,14 @@ def _get_current_options(self, request: httpx.Request) -> ParametersNameDecoding
         Returns:
             ParametersNameDecodingHandlerOption: The options to used.
         """
-        current_options =request.options.get( # type:ignore
-            ParametersNameDecodingHandlerOption.get_key(), self.options
-        )
+        if options := getattr(request, 'options', None):
+            current_options = options.get(  # type:ignore
+                ParametersNameDecodingHandlerOption.get_key(), self.options
+            )
         return current_options
+
+    def decode_uri_encoded_string(self, original: str) -> str:
+        """Decodes a uri encoded string ."""
+        if original and '%' in original:
+            return unquote(original)
+        return original

kiota_http/middleware/redirect_handler.py

@@ -2,10 +2,15 @@
 
 import httpx
 from kiota_abstractions.request_option import RequestOption
+from opentelemetry.semconv.trace import SpanAttributes
 
+from .._exceptions import RedirectError
 from .middleware import BaseMiddleware
 from .options import RedirectHandlerOption
 
+REDIRECT_ENABLE_KEY = "com.microsoft.kiota.handler.redirect.enable"
+REDIRECT_COUNT_KEY = "com.microsoft.kiota.handler.redirect.count"
+
 
 class RedirectHandler(BaseMiddleware):
     """Middlware that allows us to define the redirect policy for all requests
@@ -59,23 +64,32 @@ async def send(
         """Sends the http request object to the next middleware or redirects
         the request if necessary.
         """
+        _enable_span = self._create_observability_span(request, "RedirectHandler_send")
         current_options = self._get_current_options(request)
+        _enable_span.set_attribute(REDIRECT_ENABLE_KEY, True)
+        _enable_span.end()
 
         retryable = True
+        _redirect_span = self._create_observability_span(
+            request, f"RedirectHandler_send - redirect {len(self.history)}"
+        )
         while retryable:
             response = await super().send(request, transport)
+            _redirect_span.set_attribute(SpanAttributes.HTTP_STATUS_CODE, response.status_code)
             redirect_location = self.get_redirect_location(response)
             if redirect_location and current_options.should_redirect:
                 current_options.max_redirect -= 1
                 retryable = self.increment(response, current_options.max_redirect)
+                _redirect_span.set_attribute(REDIRECT_COUNT_KEY, len(self.history))
                 new_request = self._build_redirect_request(request, response)
                 request = new_request
                 continue
-
             response.history = self.history
-            return response
-
-        raise Exception(f"Too many redirects. {response.history}")
+            exc = RedirectError(f"Too many redirects. {response.history}")
+            _redirect_span.record_exception(exc)
+            _redirect_span.end()
+            raise exc
+        return response
 
     def _get_current_options(self, request: httpx.Request) -> RedirectHandlerOption:
         """Returns the options to use for the request.Overries default options if

kiota_http/middleware/retry_handler.py

@@ -6,6 +6,7 @@
 
 import httpx
 from kiota_abstractions.request_option import RequestOption
+from opentelemetry.semconv.trace import SpanAttributes
 
 from .middleware import BaseMiddleware
 from .options import RetryHandlerOption
@@ -66,36 +67,43 @@ async def send(self, request: httpx.Request, transport: httpx.AsyncBaseTransport
         """
         Sends the http request object to the next middleware or retries the request if necessary.
         """
-        current_options = self._get_current_options(request)
         response = None
         retry_count = 0
-        retry_valid = current_options.should_retry
 
+        _span = self._create_observability_span(request, "RetryHandler_send")
+        current_options = self._get_current_options(request)
+        _span.set_attribute("com.microsoft.kiota.handler.retry.enable", True)
+        _span.end()
+        retry_valid = current_options.should_retry
+        _retry_span = self._create_observability_span(
+            request, f"RetryHandler_send - attempt {retry_count}"
+        )
         while retry_valid:
             start_time = time.time()
-            if retry_count > 0:
-                request.headers.update({'retry-attempt': f'{retry_count}'})
             response = await super().send(request, transport)
-            # Check if the request needs to be retried based on the response method
-            # and status code
-            if self.should_retry(request, current_options, response):
-                # check that max retries has not been hit
-                retry_valid = self.check_retry_valid(retry_count, current_options)
-
-                # Get the delay time between retries
-                delay = self.get_delay_time(retry_count, response)
+            _retry_span.set_attribute(SpanAttributes.HTTP_STATUS_CODE, response.status_code)
+            # check that max retries has not been hit
+            retry_valid = self.check_retry_valid(retry_count, current_options)
 
-                if retry_valid and delay < current_options.max_delay:
-                    time.sleep(delay)
-                    end_time = time.time()
-                    current_options.max_delay -= (end_time - start_time)
-                    # increment the count for retries
-                    retry_count += 1
+            # Get the delay time between retries
+            delay = self.get_delay_time(retry_count, response)
 
-                    continue
+            # Check if the request needs to be retried based on the response method
+            # and status code
+            should_retry = self.should_retry(request, current_options, response)
+            if all([should_retry, retry_valid, delay < current_options.max_delay]):
+                time.sleep(delay)
+                end_time = time.time()
+                current_options.max_delay -= (end_time - start_time)
+                # increment the count for retries
+                retry_count += 1
+                request.headers.update({'retry-attempt': f'{retry_count}'})
+                _retry_span.set_attribute(SpanAttributes.HTTP_RETRY_COUNT, retry_count)
+                continue
             break
         if response is None:
             response = await super().send(request, transport)
+        _retry_span.end()
         return response
 
     def _get_current_options(self, request: httpx.Request) -> RetryHandlerOption:

kiota_http/middleware/url_replace_handler.py

@@ -1,5 +1,6 @@
 import httpx
 from kiota_abstractions.request_option import RequestOption
+from opentelemetry.semconv.trace import SpanAttributes
 
 from .middleware import BaseMiddleware
 from .options import UrlReplaceHandlerOption
@@ -20,7 +21,7 @@ def __init__(self, options: RequestOption = UrlReplaceHandlerOption()):
 
     async def send(
         self, request: httpx.Request, transport: httpx.AsyncBaseTransport
-    ) -> httpx.Response:  #type: ignore
+    ) -> httpx.Response:  # type: ignore
         """To execute the current middleware
 
         Args:
@@ -30,12 +31,18 @@ async def send(
         Returns:
             Response: The response object.
         """
-        current_options = self._get_current_options(request)
+        response = None
+        _enable_span = self._create_observability_span(request, "UrlReplaceHandler_send")
+        if self.options and self.options.is_enabled:
+            _enable_span.set_attribute("com.microsoft.kiota.handler.url_replacer.enable", True)
+            current_options = self._get_current_options(request)
 
-        url_string: str = str(request.url)  #type: ignore
-        url_string = self.replace_url_segment(url_string, current_options)
-        request.url = httpx.URL(url_string)
+            url_string: str = str(request.url)  # type: ignore
+            url_string = self.replace_url_segment(url_string, current_options)
+            request.url = httpx.URL(url_string)
+            _enable_span.set_attribute(SpanAttributes.HTTP_URL, str(request.url))
         response = await super().send(request, transport)
+        _enable_span.end()
         return response
 
     def _get_current_options(self, request: httpx.Request) -> UrlReplaceHandlerOption:
@@ -48,7 +55,7 @@ def _get_current_options(self, request: httpx.Request) -> UrlReplaceHandlerOptio
         Returns:
             UrlReplaceHandlerOption: The options to be used.
         """
-        current_options =request.options.get(  # type:ignore
+        current_options = request.options.get(  # type:ignore
             UrlReplaceHandlerOption.get_key(), self.options
         )
         return current_options

kiota_http/middleware/user_agent_handler.py

@@ -1,5 +1,6 @@
 from httpx import AsyncBaseTransport, Request, Response
 from kiota_abstractions.request_option import RequestOption
+from opentelemetry.semconv.trace import SpanAttributes
 
 from .middleware import BaseMiddleware
 from .options import UserAgentHandlerOption
@@ -19,14 +20,19 @@ async def send(self, request: Request, transport: AsyncBaseTransport) -> Respons
         Checks if the request has a User-Agent header and updates it if the
         platform config allows.
         """
+        _span = self._create_observability_span(request, "UserAgentHandler_send")
         if self.options and self.options.is_enabled:
+            _span.set_attribute("com.microsoft.kiota.handler.useragent.enable", True)
             value = f"{self.options.product_name}/{self.options.product_version}"
-
-            user_agent = request.headers.get("User-Agent", "")
-            if not user_agent:
-                request.headers.update({"User-Agent": value})
-            else:
-                if value not in user_agent:
-                    request.headers.update({"User-Agent": f"{user_agent} {value}"})
-
+            self._update_user_agent(request, value)
+        _span.end()
         return await super().send(request, transport)
+
+    def _update_user_agent(self, request: Request, value: str):
+        """Updates the values of the User-Agent header."""
+        user_agent = request.headers.get("User-Agent", "")
+        if not user_agent:
+            request.headers.update({"User-Agent": value})
+        else:
+            if value not in user_agent:
+                request.headers.update({"User-Agent": f"{user_agent} {value}"})

kiota_http/observability_options.py

@@ -0,0 +1,48 @@
+"""Observability options for python http package."""
+from kiota_abstractions.request_option import RequestOption
+
+
+class ObservabilityOptions(RequestOption):
+    """Defines the metrics, tracing and logging configurations."""
+    OBSERVABILITY_OPTION_KEY = "ObservabilityOptionKey"
+
+    def __init__(self, enabled: bool = True, include_euii_attributes: bool = True) -> None:
+        """Initialize the observability options.
+
+        Args:
+            enabled(bool): whether to enable the ObservabilityOptions in the middleware chain.
+            include_euii_attributes(bool): whether to include attributes that
+                could contain EUII information likr URLS.
+        """
+        self._enabled = enabled
+        self._include_euii_attributes = include_euii_attributes
+
+    @property
+    def enabled(self) -> bool:
+        """Gets the enabled option value."""
+        return self._enabled
+
+    @enabled.setter
+    def enabled(self, value: bool):
+        """sets whether to enable ObservabilityOptions in the middleware chain."""
+        self._enabled = value
+
+    @property
+    def include_euii_attributes(self) -> bool:
+        """Returns whether to include EUII attributes."""
+        return self._include_euii_attributes
+
+    @include_euii_attributes.setter
+    def include_euii_attributes(self, value: bool) -> None:
+        """Sets whether to include EUII attributes."""
+        self._include_euii_attributes = value
+
+    @staticmethod
+    def get_key() -> str:
+        """The middleware key name."""
+        return ObservabilityOptions.OBSERVABILITY_OPTION_KEY
+
+    @staticmethod
+    def get_tracer_instrumentation_name() -> str:
+        """Returns the instrumentation name used for tracing"""
+        return "com.microsoft.com:microsoft-kiota-http-httpx"