From d79390303590a534a8224efbe96c6023c336a32f Mon Sep 17 00:00:00 2001 From: Nick Gerace Date: Fri, 8 Apr 2022 15:08:20 -0400 Subject: [PATCH] docs: add tokio-console installation section (#313) ## Description This PR adds a section for installing the tokio-console crate as well as fixes some broken console links. All changes were made to the README. Even though the tokio-console crate has its own README that includes installation, users will likely stumble upon the root README first. Thus, the purpose of this PR is to aid folks who may not wish to clone the repository when trying out the project. ## Commit Notes - Add tokio-console installation section in the README as the primary method of using tokio-console - Move the local cargo run option to its own alternative method section - Update broken console links to use tokio-console in the README - Add ".idea" to gitignore - Update cargo install to use "--locked" flag in the nested README ## Additional Notes Excellent project! Thank you for this. Signed-off-by: Nick Gerace Co-authored-by: Eliza Weisman --- .gitignore | 1 + README.md | 22 +++++++++++++++++----- tokio-console/README.md | 2 +- 3 files changed, 19 insertions(+), 6 deletions(-) diff --git a/.gitignore b/.gitignore index 19edc1803..883a2eba2 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ **/target **/result **/*.swp +**/.idea diff --git a/README.md b/README.md index fce2b7239..35029e44a 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ toolkit consists of multiple components: [`tracing`]. * tools for **displaying and exploring diagnostic data**, implemented as gRPC - clients using the console wire protocol. the [`console`] crate implements an + clients using the console wire protocol. the [`tokio-console`] crate implements an **an interactive command-line tool** that consumes this data, but **other implementations**, such as graphical or web-based tools, are also possible. @@ -129,11 +129,23 @@ notes: ### running the console -to **run the console command-line tool**, simply +to **run the console command-line tool**, install `tokio-console` from [crates.io](https://crates.io/crates/tokio-console) + +```shell +$ cargo install --locked tokio-console +``` + +and run locally + ```shell -$ cargo run +$ tokio-console ``` -in this repository. + +> **alternative method:** run the tool from a local checkout of this repository +> +> ```shell +> $ cargo run +> ``` by default, this will attempt to connect to an instrumented application running on localhost on port 6669. if the application is running somewhere else, or is @@ -248,7 +260,7 @@ cargo run --example $name [`tracing-subscriber`]: https://lib.rs/crates/tracing-subscriber [`console-api`]: ./console-api [`console-subscriber`]: ./console-subscriber -[`console`]: ./console +[`tokio-console`]: ./tokio-console [`Layer`]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/layer/trait.Layer.html [`tracing` targets]: https://docs.rs/tracing/latest/tracing/struct.Metadata.html [`TRACE` level]: https://docs.rs/tracing/latest/tracing/struct.Level.html#associatedconstant.TRACE diff --git a/tokio-console/README.md b/tokio-console/README.md index 6f78dca1a..33d5af66f 100644 --- a/tokio-console/README.md +++ b/tokio-console/README.md @@ -72,7 +72,7 @@ use the [Tokio] runtime, this means that: Once the application is instrumented, install the console CLI using ```shell -cargo install tokio-console +cargo install --locked tokio-console ``` Running `tokio-console` without any arguments will connect to an application on