|
| 1 | +use crate::TasksLayer; |
| 2 | +use std::thread; |
| 3 | +use tokio::runtime; |
| 4 | +use tracing_subscriber::{fmt, layer::Layered, prelude::*, EnvFilter, Registry}; |
| 5 | + |
| 6 | +type ConsoleSubscriberLayer = Layered<TasksLayer, Layered<EnvFilter, Registry>>; |
| 7 | + |
| 8 | +/// Starts the console subscriber server on its own thread. |
| 9 | +/// |
| 10 | +/// This function represents the easiest way to get started using |
| 11 | +/// tokio-console. |
| 12 | +/// |
| 13 | +/// **Note**: this function sets the [default `tracing` subscriber][default] |
| 14 | +/// for your application. If you need to add additional layers to this |
| 15 | +/// subscriber, see [`build`]. |
| 16 | +/// |
| 17 | +/// [default]: https://docs.rs/tracing/latest/tracing/dispatcher/index.html#setting-the-default-subscriber |
| 18 | +/// |
| 19 | +/// ## Configuration |
| 20 | +/// |
| 21 | +/// Tokio console subscriber is configured with sensible defaults for most |
| 22 | +/// use cases. If you need to tune these parameters, several environmental |
| 23 | +/// configuration variables are available: |
| 24 | +/// |
| 25 | +/// | **Environment Variable** | **Purpose** | **Default Value** | |
| 26 | +/// |-------------------------------------|---------------------------------------------------------------------------|-------------------| |
| 27 | +/// | `TOKIO_CONSOLE_RETENTION_SECS` | The number of seconds to accumulate completed tracing data | 3600s (1h) | |
| 28 | +/// | `TOKIO_CONSOLE_BIND` | A HOST:PORT description, such as `localhost:1234` | `127.0.0.1:6669` | |
| 29 | +/// | `TOKIO_CONSOLE_PUBLISH_INTERVAL_MS` | The number of milliseconds to wait between sending updates to the console | 1000ms (1s) | |
| 30 | +/// | `RUST_LOG` | Configure the tracing filter. See [`EnvFilter`] for further information | `tokio=trace` | |
| 31 | +/// |
| 32 | +/// ## Further customization |
| 33 | +/// |
| 34 | +/// To add additional layers or replace the format layer, replace |
| 35 | +/// `console_subscriber::init` with: |
| 36 | +/// |
| 37 | +/// ```rust |
| 38 | +/// use tracing_subscriber::prelude::*; |
| 39 | +/// console_subscriber::build() |
| 40 | +/// .with(tracing_subscriber::fmt::layer()) |
| 41 | +/// // .with(..potential additional layer..) |
| 42 | +/// .init(); |
| 43 | +/// ``` |
| 44 | +
|
| 45 | +pub fn init() { |
| 46 | + build().with(fmt::layer()).init() |
| 47 | +} |
| 48 | + |
| 49 | +/// Returns a new `tracing` [subscriber] configured with a [`TasksLayer`] |
| 50 | +/// and a [filter] that enables the spans and events required by the console. |
| 51 | +/// |
| 52 | +/// Unlike [`init`], this function does not set the default subscriber, allowing |
| 53 | +/// additional [`Layer`s] to be added. |
| 54 | +/// |
| 55 | +/// [subscriber]: https://docs.rs/tracing/latest/tracing/subscriber/trait.Subscriber.html |
| 56 | +/// [filter]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html |
| 57 | +/// |
| 58 | +/// ## Configuration |
| 59 | +/// |
| 60 | +/// `console_subscriber::build` supports all of the environmental |
| 61 | +/// configuration described at [`console_subscriber::init`][init] |
| 62 | +/// |
| 63 | +/// ## Differences from `init` |
| 64 | +/// |
| 65 | +/// **Note**: In order to support customizing the format `build` does |
| 66 | +/// not attach a [`tracing_subscriber::fmt::layer`], unlike [`init`]. |
| 67 | +/// |
| 68 | +/// Additionally, you must call |
| 69 | +/// [`init`][tracing_subscriber::util::SubscriberInitExt::init] on the |
| 70 | +/// final layer in order to register the subscriber. |
| 71 | +/// |
| 72 | +/// ## Examples |
| 73 | +/// |
| 74 | +/// ```rust |
| 75 | +/// use tracing_subscriber::prelude::*; |
| 76 | +/// console_subscriber::build() |
| 77 | +/// .with(tracing_subscriber::fmt::layer()) |
| 78 | +/// // .with(...) |
| 79 | +/// .init(); |
| 80 | +/// ``` |
| 81 | +
|
| 82 | +#[must_use = "build() without init() will not set the default tracing subscriber"] |
| 83 | +pub fn build() -> ConsoleSubscriberLayer { |
| 84 | + let (layer, server) = TasksLayer::builder().with_default_env().build(); |
| 85 | + |
| 86 | + let filter = EnvFilter::from_default_env().add_directive("tokio=trace".parse().unwrap()); |
| 87 | + |
| 88 | + let console_subscriber = tracing_subscriber::registry().with(filter).with(layer); |
| 89 | + |
| 90 | + thread::Builder::new() |
| 91 | + .name("console_subscriber".into()) |
| 92 | + .spawn(move || { |
| 93 | + let runtime = runtime::Builder::new_current_thread() |
| 94 | + .enable_io() |
| 95 | + .enable_time() |
| 96 | + .build() |
| 97 | + .expect("console subscriber runtime initialization failed"); |
| 98 | + |
| 99 | + runtime.block_on(async move { |
| 100 | + server |
| 101 | + .serve() |
| 102 | + .await |
| 103 | + .expect("console subscriber server failed") |
| 104 | + }); |
| 105 | + }) |
| 106 | + .expect("console subscriber could not spawn thread"); |
| 107 | + |
| 108 | + console_subscriber |
| 109 | +} |
0 commit comments