api: Adding record_error to span API (#790)

As per open-telemetry/opentelemetry-specification#427, we need an interface for users to record errors.

Author: alrex

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

@@ -88,6 +88,10 @@ def set_status(self, status: Status) -> None:
         Span status, which is OK.
         """
 
+    @abc.abstractmethod
+    def record_error(self, err: Exception) -> None:
+        """Records an error as a span event."""
+
     def __enter__(self) -> "Span":
         """Invoked when `Span` is used as a context manager.
 
@@ -253,6 +257,9 @@ def update_name(self, name: str) -> None:
     def set_status(self, status: Status) -> None:
         pass
 
+    def record_error(self, err: Exception) -> None:
+        pass
+
 
 INVALID_SPAN_ID = 0x0000000000000000
 INVALID_TRACE_ID = 0x00000000000000000000000000000000

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

@@ -20,6 +20,7 @@
 import logging
 import random
 import threading
+import traceback
 from collections import OrderedDict
 from contextlib import contextmanager
 from types import TracebackType
@@ -681,6 +682,17 @@ def __exit__(
 
         super().__exit__(exc_type, exc_val, exc_tb)
 
+    def record_error(self, err: Exception) -> None:
+        """Records an error as a span event."""
+        self.add_event(
+            name="error",
+            attributes={
+                "error.type": err.__class__.__name__,
+                "error.message": str(err),
+                "error.stack": traceback.format_exc(),
+            },
+        )
+
 
 def generate_span_id() -> int:
     """Get a new random span ID.

opentelemetry-sdk/tests/trace/test_trace.py

@@ -801,6 +801,20 @@ def error_status_test(context):
             .start_as_current_span("root")
         )
 
+    def test_record_error(self):
+        span = trace.Span("name", mock.Mock(spec=trace_api.SpanContext))
+        try:
+            raise ValueError("invalid")
+        except ValueError as err:
+            span.record_error(err)
+        error_event = span.events[0]
+        self.assertEqual("error", error_event.name)
+        self.assertEqual("invalid", error_event.attributes["error.message"])
+        self.assertEqual("ValueError", error_event.attributes["error.type"])
+        self.assertIn(
+            "ValueError: invalid", error_event.attributes["error.stack"]
+        )
+
 
 def span_event_start_fmt(span_processor_name, span_name):
     return span_processor_name + ":" + span_name + ":start"