From 7d16eadc5c254f21b0f4fba31f2fdf758808a8f4 Mon Sep 17 00:00:00 2001 From: Felix S Klock II Date: Wed, 15 Dec 2021 18:59:09 -0500 Subject: [PATCH] docs(subscriber): console-subscriber API docs (#198) --- console-subscriber/src/builder.rs | 27 ++++++- console-subscriber/src/lib.rs | 113 +++++++++++++++++++++++++++++- 2 files changed, 137 insertions(+), 3 deletions(-) diff --git a/console-subscriber/src/builder.rs b/console-subscriber/src/builder.rs index 1b1396a42..65eba8705 100644 --- a/console-subscriber/src/builder.rs +++ b/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,7 +103,12 @@ 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 } } @@ -106,7 +116,13 @@ impl Builder { /// 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) -> 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) -> Self { Self { recording_path: Some(path.into()), diff --git a/console-subscriber/src/lib.rs b/console-subscriber/src/lib.rs index 6e0cd0159..85dd31666 100644 --- a/console-subscriber/src/lib.rs +++ b/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>, tx: mpsc::Sender, @@ -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, 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> { + /// # 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> { 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,