docs(console): add column descriptions for all tables #431

hds · 2023-06-06T15:55:18Z

We often receive questions about the meaning of certain columns in the
different views in Tokio Console.

This change adds additional documentation to the tokio-console README

which is also used in the docs.rs main page - describing each column
in the tasks, resources, and async ops tables. Where there are a fixed
set of values possible in the column, those values are also described.

Additionally, the 4 views are enumerated and separted into sections to
aid readability and allow deep linking.

We often receive questions about the meaning of certain columns in the different views in Tokio Console. This change adds additional documentation to the `tokio-console` README - which is also used in the docs.rs main page - describing each column in the tasks, resources, and async ops tables. Where there are a fixed set of values possible in the column, those values are also described. Additionally, the 4 views are enumerated and separted into sections to aid readability and allow deep linking.

hawkw

thanks for working on this! i had some minor edits to suggest.

tokio-console/README.md

hawkw · 2023-06-10T14:03:04Z

tokio-console/README.md

+* `Busy` - Total duration the async op has been busy
+* `Idle` - Total duration the async op has been idle
+* `Polls` - Number of times the async op has been polled
+* `Attributes` - Additional attributes from the async op, these will vary by type


Suggested change

* `Attributes` - Additional attributes from the async op, these will vary by type

* `Attributes` - Additional attributes from the async op. These will vary based on the type of the async op.

For consistency reasons, I'm trying to avoid multiple sentences in these bullet points becasue we don't put a full stop . at the end of the bullet point line. I've changed this to:

Additional attributes from the async op, these will vary based on the type of the async op

Co-authored-by: Eliza Weisman <eliza@buoyant.io>

hds

@hawkw Thanks for your suggestions! I've made all the changes.

hds · 2023-06-12T12:21:45Z

tokio-console/README.md

+* `Polls` - Number of times the task has been polled
+* `Target` - The taget of the span used to record the task
+  * `tokio::task` - Async task
+  * `tokio::task::blocking` - A blocking task


hds · 2023-06-12T12:24:36Z

tokio-console/README.md

+* `Kind` - The resource kind, this is a high level grouping of resources
+  * `Sync` - Synchronization resources from [`tokio::sync`](https://docs.rs/tokio/latest/tokio/sync/index.html) such as [`Mutex`](https://docs.rs/tokio/latest/tokio/sync/struct.Mutex.html)
+  * `Timer` - Timer resources from [`tokio::time`](https://docs.rs/tokio/latest/tokio/time/index.html) such as [`Sleep`](https://docs.rs/tokio/latest/tokio/time/struct.Sleep.html)
+ possible values depend on the resources instrumented in Tokio, which may vary between versions


This should actually have been part of the description for Type, I've moved it there.

tokio-console/README.md

hds · 2023-06-12T12:41:49Z

tokio-console/README.md

@@ -130,6 +188,18 @@ a large number of tasks, such as this private `tokio::sync::batch_semaphore::Sem

 ![resource details --- semaphore](https://raw.githubusercontent.com/tokio-rs/console/main/assets/tokio-console-0.1.8/resource_details_semaphore.png)

+The resource details view includes a table of async ops belonging to the resource.
+
+* `ID` - The ID of the async op, this is a display ID similar to the one for resources


For consistency reasons, I'm trying to avoid multiple sentences in these bullet points becasue we don't put a full stop . at the end of the bullet point line. I've changed this to:

The ID of the async op, this is a display ID similar to those recorded for resources

hds · 2023-06-12T12:42:33Z

tokio-console/README.md

+* `Busy` - Total duration the async op has been busy
+* `Idle` - Total duration the async op has been idle
+* `Polls` - Number of times the async op has been polled
+* `Attributes` - Additional attributes from the async op, these will vary by type


For consistency reasons, I'm trying to avoid multiple sentences in these bullet points becasue we don't put a full stop . at the end of the bullet point line. I've changed this to:

Additional attributes from the async op, these will vary based on the type of the async op

Also added full stops to all the bullet points to keep style consistent.

hawkw

looks good to me! thank you for working on this!

tokio-console/README.md

As suggested, to shwo that we display either text or the emoji. Co-authored-by: Eliza Weisman <eliza@buoyant.io>

hds · 2023-06-13T21:44:35Z

@hawkw Good idea about the slash, added those suggestions!

We often receive questions about the meaning of certain columns in the different views in Tokio Console. This change adds additional documentation to the `tokio-console` README - which is also used in the docs.rs main page - describing each column in the tasks, resources, and async ops tables. Where there are a fixed set of values possible in the column, those values are also described. Additionally, the 4 views are enumerated and separated into sections to aid readability and allow deep linking. Co-authored-by: Eliza Weisman <eliza@buoyant.io>

# Changelog All notable changes to this project will be documented in this file. This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## tokio-console-v0.1.10 - (2023-09-29) [7d009f8](https://github.com/tokio-rs/console/commit/7d009f87120ce0c89f5f9c5311f05b6756ca770f)...[7d009f8](https://github.com/tokio-rs/console/commit/7d009f87120ce0c89f5f9c5311f05b6756ca770f) ### <a id = "tokio-console-v0.1.10-breaking"></a>Breaking Changes - **Update Tonic and Prost dependencies ([#364](#364 ([f9b8e03](https://github.com/tokio-rs/console/commit/f9b8e03bd7ee1d0edb441c94a93a350d5b06ed3b))<br />This commit updates the public dependencies `prost` and `tonic` to semver-incompatible versions (v0.11.0 and v0.8.0, respectively). This is a breaking change for users who are integrating the `console-api` protos with their own `tonic` servers or clients. - **Update `tonic` to v0.10 and increase MSRV to 1.64 ([#464](#464 ([96e62c8](https://github.com/tokio-rs/console/commit/96e62c83ef959569bb062dc8fee98fa2b2461e8d))<br />This is a breaking change for users of `console-api` and `console-subscriber`, as it changes the public `tonic` dependency to a semver-incompatible version. This breaks compatibility with `tonic` 0.9.x and `prost` 0.11.x. ### Added - [**breaking**](#tokio-console-v0.1.10-breaking) Update Tonic and Prost dependencies ([#364](#364)) ([f9b8e03](f9b8e03)) - Only suggest opening issues for panics ([#365](#365)) ([da2a89c](da2a89c)) - Init error handling before subcmds ([#365](#365)) ([ec66eda](ec66eda)) - Filter out boring frames in backtraces ([#365](#365)) ([95a5e54](95a5e54)) - Include config options in autogenerated issues ([#365](#365)) ([3244a1f](3244a1f)) - Reduce decimal digits in UI ([#402](#402)) ([c13085e](c13085e)) - Use tokio task ids in task views ([#403](#403)) ([f5b06d2](f5b06d2)) - Add support for Unix domain sockets ([#388](#388)) ([a944dbc](a944dbc), closes [#296](#296)) - Add scheduled time per task ([#406](#406)) ([f280df9](f280df9)) - Add task scheduled times histogram ([#409](#409)) ([d92a399](d92a399)) - Update `tonic` to 0.9 ([#420](#420)) ([48af1ee](48af1ee)) - Update MSRV to Rust 1.60.0 ([b18ee47](b18ee47)) - Migrate to `ratatui` and update `crossterm` ([#425](#425)) ([b209dd6](b209dd6)) - Help view modal ([#432](#432)) ([359a4e7](359a4e7)) - Add way to inspect details of task from resource view ([#449](#449)) ([132ed4e](132ed4e), closes [#448](#448)) - Add warning for tasks that never yield ([#439](#439)) ([d05fa9e](d05fa9e)) - [**breaking**](#tokio-console-v0.1.10-breaking) Update `tonic` to v0.10 and increase MSRV to 1.64 ([#464](#464)) ([96e62c8](96e62c8)) ### Documented - Update screenshots in README ([#419](#419)) ([e9bcd67](e9bcd67)) - Revert "update screenshots in README ([#419](#419))" ([993a3d9](993a3d9)) - Update screenshots in README ([#421](#421)) ([8a27f96](8a27f96)) - Add column descriptions for all tables ([#431](#431)) ([e3cf82b](e3cf82b)) - Update MSRV version docs to 1.64 ([#467](#467)) ([94a5a51](94a5a51)) ### Fixed - Fix ascii-only flipped input ([#377](#377)) ([652ac34](652ac34)) - Declare `tokio-console` bin as `default-run` ([#379](#379)) ([9ce60ec](9ce60ec)) - Make `retain_for` default to 6s if not specfied ([#383](#383)) ([0a6012b](0a6012b), fixes [#382](#382)) - Enable view-switching keystrokes on details views ([#387](#387)) ([f417d7a](f417d7a)) - Fix `ViewOptions` default lang' ([#394](#394)) ([a1cf1b8](a1cf1b8), fixes [#393](#393)) - Remove `tracing-subscriber` 0.2 from dependencies ([#404](#404)) ([768534a](768534a)) - Fix calculation of busy time during poll ([#405](#405)) ([e2c536a](e2c536a)) - Remove histogram minimum count ([#424](#424)) ([02cf8a6](02cf8a6)) - Remove trailing space from task/resource location ([#443](#443)) ([90e5918](90e5918)) - Make long locations readable ([#441](#441)) ([9428d7f](9428d7f), closes [#411](#411)) - Fix task detail view Id to display remote tokio::task::Id ([#455](#455)) ([70c3952](70c3952)) Signed-off-by: Eliza Weisman <eliza@buoyant.io>

hds requested a review from a team as a code owner June 6, 2023 15:55

Merge branch 'main' into hds/docs-console-table-columns

f4734f7

hawkw requested changes Jun 10, 2023

View reviewed changes

hds and others added 3 commits June 12, 2023 10:53

Apply suggestions from code review

343d38d

Co-authored-by: Eliza Weisman <eliza@buoyant.io>

Merge branch 'main' into hds/docs-console-table-columns

36b0c9d

Additional changes based on review feedback

3dbb5e3

hds commented Jun 12, 2023

View reviewed changes

Break up some of the bullet points into multiple sentences

729678f

Also added full stops to all the bullet points to keep style consistent.

hawkw approved these changes Jun 12, 2023

View reviewed changes

tokio-console/README.md Outdated Show resolved Hide resolved

tokio-console/README.md Outdated Show resolved Hide resolved

Separate text and emoji with a /

3bb7875

As suggested, to shwo that we display either text or the emoji. Co-authored-by: Eliza Weisman <eliza@buoyant.io>

hawkw approved these changes Jun 14, 2023

View reviewed changes

hawkw merged commit 2de5b68 into main Jun 14, 2023
12 checks passed

hawkw deleted the hds/docs-console-table-columns branch June 14, 2023 14:58

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(console): add column descriptions for all tables #431

docs(console): add column descriptions for all tables #431

hds commented Jun 6, 2023

hawkw left a comment

hawkw Jun 10, 2023

hds Jun 12, 2023

hds left a comment

hds Jun 12, 2023

hds Jun 12, 2023

hds Jun 12, 2023

hds Jun 12, 2023

hawkw left a comment

hds commented Jun 13, 2023

	* `Attributes` - Additional attributes from the async op, these will vary by type
	* `Attributes` - Additional attributes from the async op. These will vary based on the type of the async op.

docs(console): add column descriptions for all tables #431

docs(console): add column descriptions for all tables #431

Conversation

hds commented Jun 6, 2023

hawkw left a comment

Choose a reason for hiding this comment

hawkw Jun 10, 2023

Choose a reason for hiding this comment

hds Jun 12, 2023

Choose a reason for hiding this comment

hds left a comment

Choose a reason for hiding this comment

hds Jun 12, 2023

Choose a reason for hiding this comment

hds Jun 12, 2023

Choose a reason for hiding this comment

hds Jun 12, 2023

Choose a reason for hiding this comment

hds Jun 12, 2023

Choose a reason for hiding this comment

hawkw left a comment

Choose a reason for hiding this comment

hds commented Jun 13, 2023