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 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 VariablePurposeDefault Value
TOKIO_CONSOLE_RETENTIONThe duration of seconds to accumulate completed tracing data3600s (1h)
TOKIO_CONSOLE_BINDa HOST:PORT description, such as localhost:1234127.0.0.1:6669
TOKIO_CONSOLE_PUBLISH_INTERVALThe duration to wait between sending updates to the console1000ms (1s)
TOKIO_CONSOLE_RECORD_PATHThe file path to save a recordingNone
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
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 VariablePurposeDefault Value
TOKIO_CONSOLE_RETENTIONThe number of seconds to accumulate completed tracing data3600s (1h)
TOKIO_CONSOLE_BINDA HOST:PORT description, such as localhost:1234127.0.0.1:6669
TOKIO_CONSOLE_PUBLISH_INTERVALThe number of milliseconds to wait between sending updates to the console1000ms (1s)
TOKIO_CONSOLE_RECORD_PATHThe file path to save a recordingNone
RUST_LOGConfigures 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();

Trait Implementations§

source§

impl Clone for Builder

source§

fn clone(&self) -> Builder

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for Builder

source§

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

Formats the value using the given formatter. Read more
source§

impl Default for Builder

source§

fn default() -> Self

Returns the “default value” for a type. Read more

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> FromRef<T> for Twhere T: Clone,

§

fn from_ref(input: &T) -> T

Converts to this type from a reference to the input type.
source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> IntoRequest<T> for T

source§

fn into_request(self) -> Request<T>

Wrap the input message T in a tonic::Request
source§

impl<T> ToOwned for Twhere T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for Twhere V: MultiLane<T>,

§

fn vzip(self) -> V

source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more