diff --git a/console-subscriber/src/lib.rs b/console-subscriber/src/lib.rs index 0edfb7176..a5bf2d137 100644 --- a/console-subscriber/src/lib.rs +++ b/console-subscriber/src/lib.rs @@ -1000,7 +1000,8 @@ impl Server { /// tokio::spawn(serve); /// # // Avoid a warning that `console_layer` and `aggregator_handle` are unused. /// # drop(console_layer); - /// # drop(aggregator_handle); + /// # let mut aggregator_handle = aggregator_handle; + /// # aggregator_handle.abort(); /// # }); /// ``` /// @@ -1031,8 +1032,8 @@ impl Server { /// The `InstrumentServer` can be used to construct a router which /// can be added to a [`tonic`] gRPC server. /// -/// The [`AggregatorHandle`] must be kept until after the server has been -/// shut down. +/// The [`AggregatorHandle`] can be used to abort the associated aggregator task +/// after the server has been shut down. /// /// See the [`Server::into_parts`] documentation for usage. #[non_exhaustive] @@ -1050,15 +1051,32 @@ pub struct ServerParts { /// Aggregator handle. /// -/// This object is returned from [`Server::into_parts`] and must be -/// kept as long as the `InstrumentServer` - which is also -/// returned - is in use. +/// This object is returned from [`Server::into_parts`]. It can be +/// used to abort the aggregator task. +/// +/// The aggregator collects the traces that implement the async runtime +/// being observed and prepares them to be served by the gRPC server. +/// +/// Normally, if the server, started with [`Server::serve`] or +/// [`Server::serve_with`] stops for any reason, the aggregator is aborted, +/// hoewver, if the server was started with the [`InstrumentServer`] returned +/// from [`Server::into_parts`], then it is the responsibility of the user +/// of the API to stop the aggregator task by calling [`abort`] on this +/// object. +/// +/// [`abort`]: fn@crate::Aggregator::abort pub struct AggregatorHandle { join_handle: JoinHandle<()>, } -impl Drop for AggregatorHandle { - fn drop(&mut self) { +impl AggregatorHandle { + /// Aborts the task running this aggregator. + /// + /// To avoid having a disconnected aggregator running forever, this + /// method should be called when the [`tonic::transport::Server`] started + /// with the [`InstrumentServer`] also returned from [`Server::into_parts`] + /// stops running. + pub fn abort(&mut self) { self.join_handle.abort(); } }