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

OVERVIEW
Oracle Functions will soon release a feature providing an integration with the Oracle Application Performance Monitoring (APM) service. This service supports the sending of Zipkin formatted tracing data to a collector endpoint.

The service will provide the function code with data which includes:

    A boolean flag specifying whether the tracing integration is enabled for the function invocation
    A trace collector URL that can be used to configure Zipkin so that tracing data is sent there
    The "B3" formatted headers specifying the originating trace ID and span IDs (as specified by Zipkin)

This information is accessible by the function code in a Tracing Context provided by the FDK.

This change has no effect on existing functions, except that the keys "OCI_TRACING_ENABLED" and "OCI_TRACE_COLLECTOR_URL" are now reserved for this tracing integration and cannot be used for function configuration.

FDK SPECIFIC CHANGES
This change adds an additional tracing context to the invoke context. This can be accessed by users to configure tracing in their functions using the zipkin libraries of their choice (py_zipkin seems to be the most popular). The tracing context contains methods to access the extracted zipkin B3 headers as well as the trace collector URL, tracing enabled flag and a few extra helper methods specific to py_zipkin (service name, annotations and zipkin attributes).

Additionally, methods to retrieve the app and fn name were added to the invoke context.

Changes have been made to constants.py and context.py and unit tests have been added to test_tracing.py

This change should not affect existing functions.

Author: hhexo

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