Merge pull request #74 from microsoftgraph/feat/telemetry-handler

Feat/telemetry handler

Author: samwelkanda

README.md

@@ -61,6 +61,11 @@ print(result.json())
 
 For more information on how to use the package, refer to the [samples](https://github.com/microsoftgraph/msgraph-sdk-python-core/tree/dev/samples).
 
+
+## Telemetry Metadata
+
+This library captures metadata by default that provides insights into its usage and helps to improve the developer experience. This metadata includes the `SdkVersion`, `RuntimeEnvironment` and `HostOs` on which the client is running.
+
 ## Issues
 
 View or log issues on the [Issues](https://github.com/microsoftgraph/msgraph-sdk-python-core/issues) tab in the repo.

msgraph/core/_client_factory.py

@@ -12,6 +12,7 @@
 from .middleware.authorization import AuthorizationHandler
 from .middleware.middleware import BaseMiddleware, MiddlewarePipeline
 from .middleware.retry import RetryHandler
+from .middleware.telemetry import TelemetryHandler
 
 
 class HTTPClientFactory:
@@ -53,6 +54,7 @@ def create_with_default_middleware(self, credential: TokenCredential, **kwargs)
         middleware = [
             AuthorizationHandler(credential, **kwargs),
             RetryHandler(**kwargs),
+            TelemetryHandler(),
         ]
         self._register(middleware)
         return self.session

msgraph/core/middleware/middleware.py

@@ -12,20 +12,22 @@
 
 class MiddlewarePipeline(HTTPAdapter):
     """MiddlewarePipeline, entry point of middleware
-
     The pipeline is implemented as a linked-list, read more about
     it here https://buffered.dev/middleware-python-requests/
     """
     def __init__(self):
         super().__init__()
-        self._middleware = None
+        self._current_middleware = None
+        self._first_middleware = None
         self.poolmanager = PoolManager(ssl_version=ssl.PROTOCOL_TLSv1_2)
 
     def add_middleware(self, middleware):
         if self._middleware_present():
-            self._middleware.next = middleware
+            self._current_middleware.next = middleware
+            self._current_middleware = middleware
         else:
-            self._middleware = middleware
+            self._first_middleware = middleware
+            self._current_middleware = self._first_middleware
 
     def send(self, request, **kwargs):
 
@@ -34,12 +36,12 @@ def send(self, request, **kwargs):
             request.context = RequestContext(dict(), headers)
 
         if self._middleware_present():
-            return self._middleware.send(request, **kwargs)
+            return self._first_middleware.send(request, **kwargs)
         # No middleware in pipeline, call superclass' send
         return super().send(request, **kwargs)
 
     def _middleware_present(self):
-        return self._middleware
+        return self._current_middleware
 
 
 class BaseMiddleware(HTTPAdapter):

msgraph/core/middleware/options/retry_middleware_options.py

@@ -1,10 +1,10 @@
 import datetime
 import random
-import sys
 import time
 from email.utils import parsedate_to_datetime
 
-from msgraph.core.middleware.middleware import BaseMiddleware
+from .._enums import FeatureUsageFlag
+from .middleware import BaseMiddleware
 
 
 class RetryHandler(BaseMiddleware):

msgraph/core/middleware/retry.py

@@ -0,0 +1,85 @@
+import platform
+
+from urllib3.util import parse_url
+
+from .._constants import SDK_VERSION
+from .._enums import NationalClouds
+from .middleware import BaseMiddleware
+
+
+class TelemetryHandler(BaseMiddleware):
+    """Middleware component that attaches metadata to a Graph request in order to help
+    the SDK team improve the developer experience.
+    """
+    def send(self, request, **kwargs):
+
+        if self.is_graph_url(request.url):
+            self._add_client_request_id_header(request)
+            self._append_sdk_version_header(request)
+            self._add_host_os_header(request)
+            self._add_runtime_environment_header(request)
+
+        response = super().send(request, **kwargs)
+        return response
+
+    def is_graph_url(self, url):
+        """Check if the request is made to a graph endpoint. We do not add telemetry headers to
+        non-graph endpoints"""
+        endpoints = set(item.value for item in NationalClouds)
+
+        base_url = parse_url(url)
+        endpoint = "{}://{}".format(
+            base_url.scheme,
+            base_url.netloc,
+        )
+        return endpoint in endpoints
+
+    def _add_client_request_id_header(self, request) -> None:
+        """Add a client-request-id header with GUID value to request"""
+        request.headers.update(
+            {'client-request-id': '{}'.format(request.context.client_request_id)}
+        )
+
+    def _append_sdk_version_header(self, request) -> None:
+        """Add SdkVersion request header to each request to identify the language and
+        version of the client SDK library(s).
+        Also adds the featureUsage value.
+        """
+        if 'sdkVersion' in request.headers:
+            sdk_version = request.headers.get('sdkVersion')
+            if not sdk_version == f'graph-python-core/{SDK_VERSION} '\
+                f'(featureUsage={request.context.feature_usage})':
+                request.headers.update(
+                    {
+                        'sdkVersion':
+                        f'graph-python-core/{SDK_VERSION},{ sdk_version} '\
+                        f'(featureUsage={request.context.feature_usage})'
+                    }
+                )
+        else:
+            request.headers.update(
+                {
+                    'sdkVersion':
+                    f'graph-python-core/{SDK_VERSION} '\
+                    f'(featureUsage={request.context.feature_usage})'
+                }
+            )
+
+    def _add_host_os_header(self, request) -> None:
+        """
+        Add HostOS request header to each request to help identify the OS
+        on which our client SDK is running on
+        """
+        system = platform.system()
+        version = platform.version()
+        host_os = f'{system} {version}'
+        request.headers.update({'HostOs': host_os})
+
+    def _add_runtime_environment_header(self, request) -> None:
+        """
+        Add RuntimeEnvironment request header to capture the runtime framework
+         on which the client SDK is running on.
+        """
+        python_version = platform.python_version()
+        runtime_environment = f'Python/{python_version}'
+        request.headers.update({'RuntimeEnvironment': runtime_environment})

msgraph/core/middleware/telemetry.py

@@ -0,0 +1,72 @@
+import platform
+import re
+import uuid
+
+import pytest
+
+from msgraph.core import SDK_VERSION, APIVersion, GraphClient, NationalClouds
+
+BASE_URL = NationalClouds.Global + '/' + APIVersion.v1
+
+
+@pytest.fixture
+def graph_client():
+    scopes = ['user.read']
+    credential = _CustomTokenCredential()
+    client = GraphClient(credential=credential, scopes=scopes)
+    return client
+
+
+class _CustomTokenCredential:
+    def get_token(self, scopes):
+        return ['{token:https://graph.microsoft.com/}']
+
+
+def test_telemetry_handler(graph_client):
+    """
+    Test telemetry handler updates the graph request with the requisite headers
+    """
+    response = graph_client.get('https://graph.microsoft.com/v1.0/me')
+    system = platform.system()
+    version = platform.version()
+    host_os = f'{system} {version}'
+    python_version = platform.python_version()
+    runtime_environment = f'Python/{python_version}'
+
+    assert response.status_code == 401
+    assert response.request.headers["client-request-id"]
+    assert response.request.headers["sdkVersion"].startswith('graph-python-core/' + SDK_VERSION)
+    assert response.request.headers["HostOs"] == host_os
+    assert response.request.headers["RuntimeEnvironment"] == runtime_environment
+
+
+def test_telemetry_handler_non_graph_url(graph_client):
+    """
+    Test telemetry handler does not updates the request headers for non-graph requests
+    """
+    response = graph_client.get('https://httpbin.org/status/200')
+
+    assert response.status_code == 200
+    with pytest.raises(KeyError):
+        response.request.headers["client-request-id"]
+        response.request.headers["sdkVersion"]
+        response.request.headers["HostOs"]
+        response.request.headers["RuntimeEnvironment"]
+
+
+def test_custom_client_request_id(graph_client):
+    """
+    Test customer provided client request id overrides default value
+    """
+    custom_id = str(uuid.uuid4())
+    response = graph_client.get(
+        'https://httpbin.org/status/200', headers={"client-request-id": custom_id}
+    )
+
+    assert response.status_code == 200
+    assert response.request.context.client_request_id == custom_id
+    with pytest.raises(KeyError):
+        response.request.headers["client-request-id"]
+        response.request.headers["sdkVersion"]
+        response.request.headers["HostOs"]
+        response.request.headers["RuntimeEnvironment"]

tests/integration/test_retry_middleware.py renamed to tests/integration/test_retry.py

@@ -14,8 +14,8 @@ def test_adds_middlewares_in_order(self):
         middleware_pipeline.add_middleware(MockRequestMiddleware1())
         middleware_pipeline.add_middleware(MockRequestMiddleware2())
 
-        first_middleware = middleware_pipeline._middleware
-        second_middleware = middleware_pipeline._middleware.next
+        first_middleware = middleware_pipeline._first_middleware
+        second_middleware = middleware_pipeline._first_middleware.next
 
         self.assertIsInstance(first_middleware, MockRequestMiddleware1)
         self.assertIsInstance(second_middleware, MockRequestMiddleware2)