1# FLAME
2#### A cool flamegraph library for rust
3
4Flamegraphs are a great way to view profiling information.
5At a glance, they give you information about how much time your
6program spends in critical sections of your code giving you some
7much-needed insight into where optimizations may be needed.
8
9Unlike tools like `perf` which have the OS interrupt your running
10program repeatadly and reports on every function in your callstack,
11FLAME lets you choose what you want to see in the graph by adding
12performance instrumentation to your own code.
13
14Simply use any of FLAMEs APIs to annotate the start and end of a
15block code that you want timing information from, and FLAME will
16organize these timings hierarchically.
17
18### [Docs](https://docs.rs/flame/)
19
20Here's an example of how to use some of FLAMEs APIs:
21
22```rust
23extern crate flame;
24
25use std::fs::File;
26
27fn main() {
28    // Manual `start` and `end`
29    flame::start("read file");
30    let x = read_a_file();
31    flame::end("read file");
32
33    // Time the execution of a closure.  (the result of the closure is returned)
34    let y = flame::span_of("database query", || query_database());
35
36    // Time the execution of a block by creating a guard.
37    let z = {
38        let _guard = flame::start_guard("cpu-heavy calculation");
39        cpu_heavy_operations_1();
40        // Notes can be used to annotate a particular instant in time.
41        flame::note("something interesting happened", None);
42        cpu_heavy_operations_2()
43    };
44
45    // Dump the report to disk
46    flame::dump_html(&mut File::create("flame-graph.html").unwrap()).unwrap();
47
48    // Or read and process the data yourself!
49    let spans = flame::spans();
50
51    println!("{} {} {}", x, y, z);
52}
53```
54
55And here's a screenshot of a flamegraph produced by `dump_html` (from a different project):
56
57![flamegraph](./resources/screenshot.png "Flamegraph example")
58
59[llogiq](https://github.com/llogiq) has created [flamer](https://github.com/llogiq/flamer),
60a compiler plugin that automatically inserts FLAME instrumentation into annotated functions
61allowing you to write code like
62
63```rust
64#[flame]
65fn this_function_is_profiled() {
66    ...
67}
68```
69
70So if you are using a nightly version of rust, check it out; flamer is probably the easiest way
71to use FLAME!
72