api: rename Span::record_exception to Span::record_error (#756)

This change aligns the error recording methods with Rust's naming
conventions which prefer the term `Error` over `Exception`.

This also removes `Span::record_exception_with_stacktrace` as Rust's
backtrace functionality is not yet stable. Users who wish to record
this data can use `Span::add_event` directly.

Author: jtescher

opentelemetry-api/src/trace/context.rs

@@ -60,17 +60,14 @@ impl SpanRef<'_> {
         self.with_inner_mut(|inner| inner.add_event(name, attributes))
     }
 
-    /// Record an exception event
-    pub fn record_exception(&self, err: &dyn Error) {
-        self.with_inner_mut(|inner| inner.record_exception(err))
-    }
-
-    /// Record an exception event with stacktrace
-    pub fn record_exception_with_stacktrace<T>(&self, err: &dyn Error, stacktrace: T)
-    where
-        T: Into<Cow<'static, str>>,
-    {
-        self.with_inner_mut(|inner| inner.record_exception_with_stacktrace(err, stacktrace))
+    /// Record an error as an event for this span.
+    ///
+    /// An additional call to [Span::set_status] is required if the status of the
+    /// span should be set to error, as this method does not change the span status.
+    ///
+    /// If this span is not being recorded then this method does nothing.
+    pub fn record_error(&self, err: &dyn Error) {
+        self.with_inner_mut(|inner| inner.record_error(err))
     }
 
     /// Record an event with a timestamp in the context this span.

opentelemetry-api/src/trace/span.rs

@@ -63,23 +63,17 @@ pub trait Span {
         self.add_event_with_timestamp(name, crate::time::now(), attributes)
     }
 
-    /// Record an exception event
-    fn record_exception(&mut self, err: &dyn Error) {
-        let attributes = vec![KeyValue::new("exception.message", err.to_string())];
-        self.add_event("exception", attributes);
-    }
-
-    /// Record an exception event with stacktrace
-    fn record_exception_with_stacktrace<T>(&mut self, err: &dyn Error, stacktrace: T)
-    where
-        T: Into<Cow<'static, str>>,
-    {
-        let attributes = vec![
-            KeyValue::new("exception.message", err.to_string()),
-            KeyValue::new("exception.stacktrace", stacktrace.into()),
-        ];
-
-        self.add_event("exception", attributes);
+    /// Record an error as an event for this span.
+    ///
+    /// An additional call to [Span::set_status] is required if the status of the
+    /// span should be set to error, as this method does not change the span status.
+    ///
+    /// If this span is not being recorded then this method does nothing.
+    fn record_error(&mut self, err: &dyn Error) {
+        if self.is_recording() {
+            let attributes = vec![KeyValue::new("exception.message", err.to_string())];
+            self.add_event("exception", attributes);
+        }
     }
 
     /// Record an event with a timestamp in the context this span.

opentelemetry-sdk/src/trace/span.rs

@@ -359,10 +359,10 @@ mod tests {
     }
 
     #[test]
-    fn record_exception() {
+    fn record_error() {
         let mut span = create_span();
         let err = std::io::Error::from(std::io::ErrorKind::Other);
-        span.record_exception(&err);
+        span.record_error(&err);
         span.with_data(|data| {
             if let Some(event) = data.events.iter().next() {
                 assert_eq!(event.name, "exception");
@@ -376,28 +376,6 @@ mod tests {
         });
     }
 
-    #[test]
-    fn record_exception_with_stacktrace() {
-        let mut span = create_span();
-        let err = std::io::Error::from(std::io::ErrorKind::Other);
-        let stacktrace = "stacktrace...".to_string();
-        span.record_exception_with_stacktrace(&err, stacktrace.clone());
-        span.with_data(|data| {
-            if let Some(event) = data.events.iter().next() {
-                assert_eq!(event.name, "exception");
-                assert_eq!(
-                    event.attributes,
-                    vec![
-                        KeyValue::new("exception.message", err.to_string()),
-                        KeyValue::new("exception.stacktrace", stacktrace),
-                    ]
-                );
-            } else {
-                panic!("no event");
-            }
-        });
-    }
-
     #[test]
     fn set_attribute() {
         let mut span = create_span();
@@ -517,8 +495,7 @@ mod tests {
             vec![KeyValue::new("k", "v")],
         );
         let err = std::io::Error::from(std::io::ErrorKind::Other);
-        span.record_exception(&err);
-        span.record_exception_with_stacktrace(&err, "stacktrace...".to_string());
+        span.record_error(&err);
         span.set_attribute(KeyValue::new("k", "v"));
         span.set_status(StatusCode::Error, "ERROR".to_string());
         span.update_name("new_name".to_string());