tokio-console subscriber

📡️ 一个用于收集 tracing-subscriber Layer 的 tokio-console 遥测数据的插件。

网站 | 聊天 | API文档

概述

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

• instrumentation，嵌入到应用程序中，它从异步运行时收集数据，并通过控制台的 线格式 公开数据
• consumers，如 tokio-console 命令行应用程序，它连接到已检测的应用程序，接收遥测数据并将其显示给用户

此crate使用tracing从异步运行时发出的数据实现了检测方面的接口。它提供了来自tracing-subscriber的Layer特质的类型，用于收集和聚合运行时的tracing数据，以及一个导出遥测到客户端的gRPC服务器。

入门

为了对异步应用程序进行监控，您必须使用支持控制台所需 tracing 监控的异步运行时。目前，唯一实现此监控功能的运行时是 Tokio 版本 1.7.0 及更高版本。

启用 Tokio 监控

⚠️ 目前，在 tokio 运行时中的 tracing 支持被视为 实验性的。为了使用 Tokio 与 console-subscriber，需要以下内容

• Tokio 的可选 tracing 依赖项必须启用。例如

  [dependencies]
  # ...
  tokio = { version = "1.15", features = ["full", "tracing"] }
  

• 必须启用启用 Tokio 中实验性 API 的 tokio_unstable cfg 标志。可以通过在构建时设置 RUSTFLAGS 环境变量来实现

  $ RUSTFLAGS="--cfg tokio_unstable" cargo build
  

  或者，将以下内容添加到 Cargo 项目的 .cargo/config.toml 文件中

  [build]
  rustflags = ["--cfg", "tokio_unstable"]
  

  如果您使用的是工作空间，应将 .cargo/config.toml 文件放在工作空间的根目录中。否则，请将 .cargo/config.toml 文件放在您的包根目录中。

  将 .cargo/config.toml 文件放在工作空间或包根目录以下可能会导致像 Rust-Analyzer 或 VSCode 这样的工具不使用您的 .cargo/config.toml，因为它们从工作空间或包根目录调用 cargo，而 cargo 只在当前和父目录中查找 .cargo 目录。Cargo 忽略子目录中的配置。有关 cargo 查找配置文件的更多信息，请参阅 这里。

  在编译时缺少此配置文件将导致 tokio-console 无法工作，并且交替构建包含和不包含此配置文件的文件将导致项目全面重建。

• 必须在 TRACE 级别 启用 tokio 和 runtime 的 tracing 目标。

  • 如果您使用的是 console_subscriber::init() 或 console_subscriber::Builder API，这些目标会自动启用。

  • 如果您正在手动使用来自 tracing-subscriber 的 EnvFilter 或 Targets 过滤器配置 tracing 订阅者，请将 "tokio=trace,runtime=trace" 添加到您的过滤器配置中。

  • 此外，请确保您在 Cargo.toml 中没有启用任何 编译时过滤器功能。

所需的 Tokio 版本

由于随着时间的推移，Tokio 中将添加对运行时不同方面的监控，因此通常建议使用最新版本的 Tokio 以访问控制台的所有功能。然而，它通常与更早的 Tokio 版本兼容，尽管某些信息可能不可用。要使用控制台的作业监控，需要 Tokio v1.0.0 或更高版本。

其他工具在后续的Tokio版本中添加

• 要记录任务唤醒器工具（如唤醒器计数、克隆、丢弃等），需要使用Tokio v1.7.0或更高版本。

• 要记录由Runtime::block_on和Handle::block_on方法创建的任务，需要使用Tokio v1.12.0或更高版本。

• 要跟踪如sleep和Interval等tokio::time资源，需要使用Tokio v1.13.0或更高版本。

• 要跟踪如Mutex、RwLock、Semaphore、oneshot通道、mpsc通道等tokio::sync资源，需要使用Tokio v1.15.0或更高版本。

• 要使用最新的task::Builder::spawn API，需要使用Tokio v1.21.0或更高版本。

添加控制台订阅者

如果运行时发出兼容的tracing事件，启用控制台只需将以下行添加到您的main函数中

hds_console_subscriber::init();

这会将默认的tracing订阅者设置为服务控制台遥测（同时根据RUST_LOG环境变量将日志记录到stdout）。可以通过一组环境变量配置控制台订阅者的行为。

对于程序化配置，还提供了一个构建器接口。

use std::time::Duration;

hds_console_subscriber::ConsoleLayer::builder()
    // set how long the console will retain data from completed tasks
    .retention(Duration::from_secs(60))
    // set the address the server is bound to
    .server_addr(([127, 0, 0, 1], 5555))
    // ... other configurations ...
    .init();

此crate提供的一层可以与其他crate的Layer结合使用。

use tracing_subscriber::prelude::*;

// spawn the console server in the background,
// returning a `Layer`:
let console_layer = hds_console_subscriber::spawn();

// build a `Subscriber` by combining layers with a
// `tracing_subscriber::Registry`:
tracing_subscriber::registry()
    // add the console layer to the subscriber
    .with(console_layer)
    // add other layers...
    .with(tracing_subscriber::fmt::layer())
 // .with(...)
    .init();

使用其他运行时

如果您使用的是支持tokio-console的自定义运行时，可能不需要启用tokio_unstable cfg标志。在这种情况下，您需要为console-subscriber启用cfg console_without_tokio_unstable来禁用其检查tokio_unstable。

crate特性标志

此crate提供以下特性标志和可选依赖项

• parking_lot：使用parking_lot crate的锁，而不是std::sync。使用parking_lot可能会提高性能，尤其是在高度并发的应用程序中。默认禁用。

获取帮助

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

贡献

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

支持的Rust版本

Tokio控制台是基于最新稳定版构建的。最低支持版本是1.64。当前Tokio控制台版本不保证在低于最低支持版本的Rust版本上构建。

许可证

本项目采用MIT许可证。

贡献

除非您明确声明，否则您提交给Tokio的任何有意包含的贡献，均应按照MIT许可证授权，不附加任何额外条款或条件。