1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177
//! Attribute macro that transforms doc comments in functions into tracing //! [`spans`](https://docs.rs/tracing/0.1.16/tracing/span/index.html). //! //! Spandoc provides a function level attribute macro that converts doc ! //! comments _within_ a function into tracing spans. These spans are entered //! before the annotated expression and exited immediately after. Spandoc is also //! async aware, so expressions that contain `.await`s will correctly instrument //! the future, exit before yielding, and enter the span again when the future //! resumes. //! //! # Details //! //! All doc comments intended to be transformed into spans **must** begin with `SPANDOC: `: //! //! ```rust //! 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"); //! } //! ``` //! //! The spans that are created by spandoc are explicitly scoped to the expression //! they're associated with. //! //! ```rust //! 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"); //! } //! ``` //! //! Running the above example will produce the following output //! //! <pre><font color="#06989A"><b>spandoc</b></font> on <font color="#75507B"><b> await-support</b></font> <font color="#CC0000"><b>[!+] </b></font>is <font color="#FF8700"><b>📦 v0.1.3</b></font> via <font color="#CC0000"><b>🦀 v1.44.1</b></font> //! <font color="#4E9A06"><b>❯</b></font> cargo run --example scoped //! <font color="#4E9A06"><b> Finished</b></font> dev [unoptimized + debuginfo] target(s) in 0.03s //! <font color="#4E9A06"><b> Running</b></font> `target/debug/examples/scoped` //! <font color="#A1A1A1">Jul 09 12:42:43.691 </font><font color="#4E9A06"> INFO</font> <b>main::comment{</b>local=4 text=Emit a tracing info event<b>}</b>: scoped: event 1 //! <font color="#A1A1A1">Jul 09 12:42:43.691 </font><font color="#4E9A06"> INFO</font> scoped: event 2</pre> //! //! Local variables can be associated with the generated spans by adding a //! trailing block to the doc comment. The syntax for fields in the span is the //! [same as in `tracing`](https://docs.rs/tracing/*/tracing/index.html#using-the-macros). //! //! ```rust //! 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"); //! } //! ``` //! //! When applied to expressions that contain `await`s spandoc will correctly //! use `instrument()` and exit/enter the span when suspending and resuming the //! future. If there are multiple await expressions inside of the annotated //! expression it will instrument each expression with the same span. The macro //! will not recurse into `async` blocks. //! //! //! ```rust //! 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")); //! } //! ``` #![doc(html_root_url = "https://docs.rs/spandoc/0.2.0")] #![cfg_attr(docsrs, feature(doc_cfg))] #![warn( missing_docs, missing_doc_code_examples, rust_2018_idioms, unreachable_pub, bad_style, const_err, dead_code, improper_ctypes, non_shorthand_field_patterns, no_mangle_generic_items, overflowing_literals, path_statements, patterns_in_fns_without_body, private_in_public, unconditional_recursion, unused, unused_allocation, unused_comparisons, unused_parens, while_true )] #![allow(clippy::needless_doctest_main)] use std::cell::Cell; use tracing_futures::Instrument; /// Attribute macro that transforms doc comments in functions into tracing [`spans`](https://docs.rs/tracing/0.1.16/tracing/span/index.html). pub use spandoc_attribute::spandoc; #[doc(hidden)] pub struct FancyGuard<'a> { span: &'a tracing::Span, entered: Cell<bool>, } impl<'a> FancyGuard<'a> { #[doc(hidden)] pub fn new(span: &'a tracing::Span) -> FancyGuard<'a> { span.with_subscriber(|(id, sub)| sub.enter(id)); Self { span, entered: Cell::new(true), } } #[doc(hidden)] pub async fn wrap<F>(&self, fut: F) -> F::Output where F: std::future::Future, { self.span.with_subscriber(|(id, sub)| sub.exit(id)); self.entered.set(false); let output = fut.instrument(self.span.clone()).await; self.span.with_subscriber(|(id, sub)| sub.enter(id)); self.entered.set(true); output } } impl Drop for FancyGuard<'_> { fn drop(&mut self) { if self.entered.get() { self.span.with_subscriber(|(id, sub)| sub.exit(id)); } } }