tokio-console subscriber

📡️ 一个 tracing-subscriber Layer，用于收集 tokio-console 遥测。

网站 | 聊天 | API文档

概述

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

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

此代码包使用 tracing 提供的数据实现仪表化接口。它提供了来自 tracing-subscriber 的 Layer 特性，用于收集和聚合运行时的 tracing 数据，并导出遥测数据的gRPC服务器。

入门

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

启用 Tokio 调试功能

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

• 必须启用 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，这些目标将自动启用。

  • 如果您正在使用 EnvFilter 或 Targets 过滤器从 tracing-subscriber 手动配置 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或更高版本。

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

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

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

添加控制台订阅者

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

console_subscriber::init();

这设置了默认的tracing订阅者以服务控制台遥测（以及根据RUST_LOG环境变量进行基于标准输出的日志记录）。可以通过一组环境变量配置控制台订阅者的行为。

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

use std::time::Duration;

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 = 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.74。当前Tokio控制台版本不一定能在低于最低支持版本的Rust版本上构建。

许可证

本项目受MIT许可证许可。

贡献

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