Doc additions for Simple and Batch processors (open-telemetry#2529)

Co-authored-by: Lalit Kumar Bhasin <lalit_fin@yahoo.com>

Author: cijothomas

opentelemetry-sdk/src/lib.rs

@@ -44,10 +44,7 @@
 //! [examples]: https://github.com/open-telemetry/opentelemetry-rust/tree/main/examples
 //! [`trace`]: https://docs.rs/opentelemetry/latest/opentelemetry/trace/index.html
 //!
-//! # Metrics (Alpha)
-//!
-//! Note: the metrics implementation is **still in progress** and **subject to major
-//! changes**.
+//! # Metrics
 //!
 //! ### Creating instruments and recording measurements
 //!

opentelemetry-sdk/src/logs/log_emitter.rs

@@ -185,21 +185,51 @@ pub struct Builder {
 }
 
 impl Builder {
-    /// The `LogExporter` that this provider should use.
+    /// Adds a [SimpleLogProcessor] with the configured exporter to the pipeline.
+    ///
+    /// # Arguments
+    ///
+    /// * `exporter` - The exporter to be used by the SimpleLogProcessor.
+    ///
+    /// # Returns
+    ///
+    /// A new `Builder` instance with the SimpleLogProcessor added to the pipeline.
+    ///
+    /// Processors are invoked in the order they are added.
     pub fn with_simple_exporter<T: LogExporter + 'static>(self, exporter: T) -> Self {
         let mut processors = self.processors;
         processors.push(Box::new(SimpleLogProcessor::new(exporter)));
 
         Builder { processors, ..self }
     }
 
-    /// The `LogExporter` setup using a default `BatchLogProcessor` that this provider should use.
+    /// Adds a [BatchLogProcessor] with the configured exporter to the pipeline.
+    ///
+    /// # Arguments
+    ///
+    /// * `exporter` - The exporter to be used by the BatchLogProcessor.
+    ///
+    /// # Returns
+    ///
+    /// A new `Builder` instance with the BatchLogProcessor added to the pipeline.
+    ///
+    /// Processors are invoked in the order they are added.
     pub fn with_batch_exporter<T: LogExporter + 'static>(self, exporter: T) -> Self {
         let batch = BatchLogProcessor::builder(exporter).build();
         self.with_log_processor(batch)
     }
 
-    /// The `LogProcessor` that this provider should use.
+    /// Adds a custom [LogProcessor] to the pipeline.
+    ///
+    /// # Arguments
+    ///
+    /// * `processor` - The `LogProcessor` to be added.
+    ///
+    /// # Returns
+    ///
+    /// A new `Builder` instance with the custom `LogProcessor` added to the pipeline.
+    ///
+    /// Processors are invoked in the order they are added.
     pub fn with_log_processor<T: LogProcessor + 'static>(self, processor: T) -> Self {
         let mut processors = self.processors;
         processors.push(Box::new(processor));

opentelemetry-sdk/src/logs/log_processor.rs

@@ -104,7 +104,18 @@ pub trait LogProcessor: Send + Sync + Debug {
 }
 
 /// A [`LogProcessor`] designed for testing and debugging purpose, that immediately
-/// exports log records as they are emitted.
+/// exports log records as they are emitted. Log records are exported synchronously
+/// in the same thread that emits the log record.
+/// When using this processor with the OTLP Exporter, the following exporter
+/// features are supported:
+/// - `grpc-tonic`: This requires LoggerProvider to be created within a tokio
+///   runtime. Logs can be emitted from any thread, including tokio runtime
+///   threads.
+/// - `reqwest-blocking-client`: LoggerProvider may be created anywhere, but
+///   logs must be emitted from a non-tokio runtime thread.
+/// - `reqwest-client`: LoggerProvider may be created anywhere, but logs must be
+///   emitted from a tokio runtime thread.
+///
 /// ## Example
 ///
 /// ### Using a SimpleLogProcessor

opentelemetry-sdk/src/trace/provider.rs

@@ -280,21 +280,51 @@ pub struct Builder {
 }
 
 impl Builder {
-    /// The `SpanExporter` that this provider should use.
+    /// Adds a [SimpleSpanProcessor] with the configured exporter to the pipeline.
+    ///
+    /// # Arguments
+    ///
+    /// * `exporter` - The exporter to be used by the SimpleSpanProcessor.
+    ///
+    /// # Returns
+    ///
+    /// A new `Builder` instance with the SimpleSpanProcessor added to the pipeline.
+    ///
+    /// Processors are invoked in the order they are added.
     pub fn with_simple_exporter<T: SpanExporter + 'static>(self, exporter: T) -> Self {
         let mut processors = self.processors;
         processors.push(Box::new(SimpleSpanProcessor::new(Box::new(exporter))));
 
         Builder { processors, ..self }
     }
 
-    /// The [`SpanExporter`] setup using a default [`BatchSpanProcessor`] that this provider should use.
+    /// Adds a [BatchSpanProcessor] with the configured exporter to the pipeline.
+    ///
+    /// # Arguments
+    ///
+    /// * `exporter` - The exporter to be used by the BatchSpanProcessor.
+    ///
+    /// # Returns
+    ///
+    /// A new `Builder` instance with the BatchSpanProcessor added to the pipeline.
+    ///
+    /// Processors are invoked in the order they are added.
     pub fn with_batch_exporter<T: SpanExporter + 'static>(self, exporter: T) -> Self {
         let batch = BatchSpanProcessor::builder(exporter).build();
         self.with_span_processor(batch)
     }
 
-    /// The [`SpanProcessor`] that this provider should use.
+    /// Adds a custom [SpanProcessor] to the pipeline.
+    ///
+    /// # Arguments
+    ///
+    /// * `processor` - The `SpanProcessor` to be added.
+    ///
+    /// # Returns
+    ///
+    /// A new `Builder` instance with the custom `SpanProcessor` added to the pipeline.
+    ///
+    /// Processors are invoked in the order they are added.
     pub fn with_span_processor<T: SpanProcessor + 'static>(self, processor: T) -> Self {
         let mut processors = self.processors;
         processors.push(Box::new(processor));

opentelemetry-sdk/src/trace/span_processor.rs

@@ -102,6 +102,17 @@ pub trait SpanProcessor: Send + Sync + std::fmt::Debug {
 /// `SpanExporter`, as soon as they are finished, without any batching. This is
 /// typically useful for debugging and testing. For scenarios requiring higher
 /// performance/throughput, consider using [BatchSpanProcessor].
+/// Spans are exported synchronously
+/// in the same thread that emits the log record.
+/// When using this processor with the OTLP Exporter, the following exporter
+/// features are supported:
+/// - `grpc-tonic`: This requires TracerProvider to be created within a tokio
+///   runtime. Spans can be emitted from any thread, including tokio runtime
+///   threads.
+/// - `reqwest-blocking-client`: TracerProvider may be created anywhere, but
+///   spans must be emitted from a non-tokio runtime thread.
+/// - `reqwest-client`: TracerProvider may be created anywhere, but spans must be
+///   emitted from a tokio runtime thread.
 #[derive(Debug)]
 pub struct SimpleSpanProcessor {
     exporter: Mutex<Box<dyn SpanExporter>>,
@@ -171,6 +182,13 @@ use crate::export::trace::ExportResult;
 /// individually. It uses a **dedicated background thread** to manage and export spans
 /// asynchronously, ensuring that the application's main execution flow is not blocked.
 ///
+/// When using this processor with the OTLP Exporter, the following exporter
+/// features are supported:
+/// - `grpc-tonic`: This requires `TracerProvider` to be created within a tokio
+///   runtime.
+/// - `reqwest-blocking-client`: Works with a regular `main` or `tokio::main`.
+///
+/// In other words, other clients like `reqwest` and `hyper` are not supported.
 /// /// # Example
 ///
 /// This example demonstrates how to configure and use the `BatchSpanProcessor`