1OPERF(1) General Commands Manual OPERF(1)
2
3
4
6 operf - Performance profiler tool for Linux
7
8
10 operf [ options ] [ --system-wide | --pid <pid> | [ command [ args ] ]
11 ]
12
13
15 Operf is an OProfile tool that can be used in place of opcontrol for
16 profiling. Operf uses the Linux Performance Events Subsystem, and
17 hence, does not require the use of the opcontrol daemon -- in fact,
18 operf and opcontrol usage are mutually exclusive.
19
20 By default, operf uses <current_dir>/oprofile_data as the session-dir
21 and stores profiling data there. You can change this by way of the
22 --session-dir option.
23
24 The usual post-profiling analysis tools such as opreport(1) and opanno‐
25 tate(1) can be used to generate profile reports. The post-processing
26 analysis tools will search for samples in <current_dir>/oprofile_data
27 first. If that directory does not exist, the post-processing tools use
28 the standard session-dir of /var/lib/oprofile.
29
30 Statistics, such as total samples received and lost samples, are writ‐
31 ten to the operf.log file that can be found in the <session_dir>/sam‐
32 ples directory.
33
34
36 command[args]
37 The command or application to be profiled. args are the input
38 arguments that the command or application requires. One (and
39 only one) of either command , --pid or --system-wide is
40 required.
41
42 --pid / -p PID
43 This option enables operf to profile a running application. PID
44 should be the process ID of the process you wish to profile.
45 When finished profiling (e.g., when the profiled process ends),
46 press Ctrl-c to stop operf. If you run operf --pid as a back‐
47 ground job (i.e., with the &), you must stop it in a controlled
48 manner in order for it to process the profile data it has col‐
49 lected. Use kill -SIGINT <operf-PID> for this purpose.
50
51 --system-wide / -s
52 This option is for performing a system-wide profile. You must
53 have root authority to run operf in this mode. When finished
54 profiling, Ctrl-c to stop operf. If you run operf --system-wide
55 as a background job (i.e., with the &), you must stop it in a
56 controlled manner in order for it to process the profile data it
57 has collected. Use kill -SIGINT <operf-PID> for this purpose.
58 It is recommended that when running operf with this option, the
59 user's current working directory should be /root or a subdirec‐
60 tory of /root to avoid storing sample data files in locations
61 accessible by regular users.
62
63 --vmlinux / k vmlinux_path
64 A vmlinux file that matches the running kernel that has symbol
65 and/or debuginfo. Kernel samples will be attributed to this
66 binary, allowing post-processing tools (like opreport) to
67 attribute samples to the appropriate kernel symbols.
68
69 --events / -e event1[,event2[,...]]
70 This option is for passing a comma-separated list of event spec‐
71 ifications for profiling. Each event spec is of the form:
72 name:count[:unitmask[:kernel[:user]]]
73 You can specify unit mask values using either a numerical value
74 (hex values must begin with "0x") or a symbolic name (if the
75 name=<um_name> field is shown in the ophelp output). For some
76 named unit masks, the hex value is not unique; thus, OProfile
77 tools enforce specifying such unit masks value by name.
78
79 Event names for some IBM PowerPC systems include a _GRP<n>
80 (group number) suffix. You can pass either the full event name
81 or the base event name (i.e., without the suffix) to operf. If
82 the base event name is passed, operf will automatically choose
83 an appropriate group number suffix for the event; thus, OProfile
84 post-processing tools will always show real event names that
85 include the group number suffix.
86
87 When no event specification is given, the default event for the
88 running processor type will be used for profiling. Use ophelp
89 to list the available events for your processor type.
90
91 --callgraph / -g
92 This option enables the callgraph to be saved during profiling.
93 NOTE: The full callchain is recorded, so there is no depth
94 limit.
95
96 --separate-thread / -t
97 This option categorizes samples by thread group ID (tgid) and
98 thread ID (tid). The '--separate-thread' option is useful for
99 seeing per-thread samples in multi-threaded applications. When
100 used in conjunction with the '--system-wide' option, the '--sep‐
101 arate-thread' option is also useful for seeing per-process
102 (i.e., per-thread group) samples for the case where multiple
103 processes are executing the same program during a profiling run.
104
105 --separate-cpu / -c
106 This option categorizes samples by cpu.
107
108 --session-dir / -d path
109 This option specifies the session path to hold the sample data.
110 If not specified, the data is saved in the oprofile_data direc‐
111 tory on the current path.
112
113 --lazy-conversion / -l
114 Use this option to reduce the overhead of operf during profil‐
115 ing. Normally, profile data received from the kernel is con‐
116 verted to OProfile format during profiling time. This is typi‐
117 cally not an issue when profiling a single application. But when
118 using the --system-wide option, this on-the-fly conversion
119 process can cause noticeable overhead, particularly on busy
120 multi-processor systems. The --lazy-conversion option directs
121 operf to wait until profiling is completed to do the conversion
122 of profile data.
123
124 --append / -a
125 By default, operf moves old profile data from <session_dir>/sam‐
126 ples/current to <session_dir>/samples/previous. If a 'previous'
127 profile already existed, it will be replaced. If the --append
128 option is passed, old profile data is left in place and new pro‐
129 file data will be added to it, and the 'previous' profile (if
130 one existed) will remain untouched. To access the 'previous'
131 profile, simply add a session specification to the normal invo‐
132 cation of oprofile post-processing tools. For example:
133 opreport session:previous
134
135 --verbose / -V level
136 A comma-separated list of debugging control values, used to
137 increase the verbosity of the output. Valid values are: debug,
138 record, convert, misc, sfile, arcs, or the special value, 'all'.
139
140 --version / -v
141 Show operf version.
142
143 --help / -h
144 Display brief usage message.
145
146 --usage / -u
147 Display brief usage message.
148
149
151 $ operf make
152
153
155 This man page is current for oprofile-0.9.9.
156
157
159 opreport(1), opannotate(1).
160
161
162
163oprofile 0.9.9 Tue 21 March 2017 OPERF(1)