Add a Rust implementation of `coz.h`
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
2019-09-23 19:07:51 +03:00
|
|
|
# coz-rs
|
|
|
|
|
|
|
|
Rust support for the [`coz` Causal Profiler](https://github.com/plasma-umass/coz)
|
|
|
|
|
2023-07-01 23:41:36 +03:00
|
|
|
[![Rust crate downloads](https://img.shields.io/crates/d/coz)](https://img.shields.io/crates/d/coz)[![Documentation](https://docs.rs/coz/badge.svg)](https://docs.rs/coz)
|
Add a Rust implementation of `coz.h`
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
2019-09-23 19:07:51 +03:00
|
|
|
|
|
|
|
## Usage
|
|
|
|
|
|
|
|
First, follow the instructions in [`coz`] to install the `coz` command.
|
|
|
|
|
|
|
|
[`coz`]: https://github.com/plasma-umass/coz/#installation
|
|
|
|
|
|
|
|
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`
|
|
|
|
|
|
|
|
```toml
|
|
|
|
[dependencies]
|
|
|
|
coz = "0.1"
|
|
|
|
```
|
|
|
|
|
2019-11-21 13:18:34 +03:00
|
|
|
Then you'll want to either add throughput or latency tracepoints. More
|
Add a Rust implementation of `coz.h`
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
2019-09-23 19:07:51 +03:00
|
|
|
information on this [can be found
|
|
|
|
upstream](https://github.com/plasma-umass/coz/#profiling-modes). If you have
|
2019-11-21 13:18:34 +03:00
|
|
|
something you'd wish would execute more often, you can add:
|
Add a Rust implementation of `coz.h`
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
2019-09-23 19:07:51 +03:00
|
|
|
|
|
|
|
```rust
|
|
|
|
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:
|
|
|
|
|
|
|
|
```rust
|
|
|
|
// Boy I wish this function executed more quickly...
|
|
|
|
fn foo() {
|
2020-06-10 06:55:56 +03:00
|
|
|
coz::scope!("foo");
|
Add a Rust implementation of `coz.h`
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
2019-09-23 19:07:51 +03:00
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2020-06-10 06:55:56 +03:00
|
|
|
Instead of `scope!` you may also use `coz::begin!("foo"); ... coz::end!("foo");`.
|
|
|
|
|
Add a Rust implementation of `coz.h`
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
2019-09-23 19:07:51 +03:00
|
|
|
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:
|
|
|
|
|
|
|
|
```toml
|
|
|
|
[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 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
|
|
|
|
|
2023-06-30 23:22:46 +03:00
|
|
|
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`.
|
Add a Rust implementation of `coz.h`
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
2019-09-23 19:07:51 +03:00
|
|
|
|
|
|
|
```
|
2023-06-30 23:22:46 +03:00
|
|
|
$ cargo build --release --examples
|
Add a Rust implementation of `coz.h`
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
2019-09-23 19:07:51 +03:00
|
|
|
$ coz run --- ./target/release/examples/toy
|
|
|
|
...
|
|
|
|
[profiler.cpp:75] Starting profiler thread
|
|
|
|
$
|
|
|
|
```
|
|
|
|
|
2023-06-30 23:22:46 +03:00
|
|
|
That should generate `profile.coz` in the current directory, which if you plot with `coz plot` should look something like this:
|
Add a Rust implementation of `coz.h`
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
2019-09-23 19:07:51 +03:00
|
|
|
|
|
|
|
![plot of `toy.rs`](toy.png)
|
|
|
|
|