Doc additions to warn about tokio current

Author: cijothomas

opentelemetry-sdk/src/logs/log_processor.rs

@@ -228,19 +228,33 @@ type LogsData = Box<(LogRecord, InstrumentationScope)>;
 /// individually. It uses a **dedicated background thread** to manage and export logs
 /// asynchronously, ensuring that the application's main execution flow is not blocked.
 ///
-/// - This processor supports the following configurations:
-///     - **Queue size**: Maximum number of log records that can be buffered.
-///     - **Batch size**: Maximum number of log records to include in a single export.
-///     - **Scheduled delay**: Frequency at which the batch is exported.
+/// This processor supports the following configurations:
+/// - **Queue size**: Maximum number of log records that can be buffered.
+/// - **Batch size**: Maximum number of log records to include in a single export.
+/// - **Scheduled delay**: Frequency at which the batch is exported.
 ///
 /// When using this processor with the OTLP Exporter, the following exporter
 /// features are supported:
-/// - `grpc-tonic`: This requires `MeterProvider` to be created within a tokio
-///   runtime.
+/// - `grpc-tonic`: Requires `LoggerProvider` 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.
 ///
+/// `BatchLogProcessor` buffers logs in memory and exports them in batches. An
+/// export is triggered when `max_export_batch_size` is reached or every
+/// `scheduled_delay` milliseconds. Users can explicitly trigger an export using
+/// the `force_flush` method. Shutdown also triggers an export of all buffered
+/// logs and is recommended to be called before the application exits to ensure
+/// all buffered logs are exported.
+///
+/// **Warning**: When using tokio's current-thread runtime, `shutdown()`, which
+/// is a blocking call ,should not be called from your main thread. This can
+/// cause deadlock. Instead, call `shutdown()` from a separate thread or use
+/// tokio's `spawn_blocking`.
+///
+/// [`shutdown()`]: crate::logs::LoggerProvider::shutdown
+/// [`force_flush()`]: crate::logs::LoggerProvider::force_flush
+///
 /// ### Using a BatchLogProcessor:
 ///
 /// ```rust

opentelemetry-sdk/src/metrics/periodic_reader.rs

@@ -91,25 +91,50 @@ where
     }
 }
 
-/// A [MetricReader] that continuously collects and exports metrics at a set
-/// interval.
+/// A `MetricReader` that periodically collects and exports metrics at a configurable interval.
 ///
-/// By default, `PeriodicReader` will collect and export metrics every 60
-/// seconds. The export time is not counted towards the interval between
-/// attempts. `PeriodicReader` itself does not enforce a timeout. Instead, the
-/// timeout is passed on to the configured exporter for each export attempt.
+/// By default, [`PeriodicReader`] collects and exports metrics every **60 seconds**.
+/// The time taken for export is **not** included in the interval. Use [`PeriodicReaderBuilder`]
+/// to customize the interval.
 ///
-/// `PeriodicReader` spawns a background thread to handle the periodic
-/// collection and export of metrics. The background thread will continue to run
-/// until `shutdown()` is called.
+/// [`PeriodicReader`] spawns a background thread to handle metric collection and export.
+/// This thread remains active until [`shutdown()`] is called.
 ///
-/// When using this reader with the OTLP Exporter, the following exporter
-/// features are supported:
-/// - `grpc-tonic`: This requires `MeterProvider` to be created within a tokio
-///   runtime.
-/// - `reqwest-blocking-client`: Works with a regular `main` or `tokio::main`.
+/// ## Collection Process
+/// "Collection" refers to gathering aggregated metrics from the SDK's internal storage.
+/// During this phase, callbacks from observable instruments are also triggered.
 ///
-/// In other words, other clients like `reqwest` and `hyper` are not supported.
+/// [`PeriodicReader`] does **not** enforce a timeout for collection. If an
+/// observable callback takes too long, it may delay the next collection cycle.
+/// If a callback never returns, it **will stall** all metric collection (and exports)
+/// indefinitely.
+///
+/// ## Exporter Compatibility
+/// When used with the [`OTLP Exporter`](https://docs.rs/opentelemetry-otlp), the following
+/// transport options are supported:
+///
+/// - **`grpc-tonic`**: Requires [`MeterProvider`] to be initialized within a `tokio` runtime.
+/// - **`reqwest-blocking-client`**: Works with both a standard (`main`) function and `tokio::main`.
+///
+/// [`PeriodicReader`] does **not** enforce a timeout for exports either. Instead,
+/// the configured exporter is responsible for enforcing timeouts. If an export operation
+/// never returns, [`PeriodicReader`] will **stop exporting new metrics**, stalling
+/// metric collection.
+///
+/// ## Manual Export & Shutdown
+/// Users can manually trigger an export via [`force_flush()`]. Calling [`shutdown()`]
+/// exports any remaining metrics and should be done before application exit to ensure
+/// all data is sent.
+///
+/// **Warning**: If using **tokio’s current-thread runtime**, calling [`shutdown()`]
+/// from the main thread may cause a deadlock. To prevent this, call [`shutdown()`]
+/// from a separate thread or use tokio's `spawn_blocking`.
+///
+/// [`PeriodicReader`]: crate::metrics::PeriodicReader
+/// [`PeriodicReaderBuilder`]: crate::metrics::PeriodicReaderBuilder
+/// [`MeterProvider`]: crate::metrics::SdkMeterProvider
+/// [`shutdown()`]: crate::metrics::SdkMeterProvider::shutdown
+/// [`force_flush()`]: crate::metrics::SdkMeterProvider::force_flush
 ///
 /// # Example
 ///

opentelemetry-sdk/src/trace/span_processor.rs

@@ -253,7 +253,38 @@ enum BatchMessage {
     SetResource(Arc<Resource>),
 }
 
-/// A batch span processor with a dedicated background thread.
+/// The `BatchSpanProcessor` collects finished spans in a buffer and exports them
+/// in batches to the configured `SpanExporter`. This processor is ideal for
+/// high-throughput environments, as it minimizes the overhead of exporting spans
+/// individually. It uses a **dedicated background thread** to manage and export spans
+/// asynchronously, ensuring that the application's main execution flow is not blocked.
+///
+/// This processor supports the following configurations:
+/// - **Queue size**: Maximum number of spans that can be buffered.
+/// - **Batch size**: Maximum number of spans to include in a single export.
+/// - **Scheduled delay**: Frequency at which the batch is exported.
+///
+/// When using this processor with the OTLP Exporter, the following exporter
+/// features are supported:
+/// - `grpc-tonic`: 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.
+///
+/// `BatchSpanProcessor` buffers spans in memory and exports them in batches. An
+/// export is triggered when `max_export_batch_size` is reached or every
+/// `scheduled_delay` milliseconds. Users can explicitly trigger an export using
+/// the `force_flush` method. Shutdown also triggers an export of all buffered
+/// spans and is recommended to be called before the application exits to ensure
+/// all buffered spans are exported.
+///
+/// **Warning**: When using tokio's current-thread runtime, `shutdown()`, which
+/// is a blocking call ,should not be called from your main thread. This can
+/// cause deadlock. Instead, call `shutdown()` from a separate thread or use
+/// tokio's `spawn_blocking`.
+///
+/// [`shutdown()`]: crate::trace::TracerProvider::shutdown
+/// [`force_flush()`]: crate::trace::TracerProvider::force_flush
 #[derive(Debug)]
 pub struct BatchSpanProcessor {
     span_sender: SyncSender<SpanData>, // Data channel to store spans