Replace enabled with trace_options (#43)

Author: liyanhui1228

trace/opencensus/trace/propagation/_helpers.py

@@ -17,8 +17,8 @@
 import logging
 import struct
 
-from opencensus.trace.propagation import _helpers
 from opencensus.trace.span_context import SpanContext
+from opencensus.trace.trace_options import TraceOptions
 
 # Used for decoding hex bytes to hex string.
 UTF8 = 'utf-8'
@@ -118,14 +118,12 @@ def from_header(self, binary):
         # with length 32, then decode it to hex string using utf-8.
         trace_id = str(binascii.hexlify(data.trace_id).decode(UTF8))
         span_id = data.span_id
-        trace_option = data.trace_option
-
-        enabled = _helpers._get_enabled_trace_option(trace_option)
+        trace_options = TraceOptions(data.trace_option)
 
         span_context = SpanContext(
                 trace_id=trace_id,
                 span_id=span_id,
-                enabled=enabled,
+                trace_options=trace_options,
                 from_header=True)
 
         return span_context
@@ -142,15 +140,13 @@ def to_header(self, span_context):
         """
         trace_id = span_context.trace_id
         span_id = span_context.span_id
-        enabled = span_context.enabled
+        trace_options = int(span_context.trace_options.trace_options_byte)
 
         # If there is no span_id in this context, set it to 0, which is
         # considered invalid and won't be set as the downstream parent span_id.
         if span_id is None:
             span_id = 0
 
-        enabled_int = int(enabled)
-
         # Convert trace_id to bytes with length 16, treat span_id as 64 bit
         # integer which is unsigned long long type and convert it to bytes with
         # length 8, trace_option is integer with length 1.
@@ -162,4 +158,4 @@ def to_header(self, span_context):
             SPAN_ID_FIELD_ID,
             span_id,
             TRACE_OPTION_FIELD_ID,
-            enabled_int)
+            trace_options)

trace/opencensus/trace/propagation/binary_format.py

@@ -21,10 +21,9 @@
 import logging
 import re
 
-from opencensus.trace.propagation import _helpers
 from opencensus.trace.span_context import SpanContext
+from opencensus.trace.trace_options import TraceOptions
 
-_ENABLED_BITMASK = 1
 _TRACE_CONTEXT_HEADER_FORMAT = '([0-9a-f]{32})(\/(\d+))?(;o=(\d+))?'
 _TRACE_CONTEXT_HEADER_RE = re.compile(_TRACE_CONTEXT_HEADER_FORMAT)
 _TRACE_ID_DELIMETER = '/'
@@ -59,17 +58,15 @@ def from_header(self, header):
         if match:
             trace_id = match.group(1)
             span_id = match.group(3)
-            options = match.group(5)
+            trace_options = match.group(5)
 
-            if options is None:
-                options = 1
-
-            enabled = _helpers._get_enabled_trace_option(options)
+            if trace_options is None:
+                trace_options = 1
 
             span_context = SpanContext(
                 trace_id=trace_id,
                 span_id=span_id,
-                enabled=enabled,
+                trace_options=TraceOptions(trace_options),
                 from_header=True)
             return span_context
         else:
@@ -90,10 +87,10 @@ def to_header(self, span_context):
         """
         trace_id = span_context.trace_id
         span_id = span_context.span_id
-        enabled = span_context.enabled
+        trace_options = span_context.trace_options.trace_options_byte
 
         header = '{}/{};o={}'.format(
             trace_id,
             span_id,
-            int(enabled))
+            int(trace_options))
         return header

trace/opencensus/trace/propagation/google_cloud_format.py

@@ -18,11 +18,14 @@
 """
 
 from opencensus.trace.span_context import SpanContext
+from opencensus.trace.trace_options import TraceOptions
 
 _OPENCENSUS_TRACE_PREFIX = 'opencensus-trace'
 _TRACE_ID_KEY = '{}-traceid'.format(_OPENCENSUS_TRACE_PREFIX)
 _SPAN_ID_KEY = '{}-spanid'.format(_OPENCENSUS_TRACE_PREFIX)
-_ENABLED_TRACE_KEY = '{}-enabled'.format(_OPENCENSUS_TRACE_PREFIX)
+_TRACE_OPTIONS_KEY = '{}-traceoptions'.format(_OPENCENSUS_TRACE_PREFIX)
+
+DEFAULT_TRACE_OPTIONS = '1'
 
 
 class TextFormatPropagator(object):
@@ -39,21 +42,24 @@ def from_carrier(self, carrier):
         """
         trace_id = None
         span_id = None
-        enabled = 1
+        trace_options = None
 
         for key in carrier:
             key = key.lower()
             if key == _TRACE_ID_KEY:
                 trace_id = carrier[key]
             if key == _SPAN_ID_KEY:
                 span_id = carrier[key]
-            if key == _ENABLED_TRACE_KEY:
-                enabled = bool(carrier[key])
+            if key == _TRACE_OPTIONS_KEY:
+                trace_options = bool(carrier[key])
+
+        if trace_options is None:
+            trace_options = DEFAULT_TRACE_OPTIONS
 
         return SpanContext(
             trace_id=trace_id,
             span_id=span_id,
-            enabled=enabled,
+            trace_options=TraceOptions(trace_options),
             from_header=True)
 
     def to_carrier(self, span_context, carrier):
@@ -75,6 +81,7 @@ def to_carrier(self, span_context, carrier):
         if span_context.span_id is not None:
             carrier[_SPAN_ID_KEY] = str(span_context.span_id)
 
-        carrier[_ENABLED_TRACE_KEY] = str(span_context.enabled)
+        carrier[_TRACE_OPTIONS_KEY] = str(
+            span_context.trace_options.trace_options_byte)
 
         return carrier

trace/opencensus/trace/propagation/text_format.py

@@ -73,7 +73,8 @@ def should_sample(self):
         :rtype: bool
         :returns: Whether to trace the request or not.
         """
-        return self.span_context.enabled and self.sampler.should_sample
+        return self.span_context.trace_options.enabled \
+            and self.sampler.should_sample
 
     def get_tracer(self):
         """Return a tracer according to the sampling decision."""

trace/opencensus/trace/request_tracer.py

@@ -19,14 +19,22 @@
 import re
 import uuid
 
+from opencensus.trace import trace_options
+
 _INVALID_TRACE_ID = '0' * 32
 _INVALID_SPAN_ID = 0
 _TRACE_HEADER_KEY = 'X_CLOUD_TRACE_CONTEXT'
 _TRACE_ID_FORMAT = '[0-9a-f]{32}?'
 
+# Default options, enable tracing
+DEFAULT_OPTIONS = 1
+
+# Default trace options
+DEFAULT = trace_options.TraceOptions(DEFAULT_OPTIONS)
+
 
 class SpanContext(object):
-    """SpanContext includes 3 fields: traceId, spanId, and an enabled flag
+    """SpanContext includes 3 fields: traceId, spanId, and an trace_options flag
     which indicates whether or not the request is being traced. It contains the
     current context to be propagated to the child spans.
 
@@ -37,8 +45,8 @@ class SpanContext(object):
     :type span_id: int
     :param span_id: (Optional) Identifier for the span, unique within a trace.
 
-    :type enabled: bool
-    :param enabled: (Optional) Indicates whether the request is traced or not.
+    :type trace_options: :class: `~opencensus.trace.trace_options.TraceOptions`
+    :param trace_options: (Optional) TraceOptions indicates 8 trace options.
 
     :type from_header: bool
     :param from_header: (Optional) Indicates whether the trace context is
@@ -48,14 +56,17 @@ def __init__(
             self,
             trace_id=None,
             span_id=None,
-            enabled=True,
+            trace_options=None,
             from_header=False):
         if trace_id is None:
             trace_id = generate_trace_id()
 
+        if trace_options is None:
+            trace_options = DEFAULT
+
         self.trace_id = self.check_trace_id(trace_id)
         self.span_id = self.check_span_id(span_id)
-        self.enabled = enabled
+        self.trace_options = trace_options
         self.from_header = from_header
 
     def __str__(self):
@@ -66,10 +77,11 @@ def __str__(self):
         :rtype: str
         :returns: String form of the SpanContext.
         """
+        enabled = self.trace_options.enabled
         header = '{}/{};o={}'.format(
             self.trace_id,
             self.span_id,
-            int(self.enabled))
+            int(enabled))
         return header
 
     def check_span_id(self, span_id):

trace/opencensus/trace/span_context.py

@@ -0,0 +1,61 @@
+# Copyright 2017, OpenCensus Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import logging
+
+# Enabled field is the least significant bit of trace options.
+_ENABLED_BITMASK = 1 << 0
+
+# Default trace options
+DEFAULT = '1'
+
+
+class TraceOptions(object):
+    """A class that represents global trace options.
+
+    :type trace_options_byte: str
+    :param trace_options_byte: 1 byte bitmap for trace options.
+    """
+
+    def __init__(self, trace_options_byte=None):
+        if trace_options_byte is None:
+            trace_options_byte = DEFAULT
+
+        self.trace_options_byte = self.check_trace_options(trace_options_byte)
+        self.enabled = self.get_enabled
+
+    def check_trace_options(self, trace_options_byte):
+        trace_options_int = int(trace_options_byte)
+
+        if trace_options_int < 0 or trace_options_int > 255:
+            logging.warn("Trace options invalid, should be 1 byte.")
+            trace_options_byte = DEFAULT
+
+        return trace_options_byte
+
+    @property
+    def get_enabled(self):
+        """Get the last bit from the trace options which is the enabled field.
+
+        :type trace_options: byte
+        :param trace_options: 1 byte field which indicates 8 trace options,
+                              currently only have the enabled option. 1 means
+                              enabled, 0 means not enabled.
+
+        :rtype: bool
+        :returns: Enabled tracing or not.
+        """
+        enabled = bool(int(self.trace_options_byte) & _ENABLED_BITMASK)
+
+        return enabled

trace/opencensus/trace/trace_options.py

@@ -45,18 +45,21 @@ def test_from_header(self):
 
         self.assertEqual(span_context.trace_id, expected_trace_id)
         self.assertEqual(span_context.span_id, expected_span_id)
-        self.assertEqual(span_context.enabled, expected_trace_option)
+        self.assertEqual(
+            span_context.trace_options.enabled,
+            expected_trace_option)
 
     def test_to_header_span_id_zero(self):
         from opencensus.trace.span_context import SpanContext
+        from opencensus.trace.trace_options import TraceOptions
 
         span_context = mock.Mock(spec=SpanContext)
         trace_id = 'a0b72ca15c1a4bd18962d0ac59dc90b9'
         span_id = None
-        enabled = True
+        trace_options = '1'
         span_context.trace_id = trace_id
         span_context.span_id = span_id
-        span_context.enabled = enabled
+        span_context.trace_options = TraceOptions(trace_options)
 
         propagator = binary_format.BinaryFormatPropagator()
 
@@ -70,14 +73,15 @@ def test_to_header_span_id_zero(self):
 
     def test_to_header(self):
         from opencensus.trace.span_context import SpanContext
+        from opencensus.trace.trace_options import TraceOptions
 
         span_context = mock.Mock(spec=SpanContext)
         trace_id = 'a0b72ca15c1a4bd18962d0ac59dc90b9'
         span_id = 7433567179112518326
-        enabled = True
+        trace_options = '1'
         span_context.trace_id = trace_id
         span_context.span_id = span_id
-        span_context.enabled = enabled
+        span_context.trace_options = TraceOptions(trace_options)
 
         propagator = binary_format.BinaryFormatPropagator()