features: Add "serialize" feature (#59)

Added optional `serialize` feature that allows `SpanData` to be
serialized/deserialized using the `serde` crate.

Also added a basic unit test for `SpanData` to test serialization and
deserialization.

Fixes: #58.

Signed-off-by: James O. D. Hunt <james.o.hunt@intel.com>

Author: Gmanboy

Cargo.toml

@@ -16,6 +16,8 @@ lazy_static = "1.4.0"
 pin-project = { version = "0.4.6", optional = true }
 prometheus = { version = "0.7.0", optional = true }
 rand = { version = "0.7.2", optional = true }
+serde = { version = "1.0.104", features = ["derive"], optional = true }
+bincode = { version = "1.2.1", optional = true }
 
 [dev-dependencies]
 hyper = "0.12.0"
@@ -28,6 +30,7 @@ tokio = { version = "0.2.10", features = ["full"] }
 default = ["metrics", "trace"]
 trace = ["rand", "pin-project"]
 metrics = ["prometheus"]
+serialize = ["serde", "bincode"]
 
 [workspace]
 members = [

scripts/test.sh

@@ -3,3 +3,4 @@
 set -eu
 
 cargo test --all "$@"
+cargo test --all "$@" --features="default serialize"

src/api/core.rs

@@ -1,7 +1,10 @@
 //! OpenTelemetry shared core date types
+#[cfg(feature = "serialize")]
+use serde::{Deserialize, Serialize};
 use std::borrow::Cow;
 
 /// Key used for metric `LabelSet`s and trace `Span` attributes.
+#[cfg_attr(feature = "serialize", derive(Deserialize, PartialEq, Serialize))]
 #[derive(Clone, Debug)]
 pub struct Key(Cow<'static, str>);
 
@@ -92,6 +95,7 @@ impl Into<String> for Key {
 }
 
 /// Value types for use in `KeyValue` pairs.
+#[cfg_attr(feature = "serialize", derive(Deserialize, PartialEq, Serialize))]
 #[derive(Clone, Debug)]
 pub enum Value {
     /// bool values
@@ -140,6 +144,7 @@ impl Into<Cow<'static, str>> for Value {
 }
 
 /// `KeyValue` pairs are used by `LabelSet`s and `Span` attributes.
+#[cfg_attr(feature = "serialize", derive(Deserialize, PartialEq, Serialize))]
 #[derive(Clone, Debug)]
 pub struct KeyValue {
     /// Dimension or event key

src/api/trace/event.rs

@@ -1,9 +1,12 @@
 //! # OpenTelemetry Trace Event Interface
 
+#[cfg(feature = "serialize")]
+use serde::{Deserialize, Serialize};
 use std::time::SystemTime;
 
 /// A `Span` has the ability to add events. Events have a time associated
 /// with the moment when they are added to the `Span`.
+#[cfg_attr(feature = "serialize", derive(Deserialize, PartialEq, Serialize))]
 #[derive(Clone, Debug)]
 pub struct Event {
     /// Event message

src/api/trace/link.rs

@@ -1,6 +1,9 @@
 //! # OpenTelemetry Trace Link Interface
+#[cfg(feature = "serialize")]
+use serde::{Deserialize, Serialize};
 
 /// 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.
+#[cfg_attr(feature = "serialize", derive(Deserialize, PartialEq, Serialize))]
 #[derive(Clone, Debug)]
 pub struct Link {}

src/api/trace/span.rs

@@ -16,6 +16,8 @@
 //! implementations MUST NOT allow callers to create Spans directly. All `Span`s MUST be created
 //! via a Tracer.
 use crate::api;
+#[cfg(feature = "serialize")]
+use serde::{Deserialize, Serialize};
 use std::time::SystemTime;
 
 /// Interface for a single operation within a trace.
@@ -168,6 +170,7 @@ pub trait Span: Send + Sync + std::fmt::Debug {
 /// | `PRODUCER` |     | yes |     | yes |
 /// | `CONSUMER` |     | yes | yes |     |
 /// | `INTERNAL` |     |     |     |     |
+#[cfg_attr(feature = "serialize", derive(Deserialize, PartialEq, Serialize))]
 #[derive(Clone, Debug)]
 pub enum SpanKind {
     /// Indicates that the span describes a synchronous request to
@@ -195,6 +198,7 @@ pub enum SpanKind {
 /// The `SpanStatus` interface represents the status of a finished `Span`.
 /// It's composed of a canonical code in conjunction with an optional
 /// descriptive message.
+#[cfg_attr(feature = "serialize", derive(Deserialize, PartialEq, Serialize))]
 #[derive(Clone, Debug)]
 pub enum SpanStatus {
     /// OK is returned on success.

src/api/trace/span_context.rs

@@ -10,6 +10,8 @@
 //! The spec can be viewed here: https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/api-tracing.md#spancontext
 //!
 //! [w3c TraceContext specification]: https://www.w3.org/TR/trace-context/
+#[cfg(feature = "serialize")]
+use serde::{Deserialize, Serialize};
 
 const TRACE_FLAGS_BIT_MASK_SAMPLED: u8 = 0x01;
 const TRACE_FLAGS_BIT_MASK_UNUSED: u8 = 0xFE;
@@ -21,6 +23,7 @@ pub const TRACE_FLAG_SAMPLED: u8 = TRACE_FLAGS_BIT_MASK_SAMPLED;
 pub const TRACE_FLAGS_UNUSED: u8 = TRACE_FLAGS_BIT_MASK_UNUSED;
 
 /// Immutable portion of a `Span` which can be serialized and propagated.
+#[cfg_attr(feature = "serialize", derive(Deserialize, Serialize))]
 #[derive(Clone, Debug, PartialEq)]
 pub struct SpanContext {
     trace_id: u128,

src/exporter/trace/mod.rs

@@ -1,5 +1,7 @@
 //! Trace exporters
 use crate::{api, sdk};
+#[cfg(feature = "serialize")]
+use serde::{Deserialize, Serialize};
 use std::sync::Arc;
 use std::time::SystemTime;
 
@@ -57,6 +59,7 @@ pub trait SpanExporter: Send + Sync + std::fmt::Debug {
 
 /// `SpanData` contains all the information collected by a `Span` and can be used
 /// by exporters as a standard input.
+#[cfg_attr(feature = "serialize", derive(Deserialize, PartialEq, Serialize))]
 #[derive(Clone, Debug)]
 pub struct SpanData {
     /// Exportable `SpanContext`
@@ -80,3 +83,51 @@ pub struct SpanData {
     /// Span status
     pub status: api::SpanStatus,
 }
+
+#[cfg(feature = "serialize")]
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_serialise() {
+        let trace_id = 7;
+        let span_id = 99;
+
+        let trace_flags = 0;
+        let remote = false;
+        let context = api::SpanContext::new(trace_id, span_id, trace_flags, remote);
+
+        let parent_span_id = 1;
+        let span_kind = api::SpanKind::Client;
+        let name = "foo/bar baz 人?!".to_string();
+        let start_time = SystemTime::now();
+        let end_time = SystemTime::now();
+
+        let capacity = 3;
+        let attributes = sdk::EvictedQueue::new(capacity);
+        let message_events = sdk::EvictedQueue::new(capacity);
+        let links = sdk::EvictedQueue::new(capacity);
+
+        let status = api::SpanStatus::OK;
+
+        let span_data = SpanData {
+            context,
+            parent_span_id,
+            span_kind,
+            name,
+            start_time,
+            end_time,
+            attributes,
+            message_events,
+            links,
+            status,
+        };
+
+        let encoded: Vec<u8> = bincode::serialize(&span_data).unwrap();
+
+        let decoded: SpanData = bincode::deserialize(&encoded[..]).unwrap();
+
+        assert_eq!(span_data, decoded);
+    }
+}

src/sdk/trace/evicted_queue.rs

@@ -1,10 +1,13 @@
 //! # Evicted Queue
 
+#[cfg(feature = "serialize")]
+use serde::{Deserialize, Serialize};
 use std::collections::VecDeque;
 
 /// This queue maintains an ordered list of elements, and a count of
 /// dropped elements. Elements are removed from the queue in a first
 /// in first out fashion.
+#[cfg_attr(feature = "serialize", derive(Deserialize, PartialEq, Serialize))]
 #[derive(Clone, Debug)]
 pub struct EvictedQueue<T> {
     queue: VecDeque<T>,