[trace] Move SpanProcessor into sdk. Use ReadableSpan as parameter in on_start (open-telemetry#334)

Author: TommyCpp

opentelemetry/src/api/trace/mod.rs

@@ -119,7 +119,6 @@ mod noop;
 mod provider;
 mod span;
 mod span_context;
-mod span_processor;
 mod tracer;
 
 pub use self::{
@@ -135,6 +134,5 @@ pub use self::{
         SpanContext, SpanId, TraceId, TraceState, TRACE_FLAG_DEBUG, TRACE_FLAG_DEFERRED,
         TRACE_FLAG_NOT_SAMPLED, TRACE_FLAG_SAMPLED,
     },
-    span_processor::SpanProcessor,
     tracer::{SpanBuilder, Tracer},
 };

opentelemetry/src/api/trace/span_processor.rs

@@ -24,6 +24,6 @@ pub use provider::{Builder, TracerProvider};
 pub use sampler::{Sampler, SamplingDecision, SamplingResult, ShouldSample};
 pub use span::Span;
 pub use span_processor::{
-    BatchConfig, BatchSpanProcessor, BatchSpanProcessorBuilder, SimpleSpanProcessor,
+    BatchConfig, BatchSpanProcessor, BatchSpanProcessorBuilder, SimpleSpanProcessor, SpanProcessor,
 };
 pub use tracer::Tracer;

opentelemetry/src/sdk/trace/mod.rs

@@ -9,7 +9,7 @@
 //! not duplicate this data to avoid that different `Tracer` instances
 //! of the `TracerProvider` have different versions of these data.
 use crate::exporter::trace::SpanExporter;
-use crate::{sdk, trace::SpanProcessor};
+use crate::{sdk, sdk::trace::SpanProcessor};
 use std::sync::Arc;
 
 /// Default tracer name if empty string is provided.

opentelemetry/src/sdk/trace/provider.rs

@@ -1,6 +1,41 @@
+//! # OpenTelemetry Span Processor Interface
+//!
+//! Span processor is an interface which allows hooks for span start and end method
+//! invocations. The span processors are invoked only when
+//! [`is_recording`] is true.
+//!
+//! Built-in span processors are responsible for batching and conversion of spans to
+//! exportable representation and passing batches to exporters.
+//!
+//! Span processors can be registered directly on SDK [`TracerProvider`] and they are
+//! invoked in the same order as they were registered.
+//!
+//! All `Tracer` instances created by a `TracerProvider` share the same span processors.
+//! Changes to this collection reflect in all `Tracer` instances.
+//!
+//! The following diagram shows `SpanProcessor`'s relationship to other components
+//! in the SDK:
+//!
+//! ```ascii
+//!   +-----+--------------+   +-----------------------+   +-------------------+
+//!   |     |              |   |                       |   |                   |
+//!   |     |              |   | (Batch)SpanProcessor  |   |    SpanExporter   |
+//!   |     |              +---> (Simple)SpanProcessor +--->  (JaegerExporter) |
+//!   |     |              |   |                       |   |                   |
+//!   | SDK | Tracer.span()|   +-----------------------+   +-------------------+
+//!   |     | Span.end()   |
+//!   |     |              |   +---------------------+
+//!   |     |              |   |                     |
+//!   |     |              +---> ZPagesProcessor     |
+//!   |     |              |   |                     |
+//!   +-----+--------------+   +---------------------+
+//! ```
+//!
+//! [`is_recording`]: ../span/trait.Span.html#method.is_recording
+//! [`TracerProvider`]: ../provider/trait.TracerProvider.html
+use crate::sdk::trace::Span;
 use crate::{
     exporter::trace::{SpanData, SpanExporter},
-    trace::{Span, SpanProcessor},
     Context,
 };
 use futures::{channel::mpsc, executor, future::BoxFuture, Future, FutureExt, Stream, StreamExt};
@@ -23,6 +58,18 @@ const OTEL_BSP_MAX_EXPORT_BATCH_SIZE: &str = "OTEL_BSP_MAX_EXPORT_BATCH_SIZE";
 /// Default maximum batch size
 const OTEL_BSP_MAX_EXPORT_BATCH_SIZE_DEFAULT: usize = 512;
 
+/// `SpanProcessor`s allow hooks for span start and end method invocations.
+pub trait SpanProcessor: Send + Sync + std::fmt::Debug {
+    /// `on_start` method is invoked when a `Span` is started.
+    fn on_start(&self, span: &Span, cx: &Context);
+    /// `on_end` method is invoked when a `Span` is ended.
+    fn on_end(&self, span: SpanData);
+    /// Shutdown is invoked when SDK shuts down. Use this call to cleanup any
+    /// processor data. No calls to `on_start` and `on_end` method is invoked
+    /// after `shutdown` call is made.
+    fn shutdown(&mut self);
+}
+
 /// A [`SpanProcessor`] that exports synchronously when spans are finished.
 ///
 /// # Examples
@@ -58,7 +105,7 @@ impl SimpleSpanProcessor {
 }
 
 impl SpanProcessor for SimpleSpanProcessor {
-    fn on_start(&self, _span: &dyn Span, _cx: &Context) {
+    fn on_start(&self, _span: &Span, _cx: &Context) {
         // Ignored
     }
 
@@ -127,7 +174,7 @@ impl fmt::Debug for BatchSpanProcessor {
 }
 
 impl SpanProcessor for BatchSpanProcessor {
-    fn on_start(&self, _span: &dyn Span, _cx: &Context) {
+    fn on_start(&self, _span: &Span, _cx: &Context) {
         // Ignored
     }