Struct Builder

source

pub struct Builder { /* private fields */ }

Expand description

Builder for configuring ConsoleLayers.

Implementations§

source §

impl Builder

source

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.

source

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.

source

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.

source

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.

source

pub fn server_addr(self, server_addr: impl Into<ServerAddr>) -> 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.

The socket address can be either a TCP socket address or a Unix domain socket (UDS) address. Unix domain sockets are only supported on Unix-compatible operating systems, such as Linux, BSDs, and macOS.

Each call to this method will overwrite the previously set value.

§Examples

Connect to the TCP address localhost:1234:

use std::net::Ipv4Addr;
let builder = Builder::default().server_addr((Ipv4Addr::LOCALHOST, 1234));

Connect to the UDS address /tmp/tokio-console:

use std::path::Path;

// Unix domain sockets are only available on Unix-compatible operating systems.
#[cfg(unix)]
let builder = Builder::default().server_addr(Path::new("/tmp/tokio-console"));

source

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.

source

pub fn filter_env_var(self, filter_env_var: impl Into<String>) -> Self

Sets the environment variable used to configure which tracing events are logged to stdout.

The Builder::init method configures the default tracing subscriber. In addition to a ConsoleLayer, the subscriber constructed by init includes a fmt::Layer for logging events to stdout. What tracing events that layer will log is determined by the value of an environment variable; this method configures which environment variable is read to determine the log filter.

This environment variable does not effect what spans and events are recorded by the ConsoleLayer. Therefore, this method will have no effect if the builder is used with Builder::spawn or Builder::build.

The default environment variable is RUST_LOG. See here for details on the syntax for configuring the filter.

source

pub fn poll_duration_histogram_max(self, max: Duration) -> Self

Sets the maximum value for task poll duration histograms.

Any poll durations exceeding this value will be clamped down to this duration and recorded as an outlier.

By default, this is one second. Higher values will increase per-task memory usage.

source

pub fn scheduled_duration_histogram_max(self, max: Duration) -> Self

Sets the maximum value for task scheduled duration histograms.

Any scheduled duration (the time from a task being woken until it is next polled) exceeding this value will be clamped down to this duration and recorded as an outlier.

By default, this is one second. Higher values will increase per-task memory usage.

source

pub fn enable_self_trace(self, self_trace: bool) -> Self

Sets whether tasks, resources, and async ops from the console subscriber thread are recorded.

By default, events from the console subscriber are discarded and not exported to clients.

source

pub fn enable_grpc_web(self, enable_grpc_web: bool) -> Self

Sets whether to enable the grpc-web support.

By default, this is false. If enabled, the console subscriber will serve the gRPC-Web protocol in addition to the standard gRPC protocol. This is useful for serving the console subscriber to web clients. Please be aware that the current default server port is set to 6669. However, certain browsers may restrict this port due to security reasons. If you encounter issues with this, consider changing the port to an alternative one that is not commonly blocked by browsers.

serve_with_grpc_web is used to provide more advanced configuration for the gRPC-Web server.

source

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

Completes the builder, returning a ConsoleLayer and Server task.

source

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

source

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 an environment variable, which defaults to RUST_LOG. The Builder::filter_env_var method can be used to override the environment variable used to configure the log filter.

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”

If the “env-filter” crate feature flag is enabled, the RUST_LOG environment variable will be parsed using the EnvFilter type from tracing-subscriber. If the “env-filter” feature is not enabled, the Targets filter is used instead. The EnvFilter type accepts all the same syntax as Targets, but with the added ability to filter dynamically on span field values. See the documentation for those types for details.

§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();

source

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();