@@ -64,25 +64,51 @@ where
6464 }
6565}
6666
67- /// A [MetricReader] that continuously collects and exports metrics at a set
68- /// interval.
67+ /// A `MetricReader` that periodically collects and exports metrics at a configurable interval.
6968///
70- /// By default, `PeriodicReader` will collect and export metrics every 60
71- /// seconds. The export time is not counted towards the interval between
72- /// attempts. `PeriodicReader` itself does not enforce a timeout. Instead, the
73- /// exporter is supposed to return with result in a configured time.
69+
70+ /// By default, [`PeriodicReader`] collects and exports metrics every **60 seconds**.
71+ /// The time taken for export is **not** included in the interval. Use [`PeriodicReaderBuilder`]
72+ /// to customize the interval.
73+ ///
74+ /// [`PeriodicReader`] spawns a background thread to handle metric collection and export.
75+ /// This thread remains active until [`shutdown()`] is called.
76+ ///
77+ /// ## Collection Process
78+ /// "Collection" refers to gathering aggregated metrics from the SDK's internal storage.
79+ /// During this phase, callbacks from observable instruments are also triggered.
80+ ///
81+ /// [`PeriodicReader`] does **not** enforce a timeout for collection. If an
82+ /// observable callback takes too long, it may delay the next collection cycle.
83+ /// If a callback never returns, it **will stall** all metric collection (and exports)
84+ /// indefinitely.
85+ ///
86+ /// ## Exporter Compatibility
87+ /// When used with the [`OTLP Exporter`](https://docs.rs/opentelemetry-otlp), the following
88+ /// transport options are supported:
89+ ///
90+ /// - **`grpc-tonic`**: Requires [`MeterProvider`] to be initialized within a `tokio` runtime.
91+ /// - **`reqwest-blocking-client`**: Works with both a standard (`main`) function and `tokio::main`.
92+ ///
93+ /// [`PeriodicReader`] does **not** enforce a timeout for exports either. Instead,
94+ /// the configured exporter is responsible for enforcing timeouts. If an export operation
95+ /// never returns, [`PeriodicReader`] will **stop exporting new metrics**, stalling
96+ /// metric collection.
7497///
75- /// `PeriodicReader` spawns a background thread to handle the periodic
76- /// collection and export of metrics. The background thread will continue to run
77- /// until `shutdown()` is called.
98+ /// ## Manual Export & Shutdown
99+ /// Users can manually trigger an export via [`force_flush()`]. Calling [`shutdown()`]
100+ /// exports any remaining metrics and should be done before application exit to ensure
101+ /// all data is sent.
78102///
79- /// When using this reader with the OTLP Exporter, the following exporter
80- /// features are supported:
81- /// - `grpc-tonic`: This requires `MeterProvider` to be created within a tokio
82- /// runtime.
83- /// - `reqwest-blocking-client`: Works with a regular `main` or `tokio::main`.
103+ /// **Warning**: If using **tokio’s current-thread runtime**, calling [`shutdown()`]
104+ /// from the main thread may cause a deadlock. To prevent this, call [`shutdown()`]
105+ /// from a separate thread or use tokio's `spawn_blocking`.
84106///
85- /// In other words, other clients like `reqwest` and `hyper` are not supported.
107+ /// [`PeriodicReader`]: crate::metrics::PeriodicReader
108+ /// [`PeriodicReaderBuilder`]: crate::metrics::PeriodicReaderBuilder
109+ /// [`MeterProvider`]: crate::metrics::SdkMeterProvider
110+ /// [`shutdown()`]: crate::metrics::SdkMeterProvider::shutdown
111+ /// [`force_flush()`]: crate::metrics::SdkMeterProvider::force_flush
86112///
87113/// # Example
88114///
0 commit comments