Crate vacro_trace

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:

Install the CLI: cargo install vacro-cli (or build from source).
Run your build: cargo build.
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");

§查看结果

要查看捕获的数据：

安装 CLI: cargo install vacro-cli (或从源码编译)。
运行构建: cargo build。
打开 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.

记录一条指定级别的日志消息。

Logs a message at the specified level.
snapshot: 捕获 TokenStream 快照。

Capture a TokenStream snapshot.

将当前的 Token 状态记录下来，以便在 `vacro-cli` 中查看。如果使用相同的 tag 调用多次，会自动展示 Diff。用法：`snapshot!("tag", tokens)`

Records the current token state for inspection in `vacro-cli`. If called multiple times with the same tag, it will automatically show a Diff. Usage: `snapshot!("tag", tokens)`
trace: 记录追踪 (Trace) 级别的日志。

Logs a Trace level message.
warn: 记录警告 (Warn) 级别的日志。

Logs a Warn level message.

Enums§

Level: 日志级别。

Log level.

Attribute Macros§

instrument: 函数仪表化属性。

Function instrumentation attribute.

自动追踪函数的进入和退出，并记录参数信息。

Automatically traces function entry and exit, and logs argument information.