Pipeline builder for stdout trace exporter (#224)

frigus02 · web-flow · commit 33ee1647b5c9 · 2020-09-24T09:09:54.000-07:00
diff --git a/examples/aws-xray/src/client.rs b/examples/aws-xray/src/client.rs
@@ -4,21 +4,17 @@ use opentelemetry::{api, exporter::trace::stdout, global, sdk};
 use opentelemetry_contrib::{XrayIdGenerator, XrayTraceContextPropagator};
 
 fn init_tracer() {
-    // Create stdout exporter to be able to retrieve the collected spans.
-    let exporter = stdout::Builder::default().init();
-
+    // Install stdout exporter pipeline to be able to retrieve the collected spans.
     // For the demonstration, use `Sampler::AlwaysOn` sampler to sample all traces. In a production
     // application, use `Sampler::ParentBased` or `Sampler::TraceIdRatioBased` with a desired ratio.
-    let provider = sdk::TracerProvider::builder()
-        .with_simple_exporter(exporter)
-        .with_config(sdk::Config {
+    stdout::new_pipeline()
+        .with_trace_config(sdk::Config {
             default_sampler: Box::new(sdk::Sampler::AlwaysOn),
             id_generator: Box::new(XrayIdGenerator::default()),
             ..Default::default()
         })
-        .build();
+        .install();
 
-    global::set_provider(provider);
     global::set_text_map_propagator(XrayTraceContextPropagator::new());
 }
 
diff --git a/examples/aws-xray/src/server.rs b/examples/aws-xray/src/server.rs
@@ -28,21 +28,17 @@ async fn handle(req: Request<Body>) -> Result<Response<Body>, Infallible> {
 }
 
 fn init_tracer() {
-    // Create stdout exporter to be able to retrieve the collected spans.
-    let exporter = stdout::Builder::default().init();
-
+    // Install stdout exporter pipeline to be able to retrieve the collected spans.
     // For the demonstration, use `Sampler::AlwaysOn` sampler to sample all traces. In a production
     // application, use `Sampler::ParentBased` or `Sampler::TraceIdRatioBased` with a desired ratio.
-    let provider = sdk::TracerProvider::builder()
-        .with_simple_exporter(exporter)
-        .with_config(sdk::Config {
+    stdout::new_pipeline()
+        .with_trace_config(sdk::Config {
             default_sampler: Box::new(sdk::Sampler::AlwaysOn),
             id_generator: Box::new(XrayIdGenerator::default()),
             ..Default::default()
         })
-        .build();
+        .install();
 
-    global::set_provider(provider);
     global::set_text_map_propagator(XrayTraceContextPropagator::new());
 }
 
diff --git a/examples/http/Cargo.toml b/examples/http/Cargo.toml
@@ -15,4 +15,3 @@ path = "src/client.rs"
 hyper = "0.13"
 tokio = { version = "0.2", features = ["full"] }
 opentelemetry = { path = "../../", features = ["http"] }
-opentelemetry-jaeger = { path = "../../opentelemetry-jaeger" }
diff --git a/examples/http/src/client.rs b/examples/http/src/client.rs
@@ -3,20 +3,15 @@ use opentelemetry::api::{Context, TextMapFormat, TraceContextExt, Tracer};
 use opentelemetry::{api, exporter::trace::stdout, global, sdk};
 
 fn init_tracer() {
-    // Create stdout exporter to be able to retrieve the collected spans.
-    let exporter = stdout::Builder::default().init();
-
+    // Install stdout exporter pipeline to be able to retrieve the collected spans.
     // For the demonstration, use `Sampler::AlwaysOn` sampler to sample all traces. In a production
     // application, use `Sampler::ParentBased` or `Sampler::TraceIdRatioBased` with a desired ratio.
-    let provider = sdk::TracerProvider::builder()
-        .with_simple_exporter(exporter)
-        .with_config(sdk::Config {
+    stdout::new_pipeline()
+        .with_trace_config(sdk::Config {
             default_sampler: Box::new(sdk::Sampler::AlwaysOn),
             ..Default::default()
         })
-        .build();
-
-    global::set_provider(provider);
+        .install();
 }
 
 #[tokio::main]
diff --git a/examples/http/src/server.rs b/examples/http/src/server.rs
@@ -17,20 +17,15 @@ async fn handle(req: Request<Body>) -> Result<Response<Body>, Infallible> {
 }
 
 fn init_tracer() {
-    // Create stdout exporter to be able to retrieve the collected spans.
-    let exporter = stdout::Builder::default().init();
-
+    // Install stdout exporter pipeline to be able to retrieve the collected spans.
     // For the demonstration, use `Sampler::AlwaysOn` sampler to sample all traces. In a production
     // application, use `Sampler::ParentBased` or `Sampler::TraceIdRatioBased` with a desired ratio.
-    let provider = sdk::TracerProvider::builder()
-        .with_simple_exporter(exporter)
-        .with_config(sdk::Config {
+    stdout::new_pipeline()
+        .with_trace_config(sdk::Config {
             default_sampler: Box::new(sdk::Sampler::AlwaysOn),
             ..Default::default()
         })
-        .build();
-
-    global::set_provider(provider);
+        .install();
 }
 
 #[tokio::main]
diff --git a/examples/stdout.rs b/examples/stdout.rs
@@ -1,25 +1,16 @@
 use opentelemetry::exporter::trace::stdout;
-use opentelemetry::{
-    api::{Tracer, TracerProvider},
-    global, sdk,
-};
+use opentelemetry::{api::Tracer, sdk};
 
 fn main() {
-    // Create stdout exporter to be able to retrieve the collected spans.
-    let exporter = stdout::Builder::default().init();
-
+    // Install stdout exporter pipeline to be able to retrieve collected spans.
     // For the demonstration, use `Sampler::AlwaysOn` sampler to sample all traces. In a production
     // application, use `Sampler::ParentBased` or `Sampler::TraceIdRatioBased` with a desired ratio.
-    let provider = sdk::TracerProvider::builder()
-        .with_simple_exporter(exporter)
-        .with_config(sdk::Config {
+    let tracer = stdout::new_pipeline()
+        .with_trace_config(sdk::Config {
             default_sampler: Box::new(sdk::Sampler::AlwaysOn),
             ..Default::default()
         })
-        .build();
-    global::set_provider(provider);
+        .install();
 
-    global::trace_provider()
-        .get_tracer("component-main", None)
-        .in_span("operation", |_cx| {});
+    tracer.in_span("operation", |_cx| {});
 }
diff --git a/opentelemetry-semantic-conventions/src/resource.rs b/opentelemetry-semantic-conventions/src/resource.rs
@@ -7,22 +7,20 @@
 //!
 //! ## Usage
 //!
-//! ```rust
+//! ```rust,no_run
 //! use opentelemetry::sdk;
 //! use opentelemetry_semantic_conventions as semcov;
 //! use std::sync::Arc;
 //!
-//! let exporter = opentelemetry::exporter::trace::stdout::Builder::default().init();
-//! let provider = sdk::TracerProvider::builder()
-//!    .with_simple_exporter(exporter)
-//!    .with_config(sdk::Config {
-//!        resource: Arc::new(sdk::Resource::new(vec![
-//!            semcov::resource::SERVICE_NAME.string("my-service"),
-//!            semcov::resource::SERVICE_NAMESPACE.string("my-namespace"),
-//!        ])),
-//!        ..sdk::Config::default()
-//!    })
-//!    .build();
+//! let _tracer = opentelemetry::exporter::trace::stdout::new_pipeline()
+//!     .with_trace_config(sdk::Config {
+//!         resource: Arc::new(sdk::Resource::new(vec![
+//!             semcov::resource::SERVICE_NAME.string("my-service"),
+//!             semcov::resource::SERVICE_NAMESPACE.string("my-namespace"),
+//!         ])),
+//!         ..sdk::Config::default()
+//!     })
+//!     .install();
 //! ```
 
 use opentelemetry::api::Key;
diff --git a/src/exporter/trace/stdout.rs b/src/exporter/trace/stdout.rs
@@ -10,62 +10,89 @@
 //!
 //! # Examples
 //!
-//! ```
+//! ```no_run
+//! use opentelemetry::api::Tracer;
 //! use opentelemetry::exporter::trace::stdout;
-//! use opentelemetry::{sdk, global};
 //!
-//! // Create a new stdout exporter that writes pretty printed span output
-//! let exporter = stdout::Builder::default().with_pretty_print(true).init();
-//! let provider = sdk::TracerProvider::builder()
-//!     .with_simple_exporter(exporter)
-//!     .build();
-//! global::set_provider(provider);
+//! fn main() {
+//!     let tracer = stdout::new_pipeline()
+//!         .with_pretty_print(true)
+//!         .install();
+//!
+//!     tracer.in_span("doing_work", |cx| {
+//!         // Traced app logic here...
+//!     });
+//! }
 //! ```
-use crate::exporter::trace;
+use crate::{api::TracerProvider, exporter::trace, global, sdk};
 use std::fmt::Debug;
 use std::io::{self, stdout, Stdout, Write};
 use std::sync::{Arc, Mutex};
 
-/// Builder
+/// Pipeline builder
 #[derive(Debug)]
-pub struct Builder<W: Write + Debug> {
-    writer: Mutex<W>,
+pub struct PipelineBuilder<W: Write> {
     pretty_print: bool,
+    trace_config: Option<sdk::Config>,
+    writer: W,
 }
 
-impl<W: Write + Debug> Builder<W> {
-    /// Specify the writer to use with this exporter
-    pub fn with_writer<T: Write + Debug>(self, writer: T) -> Builder<T> {
-        Builder {
-            writer: Mutex::new(writer),
-            pretty_print: self.pretty_print,
+/// Create a new stdout exporter pipeline builder.
+pub fn new_pipeline() -> PipelineBuilder<Stdout> {
+    PipelineBuilder::default()
+}
+
+impl Default for PipelineBuilder<Stdout> {
+    /// Return the default pipeline builder.
+    fn default() -> Self {
+        Self {
+            pretty_print: false,
+            trace_config: None,
+            writer: stdout(),
         }
     }
+}
 
-    /// Specify the pretty print setting for this exporter
-    pub fn with_pretty_print(self, pretty_print: bool) -> Self {
-        Builder {
-            pretty_print,
-            ..self
-        }
+impl<W: Write> PipelineBuilder<W> {
+    /// Specify the pretty print setting.
+    pub fn with_pretty_print(mut self, pretty_print: bool) -> Self {
+        self.pretty_print = pretty_print;
+        self
+    }
+
+    /// Assign the SDK trace configuration.
+    pub fn with_trace_config(mut self, config: sdk::Config) -> Self {
+        self.trace_config = Some(config);
+        self
     }
 
-    /// Build a new exporter
-    pub fn init(self) -> Exporter<W> {
-        Exporter {
-            writer: self.writer,
+    /// Specify the writer to use.
+    pub fn with_writer<T: Write>(self, writer: T) -> PipelineBuilder<T> {
+        PipelineBuilder {
             pretty_print: self.pretty_print,
+            trace_config: self.trace_config,
+            writer,
         }
     }
 }
 
-impl Default for Builder<Stdout> {
-    /// Return the default Exporter Builder.
-    fn default() -> Self {
-        Builder {
-            writer: Mutex::new(stdout()),
-            pretty_print: false,
+impl<W> PipelineBuilder<W>
+where
+    W: Write + Debug + Send + 'static,
+{
+    /// Install the stdout exporter pipeline with the recommended defaults.
+    pub fn install(mut self) -> sdk::Tracer {
+        let exporter = Exporter::new(self.writer, self.pretty_print);
+
+        let mut provider_builder = sdk::TracerProvider::builder().with_exporter(exporter);
+        if let Some(config) = self.trace_config.take() {
+            provider_builder = provider_builder.with_config(config);
         }
+        let provider = provider_builder.build();
+        let tracer = provider.get_tracer("opentelemetry", Some(env!("CARGO_PKG_VERSION")));
+        global::set_provider(provider);
+
+        tracer
     }
 }
 
@@ -80,6 +107,16 @@ pub struct Exporter<W: Write> {
     pretty_print: bool,
 }
 
+impl<W: Write> Exporter<W> {
+    /// Create a new stdout `Exporter`.
+    pub fn new(writer: W, pretty_print: bool) -> Self {
+        Self {
+            writer: Mutex::new(writer),
+            pretty_print,
+        }
+    }
+}
+
 impl<W> trace::SpanExporter for Exporter<W>
 where
     W: Write + Debug + Send + 'static,
@@ -99,7 +136,7 @@ where
                 }
             }
 
-            Ok(0)
+            Ok(())
         });
 
         if result.is_ok() {
@@ -109,7 +146,4 @@ where
             trace::ExportResult::FailedNotRetryable
         }
     }
-
-    /// Ignored for now.
-    fn shutdown(&self) {}
 }
