README.md
1 # Introduction
2
3 The `perf_to_profile` binary can be used to turn a perf.data file, which is
4 generated by the linux profiler, perf, into a profile.proto file which can be
5 visualized using the tool pprof.
6
7 For details on pprof, see https://github.com/google/pprof
8
9 **THIS IS NOT AN OFFICIAL GOOGLE PRODUCT**
10
11
12 # Prerequisites:
13 - Protocol buffers: http://github.com/google/protobuf
14 - Google Test: http://github.com/google/googletest
15
16 # Compilation:
17 To install all dependences and build the binary, run the following commands.
18 These were tested on Debian GNU/Linux 8 (jessie):
19 ```
20 sudo apt-get -y install autoconf automake g++ git libelf-dev libssl-dev libtool make pkg-config
21 git clone --recursive https://github.com/google/perf_data_converter.git
22 cd perf_data_converter/src
23 make perf_to_profile
24 ```
25
26 If you already have protocol buffers and googletest installed on your system,
27 you can compile using your local packages with the following commands:
28 ```
29 sudo apt-get -y install autoconf automake g++ git libelf-dev libssl-dev libtool make pkg-config
30 git clone https://github.com/google/perf_data_converter.git
31 cd perf_data_converter/src
32 make perf_to_profile
33 ```
34
35 Place the `perf_to_profile` binary in a place accessible from your path (eg `/usr/local/bin`).
36
37 # Running tests:
38 There are a small number of tests that verify the basic functionality.
39 To run these, after successful compilation, run:
40 ```
41 make check clean
42 make check clean -C quipper/ -f Makefile.external
43 ```
44
45 # Usage:
46 Profile a command using perf, for example:
47 ```
48 perf record /bin/ls
49 ```
50
51 The example command will generate a profile named perf.data, you
52 should convert this into a profile.proto then visualize it using
53 pprof:
54
55 ```
56 perf_to_profile perf.data profile.pb
57 pprof -web profile.pb
58 ```
59
60 Recent versions of pprof will automatically invoke `perf_to_profile`:
61 ```
62 pprof -web perf.data
63 ```
64
65 # Contribution:
66 We appreciate your help!
67
68 Note that perf data converter and quipper projects do not use GitHub pull
69 requests, and that we use the issue tracker for bug reports.
70