.. | ||
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 add throughput or latency tracepoints. More information on this can be found upstream. If you have something you'd wish would 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::scope!("foo");
}
Instead of scope!
you may also use 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:
-
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 rust/examples/toy.rs
in this repository, and we can execute it with coz
:
NOTE: If Rust is not yet installed, first run sudo apt install curl
and then curl --proto '=https' --tlsv1.3 https://sh.rustup.rs -sSf | sh
.
$ cargo build --release --examples
$ 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 with coz plot
should look something like this: