Add usage instructions

[fabianbergmark]

trafficstars

It's pretty unclear how to actually use this tool.

I've guessed this much:

cargo flamegraph --bin BINARY

press ctrl-c after a while, I see

[ perf record: Woken up 1096 times to write data ] [ perf record: Captured and wrote 275.761 MB perf.data (34147 samples) ]

now it just hangs, until I press ctrl-c again then I see

writing flamegraph to "flamegraph.svg"

It also seems that depending on how fast i issue the second ctrl-c, I get more or less output...

[RandomInsano]

That's largely how I use it on macOS and it's great. Linux I have yet to get working properly.

[djc]

If there is anything unclear about the usage instructions in the README, PRs are welcome. If you think there are bugs, then maybe make a more specific issue about the bug you think you're seeing.

[fabianbergmark]

Provided that I'm not sure that I've ever been able to run this tool correctly, I'm not very inclined to write a PR for it.

[djc]

That is totally understandable. (Although #127 suggests it might fix the issues you're having.)

[RandomInsano]

I gave it a shot, but I'm in a different boat. No dice on my side. I'm still just left with perf.data

$ cargo flamegraph --root --no-inline --bin game -o flamegraph.svg
    Finished release [optimized] target(s) in 0.21s

WARNING: building without debuginfo. Enable symbol information by adding the following lines to Cargo.toml:

[profile.release]
debug = true

Error: "Exiting"
[ perf record: Woken up 36 times to write data ]
[ perf record: Captured and wrote 9.889 MB perf.data (1217 samples) ]
failed to sample program
$ ls -l
total 10152
-rw-rw-r-- 1 me me      786 Feb 20 21:01 Cargo.toml
drwxrwxr-x 2 me me     4096 Feb 14 23:13 examples
-rw------- 1 root        root        10377460 Mar  2 19:37 perf.data
drwxrwxr-x 6 me me     4096 Feb 14 23:13 Resources
drwxrwxr-x 7 me me     4096 Feb 14 23:13 src

I don't think this is a documentation issue because I've been using cargo-flamegraph for at least nine months on Mac with no trouble.

[djc]

If you can run with -v, it should show the exact perf command it is running. Maybe try to debug that separately?

[Aranjedeath]

How do I run this with a binary that requires CLI arguments to operate? I cannot figure it out from the documentation.

I am trying to test a piece of rust software that requires -c "/path/to/config/file.toml" and I cannot make heads or tails of how to pass that option. I can only see --bin.

[djc]

You can probably pass those arguments after --, as in many Unix tools.

[j2kun]

I think what's missing is a clear explanation of how to tell the tool to stop profiling a job and write some output.

I tried attaching to an existing process, and wasn't sure if SIGINT would kill it or tell it to stop collecting and start analyzing. SIGINT makes sense, it could just be made explicit for newbies like me :)

Perhaps a flag to specify a profiling deadline would also help.

[djc]

I'm only passively maintaining this crate for now. If you'd like to add documentation or add some additional UX affordances, please submit a PR.