coz-rs

Note: the official source of this crate now lives upstream in the main
coz repository, it's recommended to
use that instead of this repository, and file issues/changes there instead of
here.

Rust support for the coz Causal Profiler

Usage

First, follow the instructions in coz to install the coz command.

Next, coz is a profiler that, for the best results, typically requires
source-level modifications of your code. To do this first add this to your
Cargo.toml

[dependencies]
coz = "0.1"

Then you'll want to either at throughput or latency tracepoints. More
information on this can be found
upstream. If you have
something you'd wish whould execute more often, you can add:

fn main() {
    loop {
        // ...

        // For example you wish this `loop` executed more iterations
        coz::progress!(); // equivalent of `COZ_PROGRESS`
    }
}

Note that coz::progress!("name") is the equivalent of COZ_PROGRESS_NAMED as
well.

If you'd like to profile the latency of an operation you can instead use:

// Boy I wish this function executed more quickly...
fn foo() {
    coz::begin!("foo");

    // ...

    coz::end!("foo");
}

If you have a lexical scope, you can also use the coz::scope!(name) macro
to place begin and end markers for you:

// Boy I wish this function executed more quickly...
fn scope_me() {
    coz::scope!("foo");

    // ...
}

This has the added benefit that it will place the end marker even on
early exit, such as return, ? or panic!.

After you've instrumented your code, you need to also ensure that you're
compiling with DWARF debug information. To do this you'll want to configure
Cargo.toml again:

[profile.release]
debug = 1

Next up you'll build your application with cargo build --release, and then
finally you can run it with coz run --- ./target/release/$your_binary.

Caveats

Known caveats so far to generate a report that collects information are:

Rust programs by default segfault when run with coz with an issue related to
plasma-umass/coz#110. Rust
programs set up a sigaltstack to run segfault handlers to print "you ran out
of stack", but this alternate stack is too small to run the SIGPROF handler
that coz installs. To handle this this crate provides a coz::thread_init()
function which will increase the sigaltstack size that Rust installs by
default to something large enough to run coz. If you see segfaults, or
corrupt reports, you may wish to manually call coz::thread_init() instead of
waiting for this crate to automatically call it for you.
Debug information looks to be critical to get a report from coz. Make sure
that your program is compiled with at least line-table information (debug = 1) to ensure you get the best experience using coz.
Currently coz only works on Linux, and while this crate should compile on
all platforms it only actually does something on Linux.

Examples

You can find an example toy program at examples/toy.rs in this repository, and
we can execute it with coz:

$ cargo build --release
$ coz run --- ./target/release/examples/toy
...
[profiler.cpp:75] Starting profiler thread
$

That should generate profile.coz in the current directory, which if you plot
that should look something like this:

Note that I'm still learning myself the best sorts of applications to run on as
well as the best sorts of questions to ask coz and where to put
latency/throughput points. If you've got ideas or good examples, please feel
free to add them here!

License

This project is licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or
http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or
http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in this project by you, as defined in the Apache-2.0 license,
shall be dual licensed as above, without any additional terms or conditions.

README