sdk: Add support for lazy events and links (#474)

The computation of attributes is expensive in some conditions, even in
some cases those attributes are not used at all. This commit fixes the
add_lazy_event method by providing a true solution that delays the attributes
calculation until attributes are accessed. It also provides a new LazyLink class.

Events are also moved to SDK, as they are not a required object to satisfy the API specification.

Co-authored-by: Leighton Chen <[email protected]>

Author: mauriciovasquezbernal

Diff for: ext/opentelemetry-ext-jaeger/tests/test_jaeger_exporter.py

@@ -151,7 +151,7 @@ def test_translate_to_jaeger(self):
         }
 
         event_timestamp = base_time + 50 * 10 ** 6
-        event = trace_api.Event(
+        event = trace.Event(
             name="event0",
             timestamp=event_timestamp,
             attributes=event_attributes,

Diff for: ext/opentelemetry-ext-otcollector/tests/test_otcollector_trace_exporter.py

@@ -108,7 +108,7 @@ def test_translate_to_collector(self):
             "key_float": 0.3,
         }
         event_timestamp = base_time + 50 * 10 ** 6
-        event = trace_api.Event(
+        event = trace.Event(
             name="event0",
             timestamp=event_timestamp,
             attributes=event_attributes,

Diff for: ext/opentelemetry-ext-zipkin/tests/test_zipkin_exporter.py

@@ -134,7 +134,7 @@ def test_export(self):
         }
 
         event_timestamp = base_time + 50 * 10 ** 6
-        event = trace_api.Event(
+        event = trace.Event(
             name="event0",
             timestamp=event_timestamp,
             attributes=event_attributes,

Diff for: opentelemetry-api/src/opentelemetry/trace/__init__.py

@@ -87,48 +87,59 @@
 ParentSpan = typing.Optional[typing.Union["Span", "SpanContext"]]
 
 
-class Link:
-    """A link to a `Span`."""
-
-    def __init__(
-        self, context: "SpanContext", attributes: types.Attributes = None
-    ) -> None:
+class LinkBase(abc.ABC):
+    def __init__(self, context: "SpanContext") -> None:
         self._context = context
-        if attributes is None:
-            self._attributes = {}  # type: types.Attributes
-        else:
-            self._attributes = attributes
 
     @property
     def context(self) -> "SpanContext":
         return self._context
 
     @property
+    @abc.abstractmethod
     def attributes(self) -> types.Attributes:
-        return self._attributes
+        pass
 
 
-class Event:
-    """A text annotation with a set of attributes."""
+class Link(LinkBase):
+    """A link to a `Span`.
+
+    Args:
+        context: `SpanContext` of the `Span` to link to.
+        attributes: Link's attributes.
+    """
 
     def __init__(
-        self, name: str, attributes: types.Attributes, timestamp: int
+        self, context: "SpanContext", attributes: types.Attributes = None,
     ) -> None:
-        self._name = name
+        super().__init__(context)
         self._attributes = attributes
-        self._timestamp = timestamp
-
-    @property
-    def name(self) -> str:
-        return self._name
 
     @property
     def attributes(self) -> types.Attributes:
         return self._attributes
 
+
+class LazyLink(LinkBase):
+    """A lazy link to a `Span`.
+
+    Args:
+        context: `SpanContext` of the `Span` to link to.
+        link_formatter: Callable object that returns the attributes of the
+            Link.
+    """
+
+    def __init__(
+        self,
+        context: "SpanContext",
+        link_formatter: types.AttributesFormatter,
+    ) -> None:
+        super().__init__(context)
+        self._link_formatter = link_formatter
+
     @property
-    def timestamp(self) -> int:
-        return self._timestamp
+    def attributes(self) -> types.Attributes:
+        return self._link_formatter()
 
 
 class SpanKind(enum.Enum):
@@ -206,10 +217,17 @@ def add_event(
         """
 
     @abc.abstractmethod
-    def add_lazy_event(self, event: Event) -> None:
+    def add_lazy_event(
+        self,
+        name: str,
+        event_formatter: types.AttributesFormatter,
+        timestamp: typing.Optional[int] = None,
+    ) -> None:
         """Adds an `Event`.
 
-        Adds an `Event` that has previously been created.
+        Adds a single `Event` with the name, an event formatter that calculates
+        the attributes lazily and, optionally, a timestamp. Implementations
+        should generate a timestamp if the `timestamp` argument is omitted.
         """
 
     @abc.abstractmethod
@@ -395,7 +413,12 @@ def add_event(
     ) -> None:
         pass
 
-    def add_lazy_event(self, event: Event) -> None:
+    def add_lazy_event(
+        self,
+        name: str,
+        event_formatter: types.AttributesFormatter,
+        timestamp: typing.Optional[int] = None,
+    ) -> None:
         pass
 
     def update_name(self, name: str) -> None:

Diff for: opentelemetry-api/src/opentelemetry/util/types.py

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 
-from typing import Dict, Optional, Sequence, Union
+from typing import Callable, Dict, Optional, Sequence, Union
 
 AttributeValue = Union[
     str,
@@ -26,3 +26,4 @@
     Sequence[float],
 ]
 Attributes = Optional[Dict[str, AttributeValue]]
+AttributesFormatter = Callable[[], Optional[Dict[str, AttributeValue]]]

Diff for: opentelemetry-sdk/src/opentelemetry/sdk/trace/__init__.py

@@ -13,6 +13,7 @@
 # limitations under the License.
 
 
+import abc
 import atexit
 import logging
 import random
@@ -114,6 +115,77 @@ def shutdown(self) -> None:
             sp.shutdown()
 
 
+class EventBase(abc.ABC):
+    def __init__(self, name: str, timestamp: Optional[int] = None) -> None:
+        self._name = name
+        if timestamp is None:
+            self._timestamp = time_ns()
+        else:
+            self._timestamp = timestamp
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def timestamp(self) -> int:
+        return self._timestamp
+
+    @property
+    @abc.abstractmethod
+    def attributes(self) -> types.Attributes:
+        pass
+
+
+class Event(EventBase):
+    """A text annotation with a set of attributes.
+
+    Args:
+        name: Name of the event.
+        attributes: Attributes of the event.
+        timestamp: Timestamp of the event. If `None` it will filled
+            automatically.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        attributes: types.Attributes = None,
+        timestamp: Optional[int] = None,
+    ) -> None:
+        super().__init__(name, timestamp)
+        self._attributes = attributes
+
+    @property
+    def attributes(self) -> types.Attributes:
+        return self._attributes
+
+
+class LazyEvent(EventBase):
+    """A text annotation with a set of attributes.
+
+    Args:
+        name: Name of the event.
+        event_formatter: Callable object that returns the attributes of the
+            event.
+        timestamp: Timestamp of the event. If `None` it will filled
+            automatically.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        event_formatter: types.AttributesFormatter,
+        timestamp: Optional[int] = None,
+    ) -> None:
+        super().__init__(name, timestamp)
+        self._event_formatter = event_formatter
+
+    @property
+    def attributes(self) -> types.Attributes:
+        return self._event_formatter()
+
+
 class Span(trace_api.Span):
     """See `opentelemetry.trace.Span`.
 
@@ -149,7 +221,7 @@ def __init__(
         trace_config: None = None,  # TODO
         resource: None = None,
         attributes: types.Attributes = None,  # TODO
-        events: Sequence[trace_api.Event] = None,  # TODO
+        events: Sequence[Event] = None,  # TODO
         links: Sequence[trace_api.Link] = (),
         kind: trace_api.SpanKind = trace_api.SpanKind.INTERNAL,
         span_processor: SpanProcessor = SpanProcessor(),
@@ -266,21 +338,7 @@ def _check_attribute_value_sequence(sequence: Sequence) -> Optional[str]:
                 return "different type"
         return None
 
-    def add_event(
-        self,
-        name: str,
-        attributes: types.Attributes = None,
-        timestamp: Optional[int] = None,
-    ) -> None:
-        self.add_lazy_event(
-            trace_api.Event(
-                name,
-                Span._empty_attributes if attributes is None else attributes,
-                time_ns() if timestamp is None else timestamp,
-            )
-        )
-
-    def add_lazy_event(self, event: trace_api.Event) -> None:
+    def _add_event(self, event: EventBase) -> None:
         with self._lock:
             if not self.is_recording_events():
                 return
@@ -293,6 +351,36 @@ def add_lazy_event(self, event: trace_api.Event) -> None:
             return
         self.events.append(event)
 
+    def add_event(
+        self,
+        name: str,
+        attributes: types.Attributes = None,
+        timestamp: Optional[int] = None,
+    ) -> None:
+        if attributes is None:
+            attributes = Span._empty_attributes
+        self._add_event(
+            Event(
+                name=name,
+                attributes=attributes,
+                timestamp=time_ns() if timestamp is None else timestamp,
+            )
+        )
+
+    def add_lazy_event(
+        self,
+        name: str,
+        event_formatter: types.AttributesFormatter,
+        timestamp: Optional[int] = None,
+    ) -> None:
+        self._add_event(
+            LazyEvent(
+                name=name,
+                event_formatter=event_formatter,
+                timestamp=time_ns() if timestamp is None else timestamp,
+            )
+        )
+
     def start(self, start_time: Optional[int] = None) -> None:
         with self._lock:
             if not self.is_recording_events():

Diff for: opentelemetry-sdk/tests/trace/test_trace.py

@@ -547,10 +547,11 @@ def test_events(self):
             now = time_ns()
             root.add_event("event2", {"name": "birthday"}, now)
 
+            def event_formatter():
+                return {"name": "hello"}
+
             # lazy event
-            root.add_lazy_event(
-                trace_api.Event("event3", {"name": "hello"}, now)
-            )
+            root.add_lazy_event("event3", event_formatter, now)
 
             self.assertEqual(len(root.events), 4)
 
@@ -584,11 +585,15 @@ def test_links(self):
             span_id=trace.generate_span_id(),
             is_remote=False,
         )
-        links = [
+
+        def get_link_attributes():
+            return {"component": "http"}
+
+        links = (
             trace_api.Link(other_context1),
             trace_api.Link(other_context2, {"name": "neighbor"}),
-            trace_api.Link(other_context3, {"component": "http"}),
-        ]
+            trace_api.LazyLink(other_context3, get_link_attributes),
+        )
         with self.tracer.start_as_current_span("root", links=links) as root:
 
             self.assertEqual(len(root.links), 3)
@@ -598,7 +603,7 @@ def test_links(self):
             self.assertEqual(
                 root.links[0].context.span_id, other_context1.span_id
             )
-            self.assertEqual(root.links[0].attributes, {})
+            self.assertEqual(root.links[0].attributes, None)
             self.assertEqual(
                 root.links[1].context.trace_id, other_context2.trace_id
             )