Crate vacro_trace

Crate vacro_trace 

Source
Expand description

§Vacro Trace

Observability for Rust Procedural Macros

§Introduction

vacro-trace brings familiar observability tools (logging, tracing, snapshots) to the world of Procedural Macro development.

It acts as the capture layer, designed to work hand-in-hand with vacro-cli (the visualization layer). While vacro-trace records the data, vacro-cli is required to view logs and inspect snapshot diffs.

§Features

  • Structured Logging: error!, warn!, info!, debug!, trace! macros.
  • Token Snapshots: Capture TokenStream states with tags. Same-tag snapshots are automatically diffed in vacro-cli.
  • Auto Instrumentation: #[instrument] attribute to automatically trace function calls.

§Usage

§1. Instrumentation

The macro entry needs to be marked with #[instrument].

ⓘ
#[instrument]
#[proc_macro]
fn parse_impl(input: proc_macro2::TokenStream) {
    // ...
}

§2. Snapshots & Diffing

Use snapshot!(tag, tokens) to capture the state of tokens at a specific point.

If you take multiple snapshots with the same tag (e.g., “transformation”), vacro-cli will automatically generate a diff view, showing how the tokens evolved.

let mut tokens = quote! { fn hello() {} };
// Initial state
snapshot!("my_macro", tokens);

// ... modify tokens ...
tokens = quote! { fn hello() { println!("world"); } };

// Final state - vacro-cli will show the diff between these two snapshots
snapshot!("my_macro", tokens);

§3. Logging

info!("Start expanding macro...");
warn!("Something looks suspicious: {}", "ident_name");

§Viewing Results

To view the captured data:

  1. Install the CLI: cargo install vacro-cli (or build from source).
  2. Run your build: cargo build.
  3. Open the TUI: vacro-cli.

§Vacro Trace

Rust 过程宏的可观测性工具集

§简介

vacro-trace 将熟悉的可观测性工具（日志、追踪、快照）引入到过程宏开发中。

它作为捕获层存在，设计上与 vacro-cli（可视化层）配合使用。vacro-trace 负责记录数据，而数据的查看和快照差异对比需要通过 vacro-cli 进行。

§特性

  • 结构化日志: error!, warn!, info!, debug!, trace! 宏。
  • Token 快照: 使用标签（Tag）捕获 TokenStream 状态。vacro-cli 会自动对比具有相同标签的快照差异（Diff）。
  • 自动仪表化: #[instrument] 属性，自动追踪函数调用。

§使用方法

§1. 仪表化 (Instrumentation)

需要为宏入口标记#[instrument]

ⓘ
#[instrument]
#[proc_macro]
fn parse_impl(input: proc_macro2::TokenStream) {
    // ...
}

§2. 快照与 Diff (Snapshots)

使用 snapshot!(tag, tokens) 来捕获特定时间点的 Token 状态。

如果你使用相同的标签（例如 “transformation”）进行了多次快照，vacro-cli 会自动生成差异视图，展示 Token 是如何演变的。

let mut tokens = quote! { fn hello() {} };
// 初始状态
snapshot!("my_macro", tokens);

// ... 修改 tokens ...
tokens = quote! { fn hello() { println!("world"); } };

// 最终状态 - vacro-cli 将展示这两次快照之间的 Diff
snapshot!("my_macro", tokens);

§3. 日志记录

info!("开始展开宏...");
warn!("看起来有点可疑: {}", "ident_name");

§查看结果

要查看捕获的数据：

  1. 安装 CLI: cargo install vacro-cli (或从源码编译)。
  2. 运行构建: cargo build。
  3. 打开 TUI: vacro-cli。

Macros§

debug
记录调试 (Debug) 级别的日志。
Logs a Debug level message.
error
记录错误 (Error) 级别的日志。
Logs an Error level message.
info
记录信息 (Info) 级别的日志。
Logs an Info level message.
log
通用日志宏。
Generic log macro.
snapshot
捕获 TokenStream 快照。
Capture a TokenStream snapshot.
trace
记录追踪 (Trace) 级别的日志。
Logs a Trace level message.
warn
记录警告 (Warn) 级别的日志。
Logs a Warn level message.

Enums§

Level
日志级别。
Log level.

Attribute Macros§

instrument
函数仪表化属性。
Function instrumentation attribute.