1TIPTOP(1) Inria TIPTOP(1)
2
6 tiptop - display hardware performance counters for Linux tasks
7
10 tiptop [OPTION]
11 tiptop [OPTION] -- command (EXPERIMENTAL)
13 ptiptop PATTERN [OPTIONS]
15
18 The tiptop program provides a dynamic real-time view of the tasks run‐
19 ning in the system. tiptop is very similar to top (1), but the informa‐
20 tion displayed comes from hardware counters.
21 tiptop has two running modes: live-mode and batch-mode. In both modes,
23 the system is periodically queried for the values of hardware counters,
24 and various ratios are printed for each task. In live-mode, the display
25 is regularly updated with new values at constant time intervals. In
26 batch-mode, the same information is emitted to stdout. Batch-mode is
27 appropriate for saving to a file or for further processing. No interac‐
28 tion is possible in batch-mode.
29 Unless tiptop is run by root, or the executable is setuid-root, a user
31 can only monitor the tasks it owns.
32 The results produced by tiptop are organized in screens. A screen con‐
34 sists in rows representing tasks, and columns reporting various values
35 and ratios collected from hardware counters. Many screens can be
36 defined. Only one screen is displayed at a time. The default screen
37 (number 0) reports target independent values as defined in the file
38 /usr/include/linux/event_counter.h. Other screens may rely on target-
39 dependent counters.
40 When an expression would result in a division by zero, a '-' sign is
42 printed. When a counter involved in an expression could not be read, a
43 '?' sign is printed.
44 If -- appears in the command line, tiptop treats the rest of the line
46 as a command. A new process is forked, and hardware counters are
47 attached just before execvp is called. This makes it possible to trace
48 an application from the first instruction. Only the child is traced,
49 and idle-mode is enabled (in live mode, this can be overridden by hit‐
50 ting keys 'p' and 'i'). This is commonly used in combination with
51 sticky mode to track a command from start to finish. This is experimen‐
52 tal!
53 ptiptop is simply a shortcut for tiptop -p.
55 tiptop requires Linux 2.6.31+.
57
61 Command line options with a parameter override values specified in the
62 configuration file. Toggles set the value or invert the value read in
63 the configuration file (if any).
64 -b Start tiptop in batch-mode. Output is sent to stdout, and no inter‐
67 active command is accepted. tiptop will run forever, or until the
68 number of iterations specified by -n.
69 -c display the command line of the task instead of its name. (toggle)
72 --cpu-min VALUE
75 %CPU activity threshold. Below this value, a task is considered
76 idle and is not reported (unless idle-mode is on, see flag -i).
77 -d VALUE
80 Specify the delay between refreshes. VALUE can be fractional. It
81 must be larger than 0.01.
82 -E FILENAME
85 Specify file where errors are logged. By default errors are logged
86 to stderr in batch-mode, and a temporary file in live-mode.
87 --epoch
90 Print the Epoch at each refresh. In batch-mode, it is printed at
91 the beginning of each row. In live-mode, it is at the bottom of the
92 display. (toggle)
93 -h --help
96 Print a brief help message and exit.
97 -H Show threads. (toggle)
100 -i Show idle tasks. (toggle)
103 -K --kernel
106 Include kernel activity in the reported values. This is only possi‐
107 ble is the user is root, the tiptop executable is setuid root, or
108 the paranoia level is low enough. (toggle)
109 See file /proc/sys/kernel/perf_event_paranoid
110 (perf_counter_paranoid on Linux 2.6.31).
111 --list-screens
114 List available screens and exit.
115 -n VALUE
118 Automatically exit after VALUE iterations.
119 --no-collect
122 By default, when the maximum number of open files is reached, and
123 new processes appear, tiptop searches for idle processes and closes
124 the files in order to make room for the new ones. This flag dis‐
125 ables this behavior: in case of file shortage, new processes will
126 not get more chances than older ones.
127 -o FILENAME
130 Specify the filename for the output of batch mode.
131 --only-conf
134 Only screens defined in configuration file displayed (no default).
135 -p --pid VALUE
138 Filters processes according to VALUE. VALUE can be either the
139 numeric value PID, or a string. In case of a string, all tasks
140 whose names or command lines (depending on the display, see -c)
141 contain VALUE are reported.
142 -S VALUE
145 Start tiptop with screen number VALUE if VALUE is an integer. Oth‐
146 erwise looks for the first screen whose name contains VALUE.
147 --sticky
150 Start in sticky mode: tasks stay in the list after they die. In
151 live-mode, they appear in a different color (when supported). In
152 batch-mode, the word DEAD is appended. (toggle)
153 --timestamp
156 Print a timestamp at the beginning of each row. The timestamp is
157 the number of refreshes so far. In batch-mode, it is printed at the
158 beginning of each row. In live-mode, it is at the bottom of the
159 display. (toggle)
160 -u USER
163 Only show tasks owned by USER. USER can be either a login name, or
164 the numeric value UID.
165 -U Show the owner of each task. (toggle)
168 -v Display build information and exit.
171 --version
174 Display version information and disclaimer and exit.
175 -w VALUE
178 Watch the task specified by VALUE. VALUE can be either the numeric
179 value PID, or a string. In case of a string, all tasks whose names
180 or command lines (depending on the display, see -c) contain VALUE
181 are reported. In live-mode, watched tasks are shown in a different
182 color (when supported). In batch-mode, an ASCII arrow points to the
183 watched tasks.
184 -W PATH
187 Directory where the configuration file is located.
188
191 In live-mode, tiptop accepts single-key commands.
192 LEFT, RIGHT
195 Rotate through available screens.
196 <, >
199 Change the reference column for sorting to the left or to the
200 right.
201 c Toggle between showing task names and command lines.
204 d Change the refresh interval. The new value is queried. Fractional
207 values larger than 0.01 are accepted.
208 e Display the errors encoutered so far. Scroll with UP, DOWN,
211 PAGE_UP, PAGE_DOWN, HOME and END.
212 h Display a brief description of the screen and each column.
215 H Toggle between showing individual threads and accumulating values
218 per process.
219 i Toggle between showing only active tasks and showing also idle
222 tasks.
223 K Toggle between showing kernel activity and only user activity. Ker‐
226 nel mode is only available to root. Switching to and from kernel
227 mode resets all counters.
228 k Kill a process. The user is asked for the PID, and the signal to
231 send.
232 p Filter tasks by name or PID. The user is asked for a PID or string.
235 In case a string is entered, only the tasks whose name or command
236 line contain the string are displayed. Changing the filter resets
237 all counters.
238 q Quit.
241 R Change sorting order: ascending or descending.
244 S Toggle sticky mode.
247 s Same as d.
250 u Filter tasks by user. The user name or PID is queried. Note that,
253 unless tiptop is run by root or setuid root, tasks owned by some‐
254 body else cannot be monitored. Changing the filter resets all coun‐
255 ters.
256 U Toggle displaying each task's owner.
259 w Used to track a particular task. The user is asked for a PID or
262 string. In case a string is entered, all tasks whose name or com‐
263 mand line contain the string are highlighted.
264 W Writes a configuration file for the current state in the current
267 directory.
268
272 During startup, tiptop attempts to read a configuration file. The file
273 must be named .tiptoprc. This file is first searched in the current
274 directory, then in the directory defined by the environment variable
275 TIPTOP if it exists, finally in the user's home.
276 Syntax
279 The file is structured in XML. The syntax is as follows.
280 Root of tree
283 The root of the xml tree is tiptop. <tiptop> ... </tiptop>
284 Options
287 Options can be specified on an <options> block.
288 <options>
290 <option name="option1" value="value_option1"/>
291 <option name="option2" value="value_option2"/>
292 ... </options>
293 Recognized options listed below, with their corresponding com‐
295 mand line option.
296 cpu_threshold (--cpu-min), delay (-d), idle (-i), max_iter (-n),
298 show_cmdline (-c), show_epoch (--epoch), show_kernel (-K),
299 show_timestamp (--timestamp), show_threads (-H), show_user (-U),
300 watch_name (-w), sticky (--sticky), watch_uid (-w)
301 Screens
304 Screens are defined inside a <screen> block. A screen is made of
305 counters and columns. A screen has a name and an optional
306 description.
307 <screen name="my_screen" desc="what this screen is about">
309 .... </screen>
310 Counters must provide an alias (used for further reference) and
312 a configuration. The configuration is either a predefined value,
313 or the actual value that must be provided to the perf_even_open
314 system call (typically found in vendor architecture manuals).
315 Predefined values are: CPU_CYCLES, INSTRUCTIONS, CACHE_REFER‐
317 ENCES, CACHE_MISSES, BRANCH_INSTRUCTIONS, BRANCH_MISSES, and
318 BUS_CYCLES.
319 <counter alias="instr" config="INSTRUCTIONS" />
321 For non-predefined configs, a type must be provided. Currently,
323 only RAW and HW_CACHE are supported.
324 Optionally, a counter may be restricted to a specific architec‐
326 ture (such as "x86"), and a model. The definition of the model
327 is architecture-dependent. For x86, it is defined as DisplayFam‐
328 ily_DisplayModel as computed by the instruction CPUID. A
329 counter for issued micro-ops on Sandy Bridge may look like the
330 following:
331 <counter alias="uops_issued" config="0x010e"
333 type="RAW" arch="x86" model="06_2A" />
334 For the x86 architecture, a single counter can be valid for sev‐
336 eral models.
337 <counter alias="uOP" config="0x1c2" type="RAW"
339 arch="x86" model="06_1A;06_1E;06_1F;06_2E" />
340 When the type is HW_CACHE, the config is specified by shifting
342 and ORing predefined values. The 8 least significant bits repre‐
343 sent the cache level (possible values L1D, L1I, LL, DTLB, ITLB,
344 BPU). The next 8 bits represent the type of access (OP_READ,
345 OP_WRITE, OP_PREFETCH). The last 8 bits represent are one of
346 RESULT_ACCESS or RESULT_MISS.
347 Note that "shift left" is expressed as shl (the usual << does
349 not fit well in xml).
350 <counter alias="L1Rmiss" type="HW_CACHE"
352 config="L1D | (OP_READ shl 8) | (RESULT_MISS shl 16)" />
353 See also /usr/include/linux/perf_events.h for more on config and
355 type.
356 A column defines its header, the printf-like format for values,
358 and an expression. Expressions evaluate as double precision. A
359 description is optional.
360 <counter alias="instr" config="INSTRUCTIONS" />
362 <counter alias="cycle" config="CPU_CYCLES" />
363 <column header=" IPC" format="%4.2f"
364 desc="Total instructions per cycle"
365 expr="instr/cycle"/>
366 <column header=" ipc" format="%4.2f"
367 desc="Total instructions per cycle"
368 expr="instr/cycle" />
369 The syntax of expressions supports basic arithmetic (+ - * /
371 parentheses and constants). The special notation
372 "delta(counter)" evaluates as the variation of the counter
373 between refreshes. Expressions can also refer to predefined
374 variables such as CPU_TOT (CPU usage), CPU_SYS (system CPU
375 usage), CPU_USER (user CPU usage), PROC_ID (processor where the
376 process was last seen).
377 <column header=" ipc" format="%4.2f"
379 desc="Average IPC over last period"
380 expr="delta(instr) / delta(cycle)" />
381 Sample config file
385 <tiptop>
387 <options>
389 <option name="delay" value="2.0" />
390 <option name="stick" value="1" />
391 </options>
392 <screen name="example" desc="Sample config file">
394 <counter alias="cycle" config="CPU_CYCLES" />
395 <counter alias="instr" config="INSTRUCTIONS" />
396 <counter alias="miss" config="CACHE_MISSES" />
397 <counter alias="br_miss" config="BRANCH_MISSES" />
398 <!-- Sandy Bridge only -->
400 <counter alias="uops_issued" config="0x010e"
401 type="RAW" arch="x86" model="06_2A" />
402 <column header=" %CPU" format="%5.1f"
404 desc="CPU usage" expr="CPU_TOT" />
405 <column header=" P" format=" %2.0f"
406 desc="Processor where last seen" expr="PROC_ID" />
407 <column header=" Mcycle" format="%8.2f"
408 desc="Cycles (millions)"
409 expr="delta(cycle) / 1e6" />
410 <column header=" Minstr" format="%8.2f"
411 desc="Instructions (millions)"
412 expr="delta(instr) / 1e6" />
413 <column header=" IPC" format="%4.2f"
414 desc="Executed instructions per cycle"
415 expr="delta(instr) / delta(cycle)" />
416 <column header=" %MISS" format="%6.2f"
417 desc="Cache miss per instructions (in %)"
418 expr="100 * delta(miss) / delta(instr)" />
419 <column header=" %BMIS" format="%6.2f"
420 desc="Branch misprediction per instruction (in %)"
421 expr="100 * delta(br_miss) / delta(instr)" />
422 <column header="uops/inst" format=" %4.1f"
423 desc="Number of issued uops per instruction"
424 expr="delta(uops_issued) / delta(instr)" />
425 </screen>
426 </tiptop>
427
431 tiptop does not seem to work within a virtualized environment.
432 Attaching counters to processes may fail for various reasons, such as
434 asking for more than available in hardware (tiptop does not implement
435 sampling), or reaching the maximum number of open files. In these
436 cases, you may consider filtering the processes (see flags -u, -p).
437 To mitigate the limitation of the maximum number of open files, tiptop
439 tries to close the events attached to idle processes. If this is a
440 problem, see the flag --no-collect.
441
445 Send bug reports to:
446 Erven Rohou <erven.rohou@inria.fr>
447
451 Written by Erven Rohou.
452
455 top(1), ps(1)
456 /usr/include/linux/perf_counter.h (Linux 2.6.31)
457 /usr/include/linux/event_counter.h (Linux 2.6.32+)
458Linux February 2013 TIPTOP(1)