From a1113a1b5f39cfcda1502064804ce912d12d51d5 Mon Sep 17 00:00:00 2001 From: Hayden Stainsby Date: Tue, 6 Jun 2023 17:47:57 +0200 Subject: [PATCH 1/5] docs(console): add column descriptions for all tables 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. --- tokio-console/README.md | 74 +++++++++++++++++++++++++++++++++++++++-- 1 file changed, 72 insertions(+), 2 deletions(-) diff --git a/tokio-console/README.md b/tokio-console/README.md index 74ca34307..de39780f8 100644 --- a/tokio-console/README.md +++ b/tokio-console/README.md @@ -97,30 +97,88 @@ 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 unstable API: [`task::Id`](https://docs.rs/tokio/latest/tokio/task/struct.Id.html) (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 via the unstable [`task::Builder`](https://docs.rs/tokio/latest/tokio/task/struct.Builder.html) API +* `Total` - Duration the task has been alive (sum of Busy, Sched, and Idle) +* `Busy` - Total duration the task has been busy +* `Sched` - Total duration the task has been scheduled +* `Idle` - Total duration the task has been idle +* `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 +* `Location` - The source code location where the task was spawned from +* `Fields` - Additional fields on the task span + * `kind` - may be `task` or `blocking` + * `fn` - function signature of the blocking task, non-blocking tasks don't have this field as it can be very large + Using the ↑ and ↓ arrow keys, an individual task can be highlighted. Pressingenter 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 escape key returns to the task list. +### Resources List + The r 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) + possible values depend on the resources instrumented in Tokio, which may vary between versions +* `Total` - Duration the resource has been alive +* `Target` - The module of the resource +* `Type` - The specific type of the resource +* `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, these will vary by resource type Pressing the t key switches the view back to the task list. Like the task list view, the resource list view can be navigated using the ↑ and ↓ arrow keys. Pressing enter -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 +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 +* `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` - Duration the async op has been alive (sum of Busy and Idle, an async op has no scheduled state) +* `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 + Like the task details view, pressing the escape key while viewing a resource's details returns to the resource list. From 343d38d3664cf44b6c6a9d9784441e8421f748b2 Mon Sep 17 00:00:00 2001 From: Hayden Stainsby Date: Mon, 12 Jun 2023 10:53:04 +0200 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: Eliza Weisman --- tokio-console/README.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/tokio-console/README.md b/tokio-console/README.md index 6544e4267..d92393f0f 100644 --- a/tokio-console/README.md +++ b/tokio-console/README.md @@ -113,25 +113,25 @@ in the program: 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 unstable API: [`task::Id`](https://docs.rs/tokio/latest/tokio/task/struct.Id.html) (see documentation for details) +* `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 + * `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 via the unstable [`task::Builder`](https://docs.rs/tokio/latest/tokio/task/struct.Builder.html) API +* `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 the task has been busy -* `Sched` - Total duration the task has been scheduled -* `Idle` - Total duration the task has been 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 taget of the span used to record the task +* `Target` - The target of the span used to record the task * `tokio::task` - Async task * `tokio::task::blocking` - A blocking task * `Location` - The source code location where the task was spawned from * `Fields` - Additional fields on the task span - * `kind` - may be `task` or `blocking` - * `fn` - function signature of the blocking task, non-blocking tasks don't have this field as it can be very large + * `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 ↑ and ↓ arrow keys, an individual task can be highlighted. Pressingenter while a task is highlighted displays details about that @@ -163,8 +163,8 @@ Resources are displayed in a table similar to the task list. * `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 -* `Total` - Duration the resource has been alive -* `Target` - The module of the resource +* `Total` - Total duration that this resource has been alive +* `Target` - The module path of the resource type * `Type` - The specific type of the resource * `Vis` - The visibility of the resource * `INT` 🔒 - Internal, this resource is only used by other resources @@ -191,12 +191,12 @@ a large number of tasks, such as this private `tokio::sync::batch_semaphore::Sem 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 -* `Parent` - The ID of the parent async op if it exists +* `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` - Duration the async op has been alive (sum of Busy and Idle, an async op has no scheduled state) -* `Busy` - Total duration the async op has been busy -* `Idle` - Total duration the async op has been idle +* `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 by type From 3dbb5e3b0fbd5dc83aab26c79f523976ec927848 Mon Sep 17 00:00:00 2001 From: Hayden Stainsby Date: Mon, 12 Jun 2023 14:42:49 +0200 Subject: [PATCH 3/5] Additional changes based on review feedback --- tokio-console/README.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/tokio-console/README.md b/tokio-console/README.md index d92393f0f..f8e63d1f9 100644 --- a/tokio-console/README.md +++ b/tokio-console/README.md @@ -127,7 +127,7 @@ Tasks are displayed in a table. * `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 + * `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) @@ -162,15 +162,14 @@ Resources are displayed in a table similar to the task list. * `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 * `Total` - Total duration that this resource has been alive * `Target` - The module path of the resource type -* `Type` - The specific type of the resource +* `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, these will vary by resource type +* `Attributes` - Additional resource-dependent attributes, for example a resource of type `Sleep` record the `duration` of the sleep Pressing the t key switches the view back to the task list. @@ -190,7 +189,7 @@ a large number of tasks, such as this private `tokio::sync::batch_semaphore::Sem 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 +* `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 @@ -198,7 +197,7 @@ The resource details view includes a table of async ops belonging to the resourc * `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 by type +* `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 escape key while viewing a resource's details returns to the resource list. From 729678f7b8a6032d49e7b3abec80c2894aceed30 Mon Sep 17 00:00:00 2001 From: Hayden Stainsby Date: Mon, 12 Jun 2023 16:06:47 +0200 Subject: [PATCH 4/5] Break up some of the bullet points into multiple sentences Also added full stops to all the bullet points to keep style consistent. --- tokio-console/README.md | 82 ++++++++++++++++++++--------------------- 1 file changed, 41 insertions(+), 41 deletions(-) diff --git a/tokio-console/README.md b/tokio-console/README.md index f8e63d1f9..328a1a55f 100644 --- a/tokio-console/README.md +++ b/tokio-console/README.md @@ -112,25 +112,25 @@ in the program: 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) +* `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 ↑ and ↓ arrow keys, an individual task can be highlighted. @@ -157,19 +157,19 @@ such as synchronization primitives, I/O resources, et cetera: 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 +* `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 t key switches the view back to the task list. @@ -189,15 +189,15 @@ a large number of tasks, such as this private `tokio::sync::batch_semaphore::Sem 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 +* `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 escape key while viewing a resource's details returns to the resource list. From 3bb787502d72079427c0a5e36f15fbbc66e1e129 Mon Sep 17 00:00:00 2001 From: Hayden Stainsby Date: Tue, 13 Jun 2023 23:43:55 +0200 Subject: [PATCH 5/5] Separate text and emoji with a / As suggested, to shwo that we display either text or the emoji. Co-authored-by: Eliza Weisman --- tokio-console/README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/tokio-console/README.md b/tokio-console/README.md index 328a1a55f..12a7d466a 100644 --- a/tokio-console/README.md +++ b/tokio-console/README.md @@ -115,10 +115,10 @@ 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. + * `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. @@ -166,8 +166,8 @@ Resources are displayed in a table similar to the task list. * `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. + * `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.