2f12e6e4f3
After seeing a recording of Emery's recent talk at Strange Loop I was super impressed with `coz` and immediately wanted to try it out with Rust code! I was curious to see if `coz` could help us out with profiling either Cargo, Rust's build system, or perhaps the compiler itself, `rustc`. In any case I ended up creating https://github.com/alexcrichton/coz-rs as a repository to house an implementation of `coz.h` for Rust so `coz` could be used to easily work with Rust executables. I toyed around a bit and Emery [mentioned] that this would be good support to have upstream once it's working, and I think it's working now! I haven't been able to get a ton of useful results myself yet, but I'm still figuring out the best way to ask `coz` questions and the best way to instrument programs myself. Nonetheless I think that the Rust support here is correct in the sense that it's a faithful translation of `coz.h`, and now it's just a problem with me learning how best to instrument programs. This commit adds a new `rust` directory with a crate (Rust parlance for "library") which provides macros that allow using `coz` instrumentation similar as you would in C, except in idiomatic Rust style. I've published the crate on Rust's package registry, crates.io, as [`coz`][crate], and I don't mind keeping it there or transferring it to y'all, whichever you'd prefer! I also don't mind being on the hook for reviewing any Rust-related changes, or if y'all need to jettison the Rust support in the future I don't mind that either and can give it a home! [mentioned]: https://github.com/alexcrichton/coz-rs/issues/2 [crate]: https://crates.io/crates/coz |
||
---|---|---|
.. | ||
examples | ||
src | ||
tests | ||
Cargo.toml | ||
README.md | ||
toy.png |
coz-rs
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");
}
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 asigaltstack
to run segfault handlers to print "you ran out of stack", but this alternate stack is too small to run theSIGPROF
handler thatcoz
installs. To handle this this crate provides acoz::thread_init()
function which will increase thesigaltstack
size that Rust installs by default to something large enough to runcoz
. If you see segfaults, or corrupt reports, you may wish to manually callcoz::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 usingcoz
. -
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!