Commit | Line | Data |
---|---|---|
e33e0a43 | 1 | perf-record(1) |
c1c2365a | 2 | ============== |
e33e0a43 IM |
3 | |
4 | NAME | |
5 | ---- | |
23ac9cbe | 6 | perf-record - Run a command and record its profile into perf.data |
e33e0a43 IM |
7 | |
8 | SYNOPSIS | |
9 | -------- | |
10 | [verse] | |
11 | 'perf record' [-e <EVENT> | --event=EVENT] [-l] [-a] <command> | |
9e096753 | 12 | 'perf record' [-e <EVENT> | --event=EVENT] [-l] [-a] -- <command> [<options>] |
e33e0a43 IM |
13 | |
14 | DESCRIPTION | |
15 | ----------- | |
16 | This command runs a command and gathers a performance counter profile | |
23ac9cbe | 17 | from it, into perf.data - without displaying anything. |
e33e0a43 IM |
18 | |
19 | This file can then be inspected later on, using 'perf report'. | |
20 | ||
21 | ||
22 | OPTIONS | |
23 | ------- | |
24 | <command>...:: | |
25 | Any command you can specify in a shell. | |
26 | ||
27 | -e:: | |
28 | --event=:: | |
1b290d67 | 29 | Select the PMU event. Selection can be: |
e33e0a43 | 30 | |
1b290d67 FW |
31 | - a symbolic event name (use 'perf list' to list all events) |
32 | ||
33 | - a raw PMU event (eventsel+umask) in the form of rNNN where NNN is a | |
34 | hexadecimal event descriptor. | |
35 | ||
36 | - a hardware breakpoint event in the form of '\mem:addr[:access]' | |
37 | where addr is the address in memory you want to break in. | |
38 | Access is the memory access type (read, write, execute) it can | |
39 | be passed as follows: '\mem:addr[:[r][w][x]]'. | |
40 | If you want to profile read-write accesses in 0x1000, just set | |
41 | 'mem:0x1000:rw'. | |
08dbd7e3 SB |
42 | |
43 | --filter=<filter>:: | |
44 | Event filter. | |
45 | ||
e33e0a43 | 46 | -a:: |
08dbd7e3 SB |
47 | --all-cpus:: |
48 | System-wide collection from all CPUs. | |
e33e0a43 IM |
49 | |
50 | -l:: | |
386c0b70 ACM |
51 | Scale counter values. |
52 | ||
53 | -p:: | |
54 | --pid=:: | |
b52956c9 | 55 | Record events on existing process ID (comma separated list). |
08dbd7e3 SB |
56 | |
57 | -t:: | |
58 | --tid=:: | |
b52956c9 | 59 | Record events on existing thread ID (comma separated list). |
386c0b70 | 60 | |
0d37aa34 ACM |
61 | -u:: |
62 | --uid=:: | |
63 | Record events in threads owned by uid. Name or number. | |
64 | ||
386c0b70 ACM |
65 | -r:: |
66 | --realtime=:: | |
67 | Collect data with this RT SCHED_FIFO priority. | |
acac03fa KS |
68 | -D:: |
69 | --no-delay:: | |
70 | Collect data without buffering. | |
386c0b70 ACM |
71 | -A:: |
72 | --append:: | |
73 | Append to the output file to do incremental profiling. | |
74 | ||
75 | -f:: | |
76 | --force:: | |
7865e817 | 77 | Overwrite existing data file. (deprecated) |
386c0b70 ACM |
78 | |
79 | -c:: | |
80 | --count=:: | |
81 | Event period to sample. | |
82 | ||
83 | -o:: | |
84 | --output=:: | |
85 | Output file name. | |
86 | ||
87 | -i:: | |
2e6cdf99 SE |
88 | --no-inherit:: |
89 | Child tasks do not inherit counters. | |
386c0b70 ACM |
90 | -F:: |
91 | --freq=:: | |
92 | Profile at this frequency. | |
93 | ||
94 | -m:: | |
95 | --mmap-pages=:: | |
41d0d933 | 96 | Number of mmap data pages. Must be a power of two. |
386c0b70 ACM |
97 | |
98 | -g:: | |
99 | --call-graph:: | |
100 | Do call-graph (stack chain/backtrace) recording. | |
101 | ||
b44308f5 ACM |
102 | -q:: |
103 | --quiet:: | |
104 | Don't print any message, useful for scripting. | |
105 | ||
386c0b70 ACM |
106 | -v:: |
107 | --verbose:: | |
108 | Be more verbose (show counter open errors, etc). | |
109 | ||
110 | -s:: | |
111 | --stat:: | |
112 | Per thread counts. | |
113 | ||
114 | -d:: | |
115 | --data:: | |
116 | Sample addresses. | |
117 | ||
9c90a61c ACM |
118 | -T:: |
119 | --timestamp:: | |
120 | Sample timestamps. Use it with 'perf report -D' to see the timestamps, | |
121 | for instance. | |
122 | ||
386c0b70 ACM |
123 | -n:: |
124 | --no-samples:: | |
125 | Don't sample. | |
e33e0a43 | 126 | |
ec7ba4ea FW |
127 | -R:: |
128 | --raw-samples:: | |
bdef3b02 | 129 | Collect raw sample records from all opened counters (default for tracepoint counters). |
ec7ba4ea | 130 | |
c45c6ea2 SE |
131 | -C:: |
132 | --cpu:: | |
08dbd7e3 SB |
133 | Collect samples only on the list of CPUs provided. Multiple CPUs can be provided as a |
134 | comma-separated list with no space: 0,1. Ranges of CPUs are specified with -: 0-2. | |
c45c6ea2 SE |
135 | In per-thread mode with inheritance mode on (default), samples are captured only when |
136 | the thread executes on the designated CPUs. Default is to monitor all CPUs. | |
137 | ||
a1ac1d3c SE |
138 | -N:: |
139 | --no-buildid-cache:: | |
140 | Do not update the builid cache. This saves some overhead in situations | |
141 | where the information in the perf.data file (which includes buildids) | |
142 | is sufficient. | |
143 | ||
023695d9 SE |
144 | -G name,...:: |
145 | --cgroup name,...:: | |
146 | monitor only in the container (cgroup) called "name". This option is available only | |
147 | in per-cpu mode. The cgroup filesystem must be mounted. All threads belonging to | |
148 | container "name" are monitored when they run on the monitored CPUs. Multiple cgroups | |
149 | can be provided. Each cgroup is applied to the corresponding event, i.e., first cgroup | |
150 | to first event, second cgroup to second event and so on. It is possible to provide | |
151 | an empty cgroup (monitor all the time) using, e.g., -G foo,,bar. Cgroups must have | |
152 | corresponding events, i.e., they always refer to events defined earlier on the command | |
153 | line. | |
154 | ||
bdfebd84 | 155 | -b:: |
a5aabdac SE |
156 | --branch-any:: |
157 | Enable taken branch stack sampling. Any type of taken branch may be sampled. | |
158 | This is a shortcut for --branch-filter any. See --branch-filter for more infos. | |
159 | ||
160 | -j:: | |
161 | --branch-filter:: | |
bdfebd84 RAV |
162 | Enable taken branch stack sampling. Each sample captures a series of consecutive |
163 | taken branches. The number of branches captured with each sample depends on the | |
164 | underlying hardware, the type of branches of interest, and the executed code. | |
165 | It is possible to select the types of branches captured by enabling filters. The | |
166 | following filters are defined: | |
167 | ||
a5aabdac | 168 | - any: any type of branches |
bdfebd84 RAV |
169 | - any_call: any function call or system call |
170 | - any_ret: any function return or system call return | |
2e49a948 | 171 | - ind_call: any indirect branch |
bdfebd84 RAV |
172 | - u: only when the branch target is at the user level |
173 | - k: only when the branch target is in the kernel | |
174 | - hv: only when the target is at the hypervisor level | |
175 | ||
176 | + | |
a5aabdac | 177 | The option requires at least one branch type among any, any_call, any_ret, ind_call. |
9c768207 | 178 | The privilege levels may be omitted, in which case, the privilege levels of the associated |
a5aabdac SE |
179 | event are applied to the branch filter. Both kernel (k) and hypervisor (hv) privilege |
180 | levels are subject to permissions. When sampling on multiple events, branch stack sampling | |
181 | is enabled for all the sampling events. The sampled branch type is the same for all events. | |
182 | The various filters must be specified as a comma separated list: --branch-filter any_ret,u,k | |
183 | Note that this feature may not be available on all processors. | |
bdfebd84 | 184 | |
05484298 AK |
185 | -W:: |
186 | --weight:: | |
187 | Enable weightened sampling. An additional weight is recorded per sample and can be | |
188 | displayed with the weight and local_weight sort keys. This currently works for TSX | |
189 | abort events and some memory events in precise mode on modern Intel CPUs. | |
190 | ||
e33e0a43 IM |
191 | SEE ALSO |
192 | -------- | |
386b05e3 | 193 | linkperf:perf-stat[1], linkperf:perf-list[1] |