trace: Span.add_annotation method (#165)

Author: Emmanuel T Odeke

opencensus/trace/span.py

@@ -176,6 +176,20 @@ def add_attribute(self, attribute_key, attribute_value):
         """
         self.attributes[attribute_key] = attribute_value
 
+    def add_annotation(self, description, **attrs):
+        """Add an annotation to span.
+
+        :type description: str
+        :param description: A user-supplied message describing the event.
+                        The maximum length for the description is 256 bytes.
+
+        :type attrs: kwargs
+        :param attrs: keyworded arguments e.g. failed=True, name='Caching'
+        """
+        at = attributes.Attributes(attrs)
+        self.add_time_event(time_event_module.TimeEvent(datetime.utcnow(),
+                            time_event_module.Annotation(description, at)))
+
     def add_time_event(self, time_event):
         """Add a TimeEvent.
 

tests/unit/trace/test_span.py

@@ -152,6 +152,17 @@ def test_add_time_event(self):
 
         self.assertEqual(len(span.time_events), 1)
 
+    def test_add_annotation(self):
+        span_name = 'test_span_name'
+        span = self._make_one(span_name)
+
+        span.add_annotation('This is a test', name='octo-span', age=98)
+
+        self.assertEqual(len(span.time_events), 1)
+        a0 = span.time_events[0].annotation
+        self.assertEqual(a0.description, 'This is a test')
+        self.assertEqual(a0.attributes.attributes, dict(name='octo-span', age=98))
+
     def test_add_link(self):
         from opencensus.trace.link import Link