Add support for Oracle Cloud Infrastructure tracing solution by providing a tracing context

Updated test-requirements dependencies

Author: isaaclipszyc

fdk/constants.py

@@ -30,6 +30,11 @@
 FN_ID = "FN_FN_ID"
 FN_LOGFRAME_NAME = "FN_LOGFRAME_NAME"
 FN_LOGFRAME_HDR = "FN_LOGFRAME_HDR"
+FN_APP_NAME = "FN_APP_NAME"
+FN_NAME = "FN_FN_NAME"
+OCI_TRACE_COLLECTOR_URL = "OCI_TRACE_COLLECTOR_URL"
+OCI_TRACING_ENABLED = "OCI_TRACING_ENABLED"
+
 
 # headers are lower case TODO(denis): why?
 FN_INTENT = "fn-intent"
@@ -42,6 +47,11 @@
 FN_HTTP_METHOD = "fn-http-method"
 CONTENT_TYPE = "content-type"
 CONTENT_LENGTH = "content-length"
+X_B3_TRACEID = "x-b3-traceid"
+X_B3_SPANID = "x-b3-spanid"
+X_B3_PARENTSPANID = "x-b3-parentspanid"
+X_B3_SAMPLED = "x-b3-sampled"
+X_B3_FLAGS = "x-b3-flags"
 
 FN_ENFORCED_RESPONSE_CODES = [200, 502, 504]
 FN_DEFAULT_RESPONSE_CODE = 200

fdk/context.py

@@ -17,26 +17,32 @@
 import datetime as dt
 import io
 import os
-
+import random
 from fdk import constants
 from fdk import headers as hs
 from fdk import log
+from collections import namedtuple
 
 
 class InvokeContext(object):
 
-    def __init__(self, app_id, fn_id, call_id,
+    def __init__(self, app_id, app_name, fn_id, fn_name, call_id,
                  content_type="application/octet-stream",
                  deadline=None, config=None,
                  headers=None, request_url=None,
-                 method="POST", fn_format=None):
+                 method="POST", fn_format=None,
+                 tracing_context=None):
         """
         Request context here to be a placeholder
         for request-specific attributes
         :param app_id: Fn App ID
         :type app_id: str
+        :param app_name: Fn App name
+        :type app_name: str
         :param fn_id: Fn App Fn ID
         :type fn_id: str
+        :param fn_name: Fn name
+        :type fn_name: str
         :param call_id: Fn call ID
         :type call_id: str
         :param content_type: request content type
@@ -53,6 +59,8 @@ def __init__(self, app_id, fn_id, call_id,
         :type method: str
         :param fn_format: function format
         :type fn_format: str
+        :param tracing_context: tracing context
+        :type tracing_context: TracingContext
         """
         self.__app_id = app_id
         self.__fn_id = fn_id
@@ -66,6 +74,9 @@ def __init__(self, app_id, fn_id, call_id,
         self._method = method
         self.__response_headers = {}
         self.__fn_format = fn_format
+        self.__app_name = app_name
+        self.__fn_name = fn_name
+        self.__tracing_context = tracing_context if tracing_context else None
 
         log.log("request headers. gateway: {0} {1}"
                 .format(self.__is_gateway(), headers))
@@ -77,9 +88,15 @@ def __init__(self, app_id, fn_id, call_id,
     def AppID(self):
         return self.__app_id
 
+    def AppName(self):
+        return self.__app_name
+
     def FnID(self):
         return self.__fn_id
 
+    def FnName(self):
+        return self.__fn_name
+
     def CallID(self):
         return self.__call_id
 
@@ -95,6 +112,9 @@ def HTTPHeaders(self):
     def Format(self):
         return self.__fn_format
 
+    def TracingContext(self):
+        return self.__tracing_context
+
     def Deadline(self):
         if self.__deadline is None:
             now = dt.datetime.now(dt.timezone.utc).astimezone()
@@ -125,6 +145,114 @@ def __is_gateway(self):
                 == constants.INTENT_HTTP_REQUEST)
 
 
+class TracingContext(object):
+
+    def __init__(self, is_tracing_enabled, trace_collector_url,
+                 trace_id, span_id, parent_span_id,
+                 is_sampled, flags):
+        """
+        Tracing context here to be a placeholder
+        for tracing-specific attributes
+        :param is_tracing_enabled: tracing enabled flag
+        :type is_tracing_enabled: bool
+        :param trace_collector_url: APM Trace Collector Endpoint URL
+        :type trace_collector_url: str
+        :param trace_id: Trace ID
+        :type trace_id: str
+        :param span_id: Span ID
+        :type span_id: str
+        :param parent_span_id: Parent Span ID
+        :type parent_span_id: str
+        :param is_sampled: Boolean for emmitting spans
+        :type is_sampled: int (0 or 1)
+        :param flags: Debug flags
+        :type flags: int (0 or 1)
+        """
+        self.__is_tracing_enabled = is_tracing_enabled
+        self.__trace_collector_url = trace_collector_url
+        self.__trace_id = trace_id
+        self.__span_id = span_id
+        self.__parent_span_id = parent_span_id
+        self.__is_sampled = is_sampled
+        self.__flags = flags
+        self.__app_name = os.environ.get(constants.FN_APP_NAME)
+        self.__app_id = os.environ.get(constants.FN_APP_ID)
+        self.__fn_name = os.environ.get(constants.FN_NAME)
+        self.__fn_id = os.environ.get(constants.FN_ID)
+
+    def is_tracing_enabled(self):
+        return self.__is_tracing_enabled
+
+    def trace_collector_url(self):
+        return self.__trace_collector_url
+
+    def trace_id(self):
+        return self.__trace_id
+
+    def span_id(self):
+        return self.__span_id
+
+    def parent_span_id(self):
+        return self.__parent_span_id
+
+    def is_sampled(self):
+        return bool(self.__is_sampled)
+
+    def flags(self):
+        return self.__flags
+
+    # this is a helper method specific for py_zipkin
+    def zipkin_attrs(self):
+        ZipkinAttrs = namedtuple(
+            "ZipkinAttrs",
+            "trace_id, span_id, parent_span_id, is_sampled, flags"
+        )
+
+        trace_id = self.__trace_id
+        span_id = self.__span_id
+        parent_span_id = self.__parent_span_id
+        is_sampled = bool(self.__is_sampled)
+        trace_flags = self.__flags
+
+        # As the fnLb sends the parent_span_id as the span_id
+        # assign the parent span id as the span id.
+        if parent_span_id is None and span_id is not None:
+            parent_span_id = span_id
+            span_id = generate_id()
+
+        zipkin_attrs = ZipkinAttrs(
+            trace_id,
+            span_id,
+            parent_span_id,
+            is_sampled,
+            trace_flags
+        )
+        return zipkin_attrs
+
+    def service_name(self, override=None):
+        # in case of missing app and function name env variables
+        service_name = (
+            override
+            if override is not None
+            else str(self.__app_name) + "::" + str(self.__fn_name)
+        )
+        return service_name.lower()
+
+    def annotations(self):
+        annotations = {
+            "generatedBy": "faas",
+            "appName": self.__app_name,
+            "appID": self.__app_id,
+            "fnName": self.__fn_name,
+            "fnID": self.__fn_id,
+        }
+        return annotations
+
+
+def generate_id():
+    return "{:016x}".format(random.getrandbits(64))
+
+
 def context_from_format(format_def: str, **kwargs) -> (
         InvokeContext, io.BytesIO):
     """
@@ -138,27 +266,76 @@ def context_from_format(format_def: str, **kwargs) -> (
 
     app_id = os.environ.get(constants.FN_APP_ID)
     fn_id = os.environ.get(constants.FN_ID)
+    app_name = os.environ.get(constants.FN_APP_NAME)
+    fn_name = os.environ.get(constants.FN_NAME)
+    # the tracing enabled env variable is passed as a "0" or "1" string
+    # and therefore needs to be converted appropriately.
+    is_tracing_enabled = os.environ.get(constants.OCI_TRACING_ENABLED)
+    is_tracing_enabled = (
+        bool(int(is_tracing_enabled))
+        if is_tracing_enabled is not None
+        else False
+    )
+    trace_collector_url = os.environ.get(constants.OCI_TRACE_COLLECTOR_URL)
 
     if format_def == constants.HTTPSTREAM:
         data = kwargs.get("data")
         headers = kwargs.get("headers")
 
+        # zipkin tracing http headers
+        trace_id = span_id = parent_span_id = is_sampled = trace_flags = None
+        tracing_context = None
+        if is_tracing_enabled:
+            # we generate the trace_id if tracing is enabled
+            # but the traceId zipkin header is missing.
+            trace_id = headers.get(constants.X_B3_TRACEID)
+            trace_id = generate_id() if trace_id is None else trace_id
+
+            span_id = headers.get(constants.X_B3_SPANID)
+            parent_span_id = headers.get(constants.X_B3_PARENTSPANID)
+
+            # span_id is also generated if the zipkin header is missing.
+            span_id = generate_id() if span_id is None else span_id
+
+            # is_sampled should be a boolean in the form of a "0/1" but
+            # legacy samples have them as "False/True"
+            is_sampled = headers.get(constants.X_B3_SAMPLED)
+            is_sampled = int(is_sampled) if is_sampled is not None else 1
+
+            # not currently used but is defined by the zipkin headers standard
+            trace_flags = headers.get(constants.X_B3_FLAGS)
+
+        # tracing context will be an empty object
+        # if tracing is not enabled or the flag is missing.
+        # this prevents the customer code from failing if they decide to
+        # disable tracing. An empty tracing context will not
+        # emit spans due to is_sampled being None.
+        tracing_context = TracingContext(
+            is_tracing_enabled,
+            trace_collector_url,
+            trace_id,
+            span_id,
+            parent_span_id,
+            is_sampled,
+            trace_flags
+        )
+
         method = headers.get(constants.FN_HTTP_METHOD)
-        request_url = headers.get(
-            constants.FN_HTTP_REQUEST_URL)
+        request_url = headers.get(constants.FN_HTTP_REQUEST_URL)
         deadline = headers.get(constants.FN_DEADLINE)
         call_id = headers.get(constants.FN_CALL_ID)
         content_type = headers.get(constants.CONTENT_TYPE)
 
         ctx = InvokeContext(
-            app_id, fn_id, call_id,
+            app_id, app_name, fn_id, fn_name, call_id,
             content_type=content_type,
             deadline=deadline,
             config=os.environ,
             headers=headers,
             method=method,
             request_url=request_url,
             fn_format=constants.HTTPSTREAM,
+            tracing_context=tracing_context,
         )
 
         return ctx, data