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

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 <[email protected]>

Author: hds

Diff for: tokio-console/README.md

@@ -97,30 +97,87 @@ tokio-console http://my.instrumented.application.local:6669
 
 See [here][cli-ref] for a complete list of all command-line arguments.
 
+Tokio Console has a numnber of different views:
+* [Tasks List](#tasks-list)
+* [Task Details](#task-details)
+* [Resources List](#resources-list)
+* [Resource Details](#resource-details)
+
+### Tasks List
+
 When the console CLI is launched, it displays a list of all [asynchronous tasks]
 in the program:
 
 ![tasks list](https://raw.githubusercontent.com/tokio-rs/console/main/assets/tokio-console-0.1.8/tasks_list.png)
 
+Tasks are displayed in a table.
+
+* `Warn` - The number of warnings active for the task.
+* `ID` - The ID of the task. This is the same as the value returned by the unstable [`tokio::task::Id`](https://docs.rs/tokio/latest/tokio/task/struct.Id.html) API (see documentation for details).
+* `State` - The state of the task.
+  * `RUNNING`/▶ - Task is currently being polled.
+  * `IDLE`/⏸ - Task is waiting on some resource.
+  * `SCHED`/⏫ - Task is scheduled (it has been woken but not yet polled).
+  * `DONE`/⏹ - Task has completed.
+* `Name` - The name of the task, which can be set when spawning a task using the unstable [`tokio::task::Builder::name()`](https://docs.rs/tokio/latest/tokio/task/struct.Builder.html#method.name) API.
+* `Total` - Duration the task has been alive (sum of Busy, Sched, and Idle).
+* `Busy` - Total duration for which the task has been actively executing.
+* `Sched` - Total duration for which the task has been scheduled to be polled by the runtime.
+* `Idle` - Total duration for which the task has been idle (waiting to be woken).
+* `Polls` - Number of times the task has been polled.
+* `Target` - The target of the span used to record the task.
+  * `tokio::task` - Async task.
+  * `tokio::task::blocking` - A blocking task (created with [tokio::task::spawn_blocking](https://docs.rs/tokio/latest/tokio/task/fn.spawn_blocking.html)).
+* `Location` - The source code location where the task was spawned from.
+* `Fields` - Additional fields on the task span.
+  * `kind` - may be `task` (for async tasks) or `blocking` (for blocking tasks).
+  * `fn` - function signature for blocking tasks. Async tasks don't record this field, as it is generally very large when using `async`/`await`.
+
 Using the <kbd>&#8593;</kbd> and <kbd>&#8595;</kbd> arrow keys, an individual task can be highlighted.
 Pressing<kbd>enter</kbd> while a task is highlighted displays details about that
-task:
+task.
+
+### Task Details
+
+This view shows details about a specific task:
 
 ![task details](https://raw.githubusercontent.com/tokio-rs/console/main/assets/tokio-console-0.1.8/task_details.png)
 
+The task details view includes percentiles and a visual histogram of the polling (busy) times
+and scheduled times.
+
 Pressing the <kbd>escape</kbd> key returns to the task list.
 
+### Resources List
+
 The <kbd>r</kbd> key switches from the list of tasks to a list of [resources],
 such as synchronization primitives, I/O resources, et cetera:
 
 ![resource list](https://raw.githubusercontent.com/tokio-rs/console/main/assets/tokio-console-0.1.8/resources_list.png)
 
+Resources are displayed in a table similar to the task list.
+
+* `ID` - The ID of the resource. This is a display ID as there is no internal resource ID to reference.
+* `Parent` - The ID of the parent resource if it exists.
+* `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).
+* `Total` - Total duration that this resource has been alive.
+* `Target` - The module path of the resource type.
+* `Type` - The specific type of the resource, possible values depend on the resources instrumented in Tokio, which may vary between versions.
+* `Vis` - The visibility of the resource.
+  * `INT`/🔒 - Internal, this resource is only used by other resources.
+  * `PUB`/✅ - Public, available in the public Tokio API.
+* `Location` - The source code location where the resource was created.
+* `Attributes` - Additional resource-dependent attributes, for example a resource of type `Sleep` record the `duration` of the sleep.
 
 Pressing the <kbd>t</kbd> key switches the view back to the task list.
 
 Like the task list view, the resource list view can be navigated using the
 <kbd>&#8593;</kbd> and <kbd>&#8595;</kbd> arrow keys. Pressing <kbd>enter</kbd>
-while a resource is highlighted displays details about that resource:
+while a resource is highlighted displays details about that resource.
+
+### Resource Details
 
 ![resource details --- sleep](https://raw.githubusercontent.com/tokio-rs/console/main/assets/tokio-console-0.1.8/resource_details_sleep.png)
 
@@ -130,6 +187,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 those recorded for resources.
+* `Parent` - The ID of the parent async op, if it exists.
+* `Task` - The ID and name of the task which performed this async op.
+* `Source` - The method where the async op is being called from.
+* `Total` - Total duration for which the async op has been alive (sum of Busy and Idle, as an async op has no scheduled state).
+* `Busy` - Total duration for which the async op has been busy (its future is actively being polled).
+* `Idle` - Total duration for which the async op has been idle (the future exists but is not being polled).
+* `Polls` - Number of times the async op has been polled.
+* `Attributes` - Additional attributes from the async op. These will vary based on the type of the async op.
+
 Like the task details view, pressing the <kbd>escape</kbd> key while viewing a resource's details
 returns to the resource list.