Struct console_subscriber::Builder

pub struct Builder { /* fields omitted */ }

Builder for configuring ConsoleLayers.

Implementations

impl Builder

pub fn event_buffer_capacity(self, event_buffer_capacity: usize) -> Self

Sets the maximum capacity for the channel of events sent from subscriber layers to the aggregator task.

When this channel is at capacity, additional events will be dropped.

By default, this is ConsoleLayer::DEFAULT_EVENT_BUFFER_CAPACITY.

pub fn client_buffer_capacity(self, client_buffer_capacity: usize) -> Self

Sets the maximum capacity of updates to buffer for each subscribed client, if that client is not reading from the RPC stream.

When this channel is at capacity, the client may be disconnected.

By default, this is ConsoleLayer::DEFAULT_CLIENT_BUFFER_CAPACITY.

pub fn publish_interval(self, publish_interval: Duration) -> Self

Sets how frequently updates are published to clients.

A shorter duration will allow clients to update more frequently, but may result in the program spending more time preparing task data updates.

By default, this is ConsoleLayer::DEFAULT_PUBLISH_INTERVAL. Methods like init and spawn will take the value from the TOKIO_CONSOLE_PUBLISH_INTERVAL environment variable before falling back on that default.

pub fn retention(self, retention: Duration) -> Self

Sets how long data is retained for completed tasks.

A longer duration will allow more historical data to be replayed by clients, but will result in increased memory usage. A shorter duration will reduce memory usage, but less historical data from completed tasks will be retained.

By default, this is ConsoleLayer::DEFAULT_RETENTION. Methods like init and spawn will take the value from the TOKIO_CONSOLE_RETENTION environment variable before falling back on that default.

pub fn server_addr(self, server_addr: impl Into<SocketAddr>) -> 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. Methods like init and spawn will parse the socket address from the TOKIO_CONSOLE_BIND environment variable before falling back on constructing a socket address from those defaults.

pub fn recording_path(self, path: impl Into<PathBuf>) -> Self

Sets the path to record the events to the file system.

By default, this is initially None. Methods like init and spawn will take the value from the TOKIO_CONSOLE_RECORD_PATH environment variable before falling back on that default.

pub fn build(self) -> (ConsoleLayer, Server)

Completes the builder, returning a ConsoleLayer and Server task.

pub fn with_default_env(self) -> Self

Configures this builder from a standard set of environment variables:

Environment Variable	Purpose	Default Value
TOKIO_CONSOLE_RETENTION	The duration of seconds to accumulate completed tracing data	3600s (1h)
TOKIO_CONSOLE_BIND	a HOST:PORT description, such as localhost:1234	127.0.0.1:6669
TOKIO_CONSOLE_PUBLISH_INTERVAL	The duration to wait between sending updates to the console	1000ms (1s)
TOKIO_CONSOLE_RECORD_PATH	The file path to save a recording	None

pub fn init(self)

Initializes the console tracing Subscriber and starts the console subscriber Server on its own background thread.

This function represents the easiest way to get started using tokio-console.

In addition to the ConsoleLayer, which collects instrumentation data consumed by the console, the default Subscriber initialized by this function also includes a tracing_subscriber::fmt layer, which logs tracing spans and events to stdout. Which spans and events are logged will be determined by the RUST_LOG environment variable.

Note: this function sets the default tracing subscriber for your application. If you need to add additional layers to a subscriber, see spawn.

Panics

• If the subscriber’s background thread could not be spawned.
• If the default tracing subscriber has already been set.

Configuration

Tokio console subscriber is configured with sensible defaults for most use cases. If you need to tune these parameters, several environmental configuration variables are available:

Environment Variable	Purpose	Default Value
TOKIO_CONSOLE_RETENTION	The number of seconds to accumulate completed tracing data	3600s (1h)
TOKIO_CONSOLE_BIND	A HOST:PORT description, such as localhost:1234	127.0.0.1:6669
TOKIO_CONSOLE_PUBLISH_INTERVAL	The number of milliseconds to wait between sending updates to the console	1000ms (1s)
TOKIO_CONSOLE_RECORD_PATH	The file path to save a recording	None
RUST_LOG	Configures what events are logged events. See Targets for details.	“error”

Further customization

To add additional layers or replace the format layer, replace console_subscriber::Builder::init with:

use tracing_subscriber::prelude::*;

let console_layer = console_subscriber::ConsoleLayer::builder().spawn();

tracing_subscriber::registry()
    .with(console_layer)
    .with(tracing_subscriber::fmt::layer())
//  .with(..potential additional layer..)
    .init();

pub fn spawn<S>(self) -> impl Layer<S> where
    S: Subscriber + for<'a> LookupSpan<'a>, 

Returns a new tracing Layer consisting of a ConsoleLayer and a filter that enables the spans and events required by the console.

This function spawns the console subscriber’s Server in its own Tokio runtime in a background thread.

Unlike init, this function does not set the default subscriber, allowing additional Layers to be added.

Panics

• If the subscriber’s background thread could not be spawned.

Configuration

console_subscriber::build supports all of the environmental configuration described at console_subscriber::init.

Differences from init

Unlike console_subscriber::init, this function does not add a tracing_subscriber::fmt layer to the configured Subscriber. This means that this function will not log spans and events based on the value of the RUST_LOG environment variable. Instead, a user-provided fmt::Layer can be added in order to customize the log format.

You must call .init() on the final subscriber in order to set the subscriber as the default.

Examples

use tracing_subscriber::prelude::*;

let console_layer = console_subscriber::ConsoleLayer::builder()
    .with_default_env()
    .spawn();

tracing_subscriber::registry()
    .with(console_layer)
    .with(tracing_subscriber::fmt::layer())
//  .with(...)
    .init();

Trait Implementations

impl Clone for Builder

fn clone(&self) -> Builder

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Builder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Builder

fn default() -> Self

Returns the “default value” for a type.