support W3C distributed tracing (part 1) (#251)

reyang · SergeyKanzhelev · commit b2c829a501c7 · 2018-08-09T13:39:48.000-07:00
diff --git a/opencensus/trace/propagation/tracestate_string_format.py b/opencensus/trace/propagation/tracestate_string_format.py
@@ -0,0 +1,42 @@
+# Copyright 2018, 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 re
+from opencensus.trace.tracestate import Tracestate
+from opencensus.trace.tracestate import _KEY_FORMAT
+from opencensus.trace.tracestate import _VALUE_FORMAT
+
+_DELIMITER_FORMAT = '[ \t]*,[ \t]*'
+_MEMBER_FORMAT = '(%s)(=)(%s)' % (_KEY_FORMAT, _VALUE_FORMAT)
+
+_DELIMITER_FORMAT_RE = re.compile(_DELIMITER_FORMAT)
+_MEMBER_FORMAT_RE = re.compile(_MEMBER_FORMAT)
+
+
+class TracestateStringFormatter(object):
+    def from_string(self, string):
+        tracestate = Tracestate()
+        for member in re.split(_DELIMITER_FORMAT_RE, string):
+            match = _MEMBER_FORMAT_RE.match(member)
+            if not match:
+                raise ValueError('illegal key-value format %r' % (member))
+            key, eq, value = match.groups()
+            tracestate[key] = value
+        return tracestate
+
+    def to_string(self, tracestate):
+        return ','.join(map(
+            lambda key: key + '=' + tracestate[key],
+            tracestate
+        ))
diff --git a/opencensus/trace/tracestate.py b/opencensus/trace/tracestate.py
@@ -0,0 +1,61 @@
+# Copyright 2018, 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.
+
+from collections import OrderedDict
+import re
+
+_KEY_FORMAT = r'[a-z][_0-9a-z\-\*\/]{0,255}'
+_VALUE_FORMAT = r'[\x20-\x2b\x2d-\x3c\x3e-\x7e]{1,256}'
+
+_KEY_VALIDATION_RE = re.compile('^' + _KEY_FORMAT + '$')
+_VALUE_VALIDATION_RE = re.compile('^' + _VALUE_FORMAT + '$')
+
+
+class Tracestate(OrderedDict):
+    def __setitem__(self, key, value):
+        if not isinstance(key, str):
+            raise ValueError('key must be an instance of str')
+        if not re.match(_KEY_VALIDATION_RE, key):
+            raise ValueError('illegal key provided')
+        if not isinstance(value, str):
+            raise ValueError('value must be an instance of str')
+        if not re.match(_VALUE_VALIDATION_RE, value):
+            raise ValueError('illegal value provided')
+        super(Tracestate, self).__setitem__(key, value)
+
+    def append(self, key, value):
+        if self.get(key):
+            del self[key]
+        self[key] = value
+
+    # make this an optional choice instead of enforcement during put/update
+    # if the tracestate value size is bigger than 512 characters, the tracer
+    # CAN decide to forward the tracestate
+    def is_valid(self):
+        if len(self) is 0:
+            return False
+        # there can be a maximum of 32 list-members in a list
+        if len(self) > 32:
+            return False
+        return True
+
+    def prepend(self, key, value):
+        self[key] = value
+        if hasattr(self, 'move_to_end'):
+            self.move_to_end(key, last=False)
+        else:  # less performant way for Python 2.x
+            copy = OrderedDict(self)
+            self.clear()
+            self[key] = value
+            self.update(copy)
diff --git a/tests/unit/trace/test_tracestate.py b/tests/unit/trace/test_tracestate.py
@@ -0,0 +1,148 @@
+# Copyright 2018, 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 sys
+import unittest
+
+from opencensus.trace.tracestate import Tracestate
+from opencensus.trace.propagation.tracestate_string_format \
+    import TracestateStringFormatter
+
+formatter = TracestateStringFormatter()
+
+class TestTracestate(unittest.TestCase):
+
+    def test_ctor_no_arg(self):
+        state = Tracestate()
+        self.assertEqual(formatter.to_string(state), '')
+
+    def test_ctor_with_dict(self):
+        state = Tracestate({'foo': '1'})
+        self.assertEqual(formatter.to_string(state), 'foo=1')
+
+    def test_cctor(self):
+        state = Tracestate(formatter.from_string('foo=1,bar=2,baz=3'))
+        self.assertEqual(formatter.to_string(state), 'foo=1,bar=2,baz=3')
+
+    def test_all_allowed_chars(self):
+        header = ''.join([
+            # key
+            ''.join(map(chr, range(0x61, 0x7A + 1))), # lcalpha
+            '0123456789', # DIGIT
+            '_',
+            '-',
+            '*',
+            '/',
+            # "="
+            '=',
+            # value
+            ''.join(map(chr, range(0x20, 0x2B + 1))),
+            ''.join(map(chr, range(0x2D, 0x3C + 1))),
+            ''.join(map(chr, range(0x3E, 0x7E + 1))),
+        ])
+        state = formatter.from_string(header)
+        self.assertEqual(formatter.to_string(state), header)
+
+    def test_delimiter(self):
+        state = formatter.from_string('foo=1, \t bar=2')
+        self.assertEqual(formatter.to_string(state), 'foo=1,bar=2')
+
+        state = formatter.from_string('foo=1,\t \tbar=2')
+        self.assertEqual(formatter.to_string(state), 'foo=1,bar=2')
+
+    def test_get(self):
+        state = Tracestate({'foo': '1'})
+        self.assertEqual(state['foo'], '1')
+
+    def test_method_append(self):
+        state = Tracestate()
+        state.append('foo', '1')
+        state.append('bar', '2')
+        state.append('baz', '3')
+        state.append('bar', '2')
+        self.assertEqual(formatter.to_string(state), 'foo=1,baz=3,bar=2')
+
+    def test_method_from_string(self):
+        state = formatter.from_string('foo=1,bar=2,baz=3')
+        self.assertEqual(formatter.to_string(state), 'foo=1,bar=2,baz=3')
+
+        self.assertRaises(ValueError, lambda: formatter.from_string('#=#'))
+
+    def test_method_get(self):
+        state = formatter.from_string('foo=1, bar=2, baz=3')
+        self.assertEqual(state.get('bar'), '2')
+
+    def test_method_is_valid(self):
+        state = Tracestate()
+
+        # empty state not allowed
+        self.assertFalse(state.is_valid())
+
+        state['foo'] = 'x' * 256
+        self.assertTrue(state.is_valid())
+
+        # exceeds 32 elements
+        for i in range(0xa0, 0xa0 + 31):
+            state['%x' % (i)] = 'E'
+        self.assertEqual(len(state), 32)
+        self.assertTrue(state.is_valid())
+        state['ff'] = 'E'
+        self.assertFalse(state.is_valid())
+
+    def test_method_prepend(self):
+        state = Tracestate()
+        state.prepend('foo', '1')
+        state.prepend('baz', '3')
+        state.prepend('bar', '2')
+        self.assertEqual(formatter.to_string(state), 'bar=2,baz=3,foo=1')
+
+        # modified key-value pair MUST be moved to the beginning of the list
+        state.prepend('foo', '1')
+        self.assertEqual(formatter.to_string(state), 'foo=1,bar=2,baz=3')
+
+    def test_pop(self):
+        state = formatter.from_string('foo=1,bar=2,baz=3')
+        state.popitem()
+        self.assertEqual(formatter.to_string(state), 'foo=1,bar=2')
+        state.popitem()
+        self.assertEqual(formatter.to_string(state), 'foo=1')
+        state.popitem()
+        self.assertEqual(formatter.to_string(state), '')
+        # raise KeyError exception while trying to pop from nothing
+        self.assertRaises(KeyError, lambda: state.popitem())
+
+    def test_set(self):
+        state = Tracestate({'bar': '0'})
+        state['foo'] = '1'
+        state['bar'] = '2'
+        state['baz'] = '3'
+        self.assertEqual(formatter.to_string(state), 'bar=2,foo=1,baz=3')
+
+        # key SHOULD be string
+        self.assertRaises(ValueError, lambda: state.__setitem__(123, 'abc'))
+        # value SHOULD NOT be empty string
+        self.assertRaises(ValueError, lambda: state.__setitem__('', 'abc'))
+        # key SHOULD start with a letter
+        self.assertRaises(ValueError, lambda: state.__setitem__('123', 'abc'))
+        # key SHOULD NOT have uppercase
+        self.assertRaises(ValueError, lambda: state.__setitem__('FOO', 'abc'))
+
+        # value SHOULD be string
+        self.assertRaises(ValueError, lambda: state.__setitem__('foo', 123))
+        # value SHOULD NOT be empty string
+        self.assertRaises(ValueError, lambda: state.__setitem__('foo', ''))
+
+        state['foo'] = 'x' * 256
+        # throw if value exceeds 256 bytes
+        self.assertRaises(ValueError, lambda: state.__setitem__('foo', 'x' * 257))
