Skip to content

Commit

Permalink
Doc additions for Simple and Batch processors
Browse files Browse the repository at this point in the history
  • Loading branch information
cijothomas committed Jan 22, 2025
1 parent 90b0dd4 commit 52781ef
Show file tree
Hide file tree
Showing 5 changed files with 98 additions and 12 deletions.
5 changes: 1 addition & 4 deletions opentelemetry-sdk/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
//!
Expand Down
36 changes: 33 additions & 3 deletions opentelemetry-sdk/src/logs/log_emitter.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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));
Expand Down
13 changes: 12 additions & 1 deletion opentelemetry-sdk/src/logs/log_processor.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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 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
Expand Down
36 changes: 33 additions & 3 deletions opentelemetry-sdk/src/trace/provider.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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));
Expand Down
20 changes: 19 additions & 1 deletion opentelemetry-sdk/src/trace/span_processor.rs
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,18 @@ pub trait SpanProcessor: Send + Sync + std::fmt::Debug {
/// A [SpanProcessor] that passes finished spans to the configured
/// `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].
/// performance/throughput, consider using [BatchSpanProcessor].
/// 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 TracerProvider to be created within a tokio
/// runtime. Spans can 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>>,
Expand Down Expand Up @@ -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`
Expand Down

0 comments on commit 52781ef

Please sign in to comment.