Span: add attribute, event, link setter to the API

Basic tests that exercise the API are added as well. However it does not
actually test that the attributes, events and links are written properly
because there is no getter. Those tests can be added later when the
attributes are actually used.

The spec mentions additional APIs for lazy initialization (AddLazyEvent,
AddLazyLink). Those are not added in this patch because OT-Python does
not expose the Event type (currently defined in the SDK only).

opentelemetry-api/src/opentelemetry/trace/__init__.py

@@ -65,6 +65,8 @@
 import typing
 
 from opentelemetry import loader
+from opentelemetry import trace as trace_api
+from opentelemetry import types
 
 # TODO: quarantine
 ParentSpan = typing.Optional[typing.Union['Span', 'SpanContext']]
@@ -102,6 +104,34 @@ def get_context(self) -> 'SpanContext':
             A :class:`.SpanContext` with a copy of this span's immutable state.
         """
 
+    def set_attribute(self: 'Span',
+                      key: str,
+                      value: 'types.AttributeValue'
+                      ) -> None:
+        """Sets an Attribute.
+
+        Sets a single Attribute with the key and value passed as arguments.
+        """
+
+    def add_event(self: 'Span',
+                  name: str,
+                  attributes: 'types.Attributes',
+                  ) -> None:
+        """Adds an Event.
+
+        Adds a single Event with the name and, optionally, attributes passed
+        as arguments.
+        """
+
+    def add_link(self: 'Span',
+                 context: 'trace_api.SpanContext',
+                 attributes: 'types.Attributes',
+                 ) -> None:
+        """Adds a Link to another Span.
+
+        Adds a single Link to the Span via the SpanContext passed as argument.
+        """
+
 
 class TraceOptions(int):
     """A bitmask that represents options specific to the trace.

opentelemetry-sdk/tests/trace/test_trace.py

@@ -114,6 +114,34 @@ def test_start_span_explicit(self):
             self.assertIs(tracer.get_current_span(), root)
             self.assertIsNotNone(child.end_time)
 
+    def test_span_members(self):
+        context = contextvars.ContextVar('test_span_members')
+        tracer = trace.Tracer(context)
+
+        other_neighbor = trace_api.SpanContext(
+            trace_id=0x0000000000000000000000000000cafe,
+            span_id=0x00000000cafe1234
+        )
+
+        self.assertIsNone(tracer.get_current_span())
+
+        with tracer.start_span('root') as root:
+            root.set_attribute('component', 'http')
+            root.set_attribute('http.method', 'GET')
+            root.set_attribute('http.url',
+                               'https://example.com:779/path/12/?q=d#123')
+            root.set_attribute('http.status_code', 200)
+            root.set_attribute('http.status_text', 'OK')
+
+            # Setting an attribute with the same key as an existing attribute
+            # SHOULD overwrite the existing attribute's value.
+            root.set_attribute('attr-key', 'attr-value1')
+            root.set_attribute('attr-key', 'attr-value2')
+
+            root.add_event('event1', 'event1-detail')
+
+            root.add_link(other_neighbor, 'neighbor')
+
 
 class TestSpan(unittest.TestCase):