gsingh93 / trace

A Rust procedural macro for tracing function execution

trace

A procedural macro for tracing the execution of functions.

Adding #[trace] to the top of functions, mods, or impls will insert println! statements at the beginning and the end of the affected functions, notifying you of when that function was entered and exited and printing the argument and return values. Useful for quickly debugging whether functions that are supposed to be called are actually called without manually inserting print statements.

See the examples directory and the documentation for more detail on how to use and configure this library.

Installation

Add it as a dependency in your Cargo.toml file:

[dependencies]
trace = "*"

Example

use trace::trace;

trace::init_depth_var!();

fn main() {
    foo(1, 2);
}

#[trace]
fn foo(a: i32, b: i32) {
    println!("I'm in foo!");
    bar((a, b));
}

#[trace(prefix_enter="[ENTER]", prefix_exit="[EXIT]")]
fn bar((a, b): (i32, i32)) -> i32 {
    println!("I'm in bar!");
    if a == 1 {
        2
    } else {
        b
    }
}

Output:

[+] Entering foo(a = 1, b = 2)
I'm in foo!
 [ENTER] Entering bar(a = 1, b = 2)
I'm in bar!
 [EXIT] Exiting bar = 2
[-] Exiting foo = ()

trace's Issues

Thread safety

using a global static mut depth isn't thread safe. It's possible to just replace the global with a thread-local like thread_local!(static STATIC_DEPTH: RefCell<usize> = RefCell::new(0)) but it still has to be entered by the user and it's long.

Disable return value

There are ways to disable parameters, but how can I disable the return value?
I'm trying to apply this to a function with a return type that doesn't implement Debug.

Considering trace using trace!() ?

In this way, it can be easily turned on and turned off by setting different log levels.

Still alive?

Is this crate still alive?
I was trying to use it today but got an error:

Compiling trace v0.1.4
error[E0557]: feature has been removed
--> /home/user/.cargo/registry/src/github.com-1ecc6299db9ec823/trace-0.1.4/src/lib.rs:1:12
|
1 | #![feature(quote, plugin_registrar, rustc_private, slice_concat_ext)]
| ^^^^^ feature has been removed

error[E0463]: can't find crate for syntax
--> /home/user/.cargo/registry/src/github.com-1ecc6299db9ec823/trace-0.1.4/src/lib.rs:3:1

|
3 | extern crate syntax;
| ^^^^^^^^^^^^^^^^^^^^ can't find crate

error: aborting due to 2 previous errors

Would it be possible to fix this issue?

no_std support

Maybe a bit outside of how this crate was intended to be used but I think it would be nice if it supported no_std.

thread_local is not available in no_std. One way to deal with that would be to make indentation optional.

println! and Format are also not available in no_std. A popular way of dealing with this is to use defmt, which effectively reimplements println! and Format in a way that is appropriate for no_std. The {{:depth$}} syntax is not supported by defmt. The inclusion of this format specifier would need to be optional.

Here is WIP https://github.com/tommy-gilligan/trace
I've hardcoded no_std enabled in WIP but I consider that a nonstarter for opening a PR here. The next thing to do is to incorporate some kind of condition for toggling no_std support. I think that making thread_local and the unsupported format specifier optional across the crate could be accomplished by a feature flag.

Love to know your thoughts

Does not work with latest nightly

Some of the errors are:

error[E0615]: attempted to take value of method `name` on type `&syntax::ast::MetaItem`criterion                                                                                                                 
   --> /Users/breezewish/.cargo/registry/src/github.com-1ecc6299db9ec823/trace-0.1.4/src/lib.rs:135:31
    |
135 |                         if mi.name == "prefix_enter" {
    |                               ^^^^
    |
    = help: maybe a `()` to call it is missing?

error[E0615]: attempted to take value of method `name` on type `&syntax::ast::MetaItem`
   --> /Users/breezewish/.cargo/registry/src/github.com-1ecc6299db9ec823/trace-0.1.4/src/lib.rs:139:38
    |
139 |                         } else if mi.name == "prefix_exit" {
    |                                      ^^^^
    |
    = help: maybe a `()` to call it is missing?

error[E0023]: this pattern has 6 fields, but the corresponding tuple variant has 4 fields
   --> /Users/breezewish/.cargo/registry/src/github.com-1ecc6299db9ec823/trace-0.1.4/src/lib.rs:314:12
    |
314 |     if let Fn(ref decl, style, constness, abi, ref generics, ref block) = item.node {
    |            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ expected 4 fields, found 6

error[E0061]: this function takes 4 parameters but 6 parameters were supplied
   --> /Users/breezewish/.cargo/registry/src/github.com-1ecc6299db9ec823/trace-0.1.4/src/lib.rs:317:9
    |
317 | /         Fn(decl.clone(),
318 | |            style,
319 | |            constness,
320 | |            abi,
321 | |            generics.clone(),
322 | |            new_block)
    | |_____________________^ expected 4 parameters

Can someone push master to crates.io please?

Can someone push master to crates.io please? version on master no longer compatible with latest rustc but head is. Took a little head scratching to figure out that was the issue.

on async function get error

getting this error on async functions

#[trace(logging)]
pub async fn foo(str: &str) {
}

#[trace(logging)]
   |     ----------------- this is not `async`

Can it trace every line inside the function?

Or even inside entire module/crate.

Fails to build on 2016-07-20

When trying to build trace with the nightly compiler 2016-07-20, I get the following error

   Compiling trace v0.1.3
/Users/nm46057/.cargo/registry/src/github.com-1ecc6299db9ec823/trace-0.1.3/src/lib.rs:12:65: 12:74 error: unresolved import `syntax::ast::TokenTree`. There is no `TokenTree` in `syntax::ast` [E0432]
/Users/nm46057/.cargo/registry/src/github.com-1ecc6299db9ec823/trace-0.1.3/src/lib.rs:12 use syntax::ast::{self, Item, ItemKind, MetaItem, Block, Ident, TokenTree, FnDecl, ImplItem,
                                                                                                                                                         ^~~~~~~~~
/Users/nm46057/.cargo/registry/src/github.com-1ecc6299db9ec823/trace-0.1.3/src/lib.rs:12:65: 12:74 help: run `rustc --explain E0432` to see a detailed explanation
/Users/nm46057/.cargo/registry/src/github.com-1ecc6299db9ec823/trace-0.1.3/src/lib.rs:316:58: 316:70 error: unresolved name `token::Plain` [E0425]
/Users/nm46057/.cargo/registry/src/github.com-1ecc6299db9ec823/trace-0.1.3/src/lib.rs:316         .map(|ident| vec![token::Ident((*ident).clone(), token::Plain)])
                                                                                                                                                   ^~~~~~~~~~~~
/Users/nm46057/.cargo/registry/src/github.com-1ecc6299db9ec823/trace-0.1.3/src/lib.rs:316:22: 316:72 note: in this expansion of vec! (defined in <std macros>)
/Users/nm46057/.cargo/registry/src/github.com-1ecc6299db9ec823/trace-0.1.3/src/lib.rs:316:58: 316:70 help: run `rustc --explain E0425` to see a detailed explanation
/Users/nm46057/.cargo/registry/src/github.com-1ecc6299db9ec823/trace-0.1.3/src/lib.rs:256:31: 256:60 error: this pattern has 2 fields, but the corresponding variant has 3 fields [E0023]
/Users/nm46057/.cargo/registry/src/github.com-1ecc6299db9ec823/trace-0.1.3/src/lib.rs:256             &PatKind::Wild | &PatKind::TupleStruct(_, None) | &PatKind::Lit(_)
                                                                                                                        ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/Users/nm46057/.cargo/registry/src/github.com-1ecc6299db9ec823/trace-0.1.3/src/lib.rs:256:31: 256:60 help: run `rustc --explain E0023` to see a detailed explanation
/Users/nm46057/.cargo/registry/src/github.com-1ecc6299db9ec823/trace-0.1.3/src/lib.rs:257:63: 257:81 error: no associated item named `QPath` found for type `syntax::ast::PatKind` in the current scope 
/Users/nm46057/.cargo/registry/src/github.com-1ecc6299db9ec823/trace-0.1.3/src/lib.rs:257                 | &PatKind::Range(..) | &PatKind::Path(..) | &PatKind::QPath(..) => (),
                                                                                                                                                        ^~~~~~~~~~~~~~~~~~
/Users/nm46057/.cargo/registry/src/github.com-1ecc6299db9ec823/trace-0.1.3/src/lib.rs:263:14: 263:50 error: this pattern has 2 fields, but the corresponding variant has 3 fields [E0023]
/Users/nm46057/.cargo/registry/src/github.com-1ecc6299db9ec823/trace-0.1.3/src/lib.rs:263             &PatKind::TupleStruct(_, Some(ref v)) | &PatKind::Tup(ref v) => {
                                                                                                       ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/Users/nm46057/.cargo/registry/src/github.com-1ecc6299db9ec823/trace-0.1.3/src/lib.rs:263:14: 263:50 help: run `rustc --explain E0023` to see a detailed explanation
/Users/nm46057/.cargo/registry/src/github.com-1ecc6299db9ec823/trace-0.1.3/src/lib.rs:263:54: 263:73 error: no associated item named `Tup` found for type `syntax::ast::PatKind` in the current scope 
/Users/nm46057/.cargo/registry/src/github.com-1ecc6299db9ec823/trace-0.1.3/src/lib.rs:263             &PatKind::TupleStruct(_, Some(ref v)) | &PatKind::Tup(ref v) => {
                                                                                                                                               ^~~~~~~~~~~~~~~~~~~
/Users/nm46057/.cargo/registry/src/github.com-1ecc6299db9ec823/trace-0.1.3/src/lib.rs:316:27: 316:71 error: this function takes 1 parameter but 2 parameters were supplied [E0061]
/Users/nm46057/.cargo/registry/src/github.com-1ecc6299db9ec823/trace-0.1.3/src/lib.rs:316         .map(|ident| vec![token::Ident((*ident).clone(), token::Plain)])
                                                                                                                    ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/Users/nm46057/.cargo/registry/src/github.com-1ecc6299db9ec823/trace-0.1.3/src/lib.rs:316:22: 316:72 note: in this expansion of vec! (defined in <std macros>)
/Users/nm46057/.cargo/registry/src/github.com-1ecc6299db9ec823/trace-0.1.3/src/lib.rs:316:27: 316:71 help: run `rustc --explain E0061` to see a detailed explanation
/Users/nm46057/.cargo/registry/src/github.com-1ecc6299db9ec823/trace-0.1.3/src/lib.rs:316:27: 316:71 note: the following parameter type was expected: syntax::ast::Ident 
error: aborting due to 5 previous errors 
error: Could not compile `trace`.

To learn more, run the command again with --verbose.

Convert examples to tests

It's annoying testing changes by manually ensuring the examples have the correct output. We should convert them to tests. I'm wondering if we can use something like https://github.com/Stebalien/gag-rs to capture stdout to do this with the least amount of work.

#[trace] on public functions makes them private

#[trace]
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

after macro expansions will behave like

fn add(a: i32, b: i32) -> i32 {
    println!("[+] Entering add(a: {:?}, b: {:?})", a, b);
    let result = a + b;
    println!("[+] Exiting add = {:?}", result);
    result
}

and will not be visible outside of the module.