docs(subscriber): console-subscriber API docs (#198)

Author: pnkfelix

console-subscriber/src/builder.rs

@@ -84,6 +84,11 @@ impl Builder {
     /// result in the program spending more time preparing task data updates.
     ///
     /// By default, this is [`ConsoleLayer::DEFAULT_PUBLISH_INTERVAL`].
+    /// Methods like [`init`][`crate::init`] and [`spawn`][`crate::spawn`] will
+    /// take the value from the `TOKIO_CONSOLE_PUBLISH_INTERVAL` [environment
+    /// variable] before falling back on that default.
+    ///
+    /// [environment variable]: `Builder::with_default_env`
     pub fn publish_interval(self, publish_interval: Duration) -> Self {
         Self {
             publish_interval,
@@ -98,15 +103,26 @@ impl Builder {
     /// will reduce memory usage, but less historical data from completed tasks
     /// will be retained.
     ///
-    /// By default, this is [`ConsoleLayer::DEFAULT_RETENTION`].
+    /// By default, this is [`ConsoleLayer::DEFAULT_RETENTION`]. Methods
+    /// like [`init`][`crate::init`] and [`spawn`][`crate::spawn`] will take the
+    /// value from the `TOKIO_CONSOLE_RETENTION` [environment variable] before
+    /// falling back on that default.
+    ///
+    /// [environment variable]: `Builder::with_default_env`
     pub fn retention(self, retention: Duration) -> Self {
         Self { retention, ..self }
     }
 
     /// Sets the socket address on which to serve the RPC server.
     ///
     /// By default, the server is bound on the IP address [`Server::DEFAULT_IP`]
-    /// on port [`Server::DEFAULT_PORT`].
+    /// on port [`Server::DEFAULT_PORT`]. Methods like
+    /// [`init`][`crate::init`] and [`spawn`][`crate::spawn`] will parse the
+    /// socket address from the `TOKIO_CONSOLE_BIND` [environment variable]
+    /// before falling back on constructing a socket address from those
+    /// defaults.
+    ///
+    /// [environment variable]: `Builder::with_default_env`
     pub fn server_addr(self, server_addr: impl Into<SocketAddr>) -> Self {
         Self {
             server_addr: server_addr.into(),
@@ -115,6 +131,13 @@ impl Builder {
     }
 
     /// Sets the path to record the events to the file system.
+    ///
+    /// By default, this is initially `None`. Methods like
+    /// [`init`][`crate::init`] and [`spawn`][`crate::spawn`] will take the
+    /// value from the `TOKIO_CONSOLE_RECORD_PATH` [environment variable] before
+    /// falling back on that default.
+    ///
+    /// [environment variable]: `Builder::with_default_env`
     pub fn recording_path(self, path: impl Into<PathBuf>) -> Self {
         Self {
             recording_path: Some(path.into()),

console-subscriber/src/lib.rs

@@ -38,6 +38,16 @@ pub use builder::{init, spawn};
 use crate::aggregator::Id;
 use crate::visitors::{PollOpVisitor, StateUpdateVisitor};
 
+/// A [`ConsoleLayer`] is a [`tracing_subscriber::Layer`] that records [`tracing`]
+/// spans and events emitted by the async runtime.
+///
+/// Runtimes emit [`tracing`] spans and events that represent specific operations
+/// that occur in asynchronous Rust programs, such as spawning tasks and waker
+/// operations. The `ConsoleLayer` collects and aggregates these events, and the
+/// resulting diagnostic data is exported to clients by the corresponding gRPC
+/// [`Server`] instance.
+///
+/// [`tracing`]: https://docs.rs/tracing
 pub struct ConsoleLayer {
     current_spans: ThreadLocal<RefCell<SpanStack>>,
     tx: mpsc::Sender<Event>,
@@ -60,7 +70,7 @@ pub struct ConsoleLayer {
     /// they might all have their own sets of waker ops.
     waker_callsites: Callsites<16>,
 
-    /// Set of callsites for spans reprenting resources
+    /// Set of callsites for spans representing resources
     ///
     /// TODO: Take some time to determine more reasonable numbers
     resource_callsites: Callsites<32>,
@@ -94,6 +104,17 @@ pub struct ConsoleLayer {
     no_dispatch: Dispatch,
 }
 
+/// A gRPC [`Server`] that implements the [`tokio-console` wire format][wire].
+///
+/// Client applications, such as the [`tokio-console CLI][cli] connect to the gRPC
+/// server, and stream data about the runtime's history (such as a list of the
+/// currently active tasks, or statistics summarizing polling times). A [`Server`] also
+/// interprets commands from a client application, such a request to focus in on
+/// a specific task, and translates that into a stream of details specific to
+/// that task.
+///
+/// [wire]: https://docs.rs/console-api
+/// [cli]: https://crates.io/crates/tokio-console
 pub struct Server {
     subscribe: mpsc::Sender<Command>,
     addr: SocketAddr,
@@ -209,11 +230,21 @@ enum WakeOp {
 }
 
 impl ConsoleLayer {
+    /// Returns a `ConsoleLayer` built with the default settings.
+    ///
+    /// Note: these defaults do *not* include values provided via the
+    /// environment variables specified in [`Builder::with_default_env`].
+    ///
+    /// See also [`Builder::build`].
     pub fn new() -> (Self, Server) {
         Self::builder().build()
     }
 
     /// Returns a [`Builder`] for configuring a `ConsoleLayer`.
+    ///
+    /// Note that the returned builder does *not* include values provided via
+    /// the environment variables specified in [`Builder::with_default_env`].
+    /// To extract those, you can call that method on the returned builder.
     pub fn builder() -> Builder {
         Builder::default()
     }
@@ -272,11 +303,45 @@ impl ConsoleLayer {
 }
 
 impl ConsoleLayer {
+    /// Default maximum capacity for the channel of events sent from a
+    /// [`ConsoleLayer`] to a [`Server`].
+    ///
+    /// When this capacity is exhausted, additional events will be dropped.
+    /// Decreasing this value will reduce memory usage, but may result in
+    /// events being dropped more frequently.
+    ///
+    /// See also [`Builder::event_buffer_capacity`].
     pub const DEFAULT_EVENT_BUFFER_CAPACITY: usize = 1024 * 10;
+    /// Default maximum capacity for th echannel of events sent from a
+    /// [`Server`] to each subscribed client.
+    ///
+    /// When this capacity is exhausted, the client is assumed to be inactive,
+    /// and may be disconnected.
+    ///
+    /// See also [`Builder::client_buffer_capacity`].
     pub const DEFAULT_CLIENT_BUFFER_CAPACITY: usize = 1024 * 4;
+
+    /// Default frequency for publishing events to clients.
+    ///
+    /// Note that methods like [`init`][`crate::init`] and [`spawn`][`crate::spawn`] will take the value
+    /// from the `TOKIO_CONSOLE_PUBLISH_INTERVAL` [environment variable] before falling
+    /// back on this default.
+    ///
+    /// See also [`Builder::publish_interval`].
+    ///
+    /// [environment variable]: `Builder::with_default_env`
     pub const DEFAULT_PUBLISH_INTERVAL: Duration = Duration::from_secs(1);
 
     /// By default, completed spans are retained for one hour.
+    ///
+    /// Note that methods like [`init`][`crate::init`] and
+    /// [`spawn`][`crate::spawn`] will take the value from the
+    /// `TOKIO_CONSOLE_RETENTION` [environment variable] before falling back on
+    /// this default.
+    ///
+    /// See also [`Builder::retention`].
+    ///
+    /// [environment variable]: `Builder::with_default_env`
     pub const DEFAULT_RETENTION: Duration = Duration::from_secs(60 * 60);
 
     fn is_spawn(&self, meta: &'static Metadata<'static>) -> bool {
@@ -641,13 +706,59 @@ impl fmt::Debug for ConsoleLayer {
 
 impl Server {
     // XXX(eliza): why is `SocketAddr::new` not `const`???
+    /// A [`Server`] by default binds socket address 127.0.0.1 to service remote
+    /// procedure calls.
+    ///
+    /// Note that methods like [`init`][`crate::init`] and
+    /// [`spawn`][`crate::spawn`] will parse the socket address from the
+    /// `TOKIO_CONSOLE_BIND` [environment variable] before falling back on
+    /// constructing a socket address from this default.
+    ///
+    /// See also [`Builder::server_addr`].
+    ///
+    /// [environment variable]: `Builder::with_default_env`
     pub const DEFAULT_IP: IpAddr = IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1));
+
+    /// A [`Server`] by default binds port 6669 to service remote procedure
+    /// calls.
+    ///
+    /// Note that methods like [`init`][`crate::init`] and
+    /// [`spawn`][`crate::spawn`] will parse the socket address from the
+    /// `TOKIO_CONSOLE_BIND` [environment variable] before falling back on
+    /// constructing a socket address from this default.
+    ///
+    /// See also [`Builder::server_addr`].
+    ///
+    /// [environment variable]: `Builder::with_default_env`
     pub const DEFAULT_PORT: u16 = 6669;
 
+    /// Starts the gRPC service with the default gRPC settings.
+    ///
+    /// To configure gRPC server settings before starting the server, use
+    /// [`serve_with`] instead. This method is equivalent to calling [`serve_with`]
+    /// and providing the default gRPC server settings:
+    ///
+    /// ```rust
+    /// # async fn docs() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
+    /// # let (_, server) = console_subscriber::ConsoleLayer::new();
+    /// server.serve_with(tonic::transport::Server::default()).await
+    /// # }
+    /// ```
+    /// [`serve_with`]: Server::serve_with
     pub async fn serve(self) -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
         self.serve_with(tonic::transport::Server::default()).await
     }
 
+    /// Starts the gRPC service with the given [`tonic`] gRPC transport server
+    /// `builder`.
+    ///
+    /// The `builder` parameter may be used to configure gRPC-specific settings
+    /// prior to starting the server.
+    ///
+    /// This spawns both the server task and the event aggregation worker
+    /// task on the current async runtime.
+    ///
+    /// [`tonic`]: https://docs.rs/tonic/
     pub async fn serve_with(
         mut self,
         mut builder: tonic::transport::Server,