spandoc

将函数中的文档注释转换为跟踪 spans 的属性宏。

详细信息

所有旨在转换为范围的文档注释 必须 以 SPANDOC: 开头

use spandoc::spandoc;
use tracing::info;

#[spandoc]
fn foo() {
    /// SPANDOC: this will be converted into a span
    info!("event 1");

    /// this will be ignored and produce a warning for an unused doc comment
    info!("event 2");
}

spandoc创建的范围被明确地限定在它们关联的表达式范围内。

use spandoc::spandoc;
use tracing::info;

#[spandoc]
fn main() {
    tracing_subscriber::fmt::init();
    let local = 4;

    /// SPANDOC: Emit a tracing info event {?local}
    info!("event 1");

    info!("event 2");
}

运行上述示例将产生以下输出

spandoc on  await-support [!+] is 📦 v0.1.3 via 🦀 v1.44.1
❯ cargo run --example scoped
    Finished dev [unoptimized + debuginfo] target(s) in 0.03s
     Running `target/debug/examples/scoped`
Jul 09 12:42:43.691  INFO main::comment{local=4 text=Emit a tracing info event}: scoped: event 1
Jul 09 12:42:43.691  INFO scoped: event 2

可以通过在文档注释中添加尾随块来将局部变量与生成的范围关联起来。范围中的字段语法与 tracing 中的语法相同。

use spandoc::spandoc;
use tracing::info;

#[spandoc]
fn foo() {
    let path = "fake.txt";
    /// SPANDOC: going to load config {?path}
    info!("event 1");

    /// this will be ignored and produce a warning for an unused doc comment
    info!("event 2");
}

当应用于包含 await 的表达式时，spandoc 将正确使用 instrument() 并在挂起和恢复未来时进入/退出范围。如果在注解表达式中存在多个 await 表达式，它将为每个表达式使用相同的范围。宏不会递归到 async 块中。

use std::future::Future;
use spandoc::spandoc;
use tracing::info;

fn make_liz() -> impl Future<Output = Result<(), ()>> {
    info!("this will be printed in the span from `clever_girl`");

    liz()
}

async fn liz() -> Result<(), ()> {
    info!("this will also be printed in the span from `clever_girl`");

    // return a result so we can call map outside of the scope of the future
    Ok(())
}

#[spandoc]
async fn clever_girl() {
    // This span will be entered before the await, exited correctly when the
    // future suspends, and instrument the future returned from `liz` with
    // `tracing-futures`
    /// clever_girl async span
    make_liz().await.map(|()| info!("this will also be printed in the span"));
}

许可证