1TIPTOP(1)                            Inria                           TIPTOP(1)
2
3
4

NAME

6       tiptop - display hardware performance counters for Linux tasks
7
8

SYNOPSIS

10       tiptop [OPTION]
11
12       tiptop [OPTION] -- command  (EXPERIMENTAL)
13
14       ptiptop PATTERN [OPTIONS]
15
16

DESCRIPTION

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
22       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
30       Unless  tiptop is run by root, or the executable is setuid-root, a user
31       can only monitor the tasks it owns.
32
33       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
41       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
45       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
54       ptiptop is simply a shortcut for tiptop -p.
55
56       tiptop requires Linux 2.6.31+.
57
58
59

COMMAND-LINE OPTIONS

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
65
66       -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
70
71       -c  display the command line of the task instead of its name. (toggle)
72
73
74       --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
78
79       -d VALUE
80           Specify  the  delay  between refreshes. VALUE can be fractional. It
81           must be larger than 0.01.
82
83
84       -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
88
89       --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
94
95       -h --help
96           Print a brief help message and exit.
97
98
99       -H  Show threads. (toggle)
100
101
102       -i  Show idle tasks. (toggle)
103
104
105       -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
112
113       --list-screens
114           List available screens and exit.
115
116
117       -n VALUE
118           Automatically exit after VALUE iterations.
119
120
121       --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
128
129       -o FILENAME
130           Specify the filename for the output of batch mode.
131
132
133       --only-conf
134           Only screens defined in configuration file displayed (no default).
135
136
137       -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
143
144       -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
148
149       --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
154
155       --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
161
162       -u USER
163           Only show tasks owned by USER. USER can be either a login name,  or
164           the numeric value UID.
165
166
167       -U  Show the owner of each task. (toggle)
168
169
170       -v  Display build information and exit.
171
172
173       --version
174           Display version information and disclaimer and exit.
175
176
177       -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
185
186       -W PATH
187           Directory where the configuration file is located.
188
189

INTERACTIVE COMMANDS

191       In live-mode, tiptop accepts single-key commands.
192
193
194       LEFT, RIGHT
195           Rotate through available screens.
196
197
198       <, >
199           Change the reference column for sorting  to  the  left  or  to  the
200           right.
201
202
203       c   Toggle between showing task names and command lines.
204
205
206       d   Change  the  refresh interval. The new value is queried. Fractional
207           values larger than 0.01 are accepted.
208
209
210       e   Display the  errors  encoutered  so  far.  Scroll  with  UP,  DOWN,
211           PAGE_UP, PAGE_DOWN, HOME and END.
212
213
214       h   Display a brief description of the screen and each column.
215
216
217       H   Toggle  between  showing individual threads and accumulating values
218           per process.
219
220
221       i   Toggle between showing only active  tasks  and  showing  also  idle
222           tasks.
223
224
225       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
229
230       k   Kill  a  process.  The user is asked for the PID, and the signal to
231           send.
232
233
234       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
239
240       q   Quit.
241
242
243       R   Change sorting order: ascending or descending.
244
245
246       S   Toggle sticky mode.
247
248
249       s   Same as d.
250
251
252       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
257
258       U   Toggle displaying each task's owner.
259
260
261       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
265
266       W   Writes a configuration file for the current state  in  the  current
267           directory.
268
269
270

FILES

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
277
278   Syntax
279       The file is structured in XML. The syntax is as follows.
280
281
282       Root of tree
283              The root of the xml tree is tiptop.  <tiptop> ... </tiptop>
284
285
286       Options
287              Options can be specified on an <options> block.
288
289              <options>
290                <option name="option1" value="value_option1"/>
291                <option name="option2" value="value_option2"/>
292                     ...  </options>
293
294              Recognized options listed below, with their  corresponding  com‐
295              mand line option.
296
297              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
302
303       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
308              <screen name="my_screen" desc="what this screen is about">
309                     ....  </screen>
310
311              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
316              Predefined  values  are:  CPU_CYCLES, INSTRUCTIONS, CACHE_REFER‐
317              ENCES,  CACHE_MISSES,  BRANCH_INSTRUCTIONS,  BRANCH_MISSES,  and
318              BUS_CYCLES.
319
320              <counter alias="instr" config="INSTRUCTIONS" />
321
322              For  non-predefined configs, a type must be provided. Currently,
323              only RAW and HW_CACHE are supported.
324
325              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
332              <counter alias="uops_issued" config="0x010e"
333                       type="RAW" arch="x86" model="06_2A" />
334
335              For the x86 architecture, a single counter can be valid for sev‐
336              eral models.
337
338              <counter alias="uOP" config="0x1c2" type="RAW"
339                       arch="x86" model="06_1A;06_1E;06_1F;06_2E" />
340
341              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
348              Note  that  "shift  left" is expressed as shl (the usual << does
349              not fit well in xml).
350
351              <counter alias="L1Rmiss" type="HW_CACHE"
352                       config="L1D | (OP_READ shl 8) | (RESULT_MISS shl 16)" />
353
354              See also /usr/include/linux/perf_events.h for more on config and
355              type.
356
357              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
361              <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
370              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
378              <column header=" ipc" format="%4.2f"
379                    desc="Average IPC over last period"
380                    expr="delta(instr) / delta(cycle)" />
381
382
383
384       Sample config file
385
386              <tiptop>
387
388                <options>
389                  <option name="delay" value="2.0" />
390                  <option name="stick" value="1" />
391                </options>
392
393                <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
399                  <!-- Sandy Bridge only -->
400                  <counter alias="uops_issued" config="0x010e"
401                           type="RAW" arch="x86" model="06_2A" />
402
403                  <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
428
429

CAVEATS

431       tiptop does not seem to work within a virtualized environment.
432
433       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
438       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
442
443

BUGS

445       Send bug reports to:
446          Erven Rohou <erven.rohou@inria.fr>
447
448
449

AUTHOR

451       Written by Erven Rohou.
452
453

SEE ALSO

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+)
458
459
460
461Linux                            February 2013                       TIPTOP(1)
Impressum