api: unify Event and Link access patterns (#757)

This makes the data in span `Event`s and `Link`s `pub`, but guards
against future additions by making the structs `non_exhaustive`.

Author: jtescher

opentelemetry-api/src/trace/mod.rs

@@ -209,17 +209,21 @@ impl From<&'static str> for TraceError {
 #[error("{0}")]
 struct Custom(String);
 
-/// A `Span` has the ability to add events. Events have a time associated
-/// with the moment when they are added to the `Span`.
+/// Events record things that happened during a [`Span`]'s lifetime.
+#[non_exhaustive]
 #[derive(Clone, Debug, PartialEq)]
 pub struct Event {
-    /// Event name
+    /// The name of this event.
     pub name: Cow<'static, str>,
-    /// Event timestamp
+
+    /// The time at which this event occurred.
     pub timestamp: time::SystemTime,
-    /// Event attributes
+
+    /// Attributes that describe this event.
     pub attributes: Vec<KeyValue>,
-    /// Number of dropped attributes
+
+    /// The number of attributes that were above the configured limit, and thus
+    /// dropped.
     pub dropped_attributes_count: u32,
 }
 
@@ -250,41 +254,30 @@ impl Event {
     }
 }
 
-/// During the `Span` creation user MUST have the ability to record links to other `Span`s. Linked
-/// `Span`s can be from the same or a different trace.
+/// Link is the relationship between two Spans.
+///
+/// The relationship can be within the same trace or across different traces.
+#[non_exhaustive]
 #[derive(Clone, Debug, PartialEq)]
 pub struct Link {
-    span_context: SpanContext,
+    /// The span context of the linked span.
+    pub span_context: SpanContext,
 
-    /// Attributes describing this link
+    /// Attributes that describe this link.
     pub attributes: Vec<KeyValue>,
 
-    /// The number of attributes that were above the limit, and thus dropped.
+    /// The number of attributes that were above the configured limit, and thus
+    /// dropped.
     pub dropped_attributes_count: u32,
 }
 
 impl Link {
-    /// Create a new link
+    /// Create a new link.
     pub fn new(span_context: SpanContext, attributes: Vec<KeyValue>) -> Self {
         Link {
             span_context,
             attributes,
             dropped_attributes_count: 0,
         }
     }
-
-    /// The span context of the linked span
-    pub fn span_context(&self) -> &SpanContext {
-        &self.span_context
-    }
-
-    /// Attributes of the span link
-    pub fn attributes(&self) -> &Vec<KeyValue> {
-        &self.attributes
-    }
-
-    /// Dropped attributes count
-    pub fn dropped_attributes_count(&self) -> u32 {
-        self.dropped_attributes_count
-    }
 }

opentelemetry-api/src/trace/tracer.rs

@@ -336,7 +336,7 @@ impl SpanBuilder {
 
     /// Assign links
     pub fn with_links(self, mut links: Vec<Link>) -> Self {
-        links.retain(|l| l.span_context().is_valid());
+        links.retain(|l| l.span_context.is_valid());
         SpanBuilder {
             links: Some(links),
             ..self

opentelemetry-jaeger/src/exporter/mod.rs

@@ -676,7 +676,7 @@ fn links_to_references(links: sdk::trace::EvictedQueue<Link>) -> Option<Vec<jaeg
         let refs = links
             .iter()
             .map(|link| {
-                let span_context = link.span_context();
+                let span_context = &link.span_context;
                 let trace_id_bytes = span_context.trace_id().to_bytes();
                 let (high, low) = trace_id_bytes.split_at(8);
                 let trace_id_high = i64::from_be_bytes(high.try_into().unwrap());

opentelemetry-proto/src/transform/traces.rs

@@ -36,11 +36,11 @@ pub mod tonic {
     impl From<Link> for span::Link {
         fn from(link: Link) -> Self {
             span::Link {
-                trace_id: link.span_context().trace_id().to_bytes().to_vec(),
-                span_id: link.span_context().span_id().to_bytes().to_vec(),
-                trace_state: link.span_context().trace_state().header(),
-                attributes: Attributes::from(link.attributes().clone()).0,
-                dropped_attributes_count: link.dropped_attributes_count(),
+                trace_id: link.span_context.trace_id().to_bytes().to_vec(),
+                span_id: link.span_context.span_id().to_bytes().to_vec(),
+                trace_state: link.span_context.trace_state().header(),
+                attributes: Attributes::from(link.attributes).0,
+                dropped_attributes_count: link.dropped_attributes_count,
             }
         }
     }
@@ -154,11 +154,11 @@ pub mod grpcio {
     impl From<Link> for Span_Link {
         fn from(link: Link) -> Self {
             Span_Link {
-                trace_id: link.span_context().trace_id().to_bytes().to_vec(),
-                span_id: link.span_context().span_id().to_bytes().to_vec(),
-                trace_state: link.span_context().trace_state().header(),
-                attributes: Attributes::from(link.attributes().clone()).0,
-                dropped_attributes_count: link.dropped_attributes_count(),
+                trace_id: link.span_context.trace_id().to_bytes().to_vec(),
+                span_id: link.span_context.span_id().to_bytes().to_vec(),
+                trace_state: link.span_context.trace_state().header(),
+                attributes: Attributes::from(link.attributes).0,
+                dropped_attributes_count: link.dropped_attributes_count,
                 ..Default::default()
             }
         }

opentelemetry-sdk/src/trace/span.rs

@@ -611,7 +611,7 @@ mod tests {
             .links;
         let link_vec: Vec<_> = link_queue.iter().collect();
         let processed_link = link_vec.get(0).expect("should have at least one link");
-        assert_eq!(processed_link.attributes().len(), 128);
+        assert_eq!(processed_link.attributes.len(), 128);
     }
 
     #[test]