tokio-console CLI

🎛️ Tokio 控制台：异步 Rust 程序的调试器。

网站 | 聊天 | API 文档

概述

tokio-console 是异步 Rust 应用程序的调试和分析工具，它可以收集并显示应用程序中异步任务、资源和操作的详细信息。控制台系统由两个主要组件组成

• 📡️ 仪表化，嵌入到应用程序中，收集来自异步运行时的数据，并通过控制台的线格式暴露
• 🛰️ 消费者，连接到仪表化的应用程序，接收遥测数据并将其显示给用户

此代码包是 tokio-console 遥测的主要消费者，是一个提供交互式调试界面的命令行应用程序。

入门

要使用控制台监控和调试程序，必须对其进行仪表化以生成控制台消耗的数据。然后，可以使用 tokio-console CLI 应用程序连接到应用程序并监控其操作。

仪表化应用程序

在控制台可以连接到应用程序之前，它必须首先进行仪表化以记录 tokio-console 遥测。最简单的方法是 使用 console-subscriber 代码包。

console-subscriber 需要应用程序的异步运行时（或运行时）以控制台可以记录的格式发出 tracing 数据。对于使用 Tokio 运行时的程序，这意味着

• 必须启用 Tokio 的 不稳定特性。有关详细信息，请参阅 console-subscriber 文档。
• 必须使用 兼容的 Tokio 版本。要使用控制台，需要 Tokio v1.0 或更高版本，并且一些功能仅在后续版本中可用。请参阅 console-subscriber 文档 以获取详细信息。

使用控制台

一旦应用程序被监控，请使用以下命令安装控制台 CLI：

cargo install --locked tokio-console

在没有参数的情况下运行 tokio-console 将连接到本地主机上监听默认端口（端口 6669）的应用程序

tokio-console

如果应用程序没有在本地运行，或者被配置为监听不同的端口，控制台也将接受一个目标地址作为类似命令的参数

tokio-console http://192.168.0.42:9090

目标地址也可以是 DNS 名称

tokio-console http://my.instrumented.application.local:6669

有关所有命令行参数的完整列表，请参阅 此处。

Tokio 控制台有多种不同的视图

• 任务列表
• 任务详情
• 资源列表
• 资源详情

在 Windows 上运行控制台

控制台使用 UTF-8 字符集来在终端中显示图表和其他视觉功能。为了在 Windows 上显示这个丰富的终端 UI，需要使用一个启用 UTF-8 的终端模拟器，例如新的 Windows Terminal。

如果你使用支持 UTF-8 的终端，请确保显式地将 tokio-console 与 UTF-8 语言标志一起调用

tokio-console --lang en_US.UTF-8

任务列表

当控制台 CLI 启动时，它会显示程序中所有 异步任务 的列表

任务以表格形式显示。

• Warn - 任务中活动的警告数量。
• ID - 任务的 ID。这与不稳定 tokio::task::Id API 返回的值相同（请参阅文档以获取详细信息）。
• State - 任务的当前状态。
  • RUNNING/▶ - 任务目前正在被轮询。
  • IDLE/⏸ - 任务正在等待某些资源。
  • SCHED/⏫ - 任务已被调度（已被唤醒但尚未轮询）。
  • DONE/⏹ - 任务已完成。
• Name - 任务的名称，可以在使用不稳定 tokio::task::Builder::name() API 创建任务时设置。
• Total - 任务存活的总时间（忙、调度和空闲时间的总和）。
• Busy - 任务实际执行的总时间。
• Sched - 任务被调度以由运行时轮询的总时间。
• Idle - 任务空闲（等待唤醒）的总时间。
• Polls - 任务被轮询的次数。
• Target - 记录任务的跨度所使用的目标。
  • tokio::task - 异步任务。
  • tokio::task::blocking - 阻塞任务（使用 tokio::task::spawn_blocking 创建）。
• Location - 任务被创建的源代码位置。
• Fields - 任务跨度上的额外字段。
  • kind - 可能是 task（用于异步任务）或 blocking（用于阻塞任务）。
  • fn - 阻塞任务的功能签名。异步任务不记录此字段，因为它在使用 async/await 时通常非常大。

使用 ↑ 和 ↓ 光标键，可以突出显示单个任务。当任务被突出显示时按 enter 键将显示该任务的相关细节。

任务详情

此视图显示了特定任务的相关细节

任务详细信息视图包括轮询（忙碌）时间和计划时间的百分位数和视觉直方图。

按 escape 键将返回到任务列表。

资源列表

r 键将任务列表切换为资源列表，例如同步原语、I/O 资源等

资源以类似于任务列表的表格形式显示。

• ID - 资源的 ID。这是一个显示 ID，因为没有内部资源 ID 可用。
• Parent - 如果存在，则显示父资源的 ID。
• Kind - 资源类型，这是资源的高级分组。
  • Sync - 来自 tokio::sync 的同步资源，例如 Mutex。
  • Timer - 来自 tokio::time 的计时器资源，例如 Sleep。
• Total - 此资源存活的总时间。
• Target - 资源类型的模块路径。
• Type - 资源的具体类型，可能的值取决于在 Tokio 中配置的资源，这些值可能在不同版本之间有所不同。
• Vis - 资源的可见性。
  • INT/🔒 - 内部，此资源仅由其他资源使用。
  • PUB/✅ - 公开，可在公共 Tokio API 中使用。
• Location - 资源被创建的源代码位置。
• Attributes - 附加的资源相关属性，例如类型为 Sleep 的资源记录睡眠的 duration。

按 t 键将视图切换回任务列表。

与任务列表视图一样，资源列表视图可以使用 ↑ 和 ↓ 光标键进行导航。当资源被突出显示时按 enter 键将显示该资源的相关细节。

资源详情

资源详细信息视图列出了当前等待该资源的任务。这可能是一个单独的任务，例如上面的 tokio::time::Sleep，或者大量的任务，如这个私有的 tokio::sync::batch_semaphore::Semaphore

资源详细信息视图包括属于该资源的异步操作表。

• ID - 异步操作的ID。这是一个类似于资源记录的显示ID。
• Parent - 如果存在，父异步操作的ID。
• Task - 执行此异步操作的任务的ID和名称。
• Source - 异步操作被调用的方法。
• Total - 异步操作存活的总时长（忙和闲的总和，因为异步操作没有计划状态）。
• Busy - 异步操作忙的总时长（其未来正在被轮询）。
• Idle - 异步操作闲的总时长（存在但未被轮询的未来）。
• Polls - 异步操作被轮询的次数。
• Attributes - 异步操作的其他属性。这些将根据异步操作的类型而有所不同。

与任务详细信息视图类似，在查看资源详细信息时按 escape 键将返回资源列表。

可以使用配置文件（console.toml）来配置控制台的行为。有关详细信息，请参阅文档。

获取帮助

首先，看看您的答案是否可以在API文档中找到。如果那里没有答案，Tokio Discord服务器中有一个活跃的社区。我们很高兴尝试回答您的问题。您也可以在讨论页面上提出问题。

贡献

🎈 感谢您帮助改进项目！我们非常高兴有您！我们有一个贡献指南，帮助您参与Tokio控制台项目。

支持的Rust版本

Tokio控制台是基于最新的稳定版本构建的。最低支持的版本是1.74。当前Tokio控制台版本不一定可以在低于最低支持版本的Rust版本上构建。

许可证

本项目受MIT许可证许可。

贡献

除非您明确声明，否则您提交给Tokio的任何有意贡献的代码，均应按MIT许可，不附加任何其他条款或条件。