trace: Allow specifying a new span's parent (#923)

This branch allows users of `tokio-trace` to explicitly set a span's
parent, or indicate that a span should be a new root of its own trace
tree. A `parent: ` key has been added to the `span!` macros. When a span
is provided, that span will be set as the parent, while `parent: None`
will result in a new root span. No `parent:` key results in the current
behaviour.

A new type, `span::Attributes`, was added to `tokio-trace-core` to act
as an arguments struct for the `Subscriber::new_span` method. This will
allow future fields to be added without causing breaking API changes.
The `Attributes` struct currently contains the new span's metadata,
`ValueSet`, and parent.

Finally, the `span::Span` type in `-core` was renamed to `span::Id`, for
consistency with `tokio-trace` and to differentiate it from
`span::Attributes`. This name was chosen primarily due to precedent in
other tracing systems.

Closes #920 

Signed-off-by: Eliza Weisman <[email protected]>

tokio-trace/tests/support/span.rs

@@ -11,10 +11,19 @@ pub struct MockSpan {
     pub(in support) metadata: metadata::Expect,
 }
 
+#[derive(Debug, Eq, PartialEq)]
+pub(in support) enum Parent {
+    ContextualRoot,
+    Contextual(String),
+    ExplicitRoot,
+    Explicit(String),
+}
+
 #[derive(Debug, Default, Eq, PartialEq)]
 pub struct NewSpan {
     pub(in support) span: MockSpan,
     pub(in support) fields: field::Expect,
+    pub(in support) parent: Option<Parent>,
 }
 
 pub fn mock() -> MockSpan {
@@ -60,6 +69,30 @@ impl MockSpan {
         }
     }
 
+    pub fn with_explicit_parent(self, parent: Option<&str>) -> NewSpan {
+        let parent = match parent {
+            Some(name) => Parent::Explicit(name.into()),
+            None => Parent::ExplicitRoot,
+        };
+        NewSpan {
+            parent: Some(parent),
+            span: self,
+            ..Default::default()
+        }
+    }
+
+    pub fn with_contextual_parent(self, parent: Option<&str>) -> NewSpan {
+        let parent = match parent {
+            Some(name) => Parent::Contextual(name.into()),
+            None => Parent::ContextualRoot,
+        };
+        NewSpan {
+            parent: Some(parent),
+            span: self,
+            ..Default::default()
+        }
+    }
+
     pub fn name(&self) -> Option<&str> {
         self.metadata.name.as_ref().map(String::as_ref)
     }
@@ -71,6 +104,7 @@ impl MockSpan {
         NewSpan {
             span: self,
             fields: fields.into(),
+            ..Default::default()
         }
     }
 
@@ -98,6 +132,40 @@ impl Into<NewSpan> for MockSpan {
     }
 }
 
+impl NewSpan {
+    pub fn with_explicit_parent(self, parent: Option<&str>) -> NewSpan {
+        let parent = match parent {
+            Some(name) => Parent::Explicit(name.into()),
+            None => Parent::ExplicitRoot,
+        };
+        NewSpan {
+            parent: Some(parent),
+            ..self
+        }
+    }
+
+    pub fn with_contextual_parent(self, parent: Option<&str>) -> NewSpan {
+        let parent = match parent {
+            Some(name) => Parent::Contextual(name.into()),
+            None => Parent::ContextualRoot,
+        };
+        NewSpan {
+            parent: Some(parent),
+            ..self
+        }
+    }
+
+    pub fn with_field<I>(self, fields: I) -> NewSpan
+    where
+        I: Into<field::Expect>,
+    {
+        NewSpan {
+            fields: fields.into(),
+            ..self
+        }
+    }
+}
+
 impl fmt::Display for NewSpan {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         write!(f, "a new span{}", self.span.metadata)?;