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`
    /// SPANDOC: clever_girl async span
    make_liz().await.map(|()| info!("this will also be printed in the span"));
}

许可证