1PERF-CONFIG(1)                    perf Manual                   PERF-CONFIG(1)
2
3
4

NAME

6       perf-config - Get and set variables in a configuration file.
7

SYNOPSIS

9       perf config [<file-option>] [section.name[=value] ...]
10       or
11       perf config [<file-option>] -l | --list
12

DESCRIPTION

14       You can manage variables in a configuration file with this command.
15

OPTIONS

17       -l, --list
18           Show current config variables, name and value, for all sections.
19
20       --user
21           For writing and reading options: write to user $HOME/.perfconfig
22           file or read it.
23
24       --system
25           For writing and reading options: write to system-wide
26           $(sysconfdir)/perfconfig or read it.
27

CONFIGURATION FILE

29       The perf configuration file contains many variables to change various
30       aspects of each of its tools, including output, disk usage, etc. The
31       $HOME/.perfconfig file is used to store a per-user configuration. The
32       file $(sysconfdir)/perfconfig can be used to store a system-wide
33       default configuration.
34
35       When reading or writing, the values are read from the system and user
36       configuration files by default, and options --system and --user can be
37       used to tell the command to read from or write to only that location.
38
39   Syntax
40       The file consist of sections. A section starts with its name surrounded
41       by square brackets and continues till the next section begins. Each
42       variable must be in a section, and have the form name = value, for
43       example:
44
45           [section]
46                   name1 = value1
47                   name2 = value2
48
49       Section names are case sensitive and can contain any characters except
50       newline (double quote " and backslash have to be escaped as \" and \\,
51       respectively). Section headers can’t span multiple lines.
52
53   Example
54       Given a $HOME/.perfconfig like this:
55
56       # # This is the config file, and # a # and ; character indicates a
57       comment #
58
59           [colors]
60                   # Color variables
61                   top = red, default
62                   medium = green, default
63                   normal = lightgray, default
64                   selected = white, lightgray
65                   jump_arrows = blue, default
66                   addr = magenta, default
67                   root = white, blue
68
69           [tui]
70                   # Defaults if linked with libslang
71                   report = on
72                   annotate = on
73                   top = on
74
75           [buildid]
76                   # Default, disable using /dev/null
77                   dir = ~/.debug
78
79           [annotate]
80                   # Defaults
81                   hide_src_code = false
82                   use_offset = true
83                   jump_arrows = true
84                   show_nr_jumps = false
85
86           [help]
87                   # Format can be man, info, web or html
88                   format = man
89                   autocorrect = 0
90
91           [ui]
92                   show-headers = true
93
94           [call-graph]
95                   # fp (framepointer), dwarf
96                   record-mode = fp
97                   print-type = graph
98                   order = caller
99                   sort-key = function
100
101           [report]
102                   # Defaults
103                   sort_order = comm,dso,symbol
104                   percent-limit = 0
105                   queue-size = 0
106                   children = true
107                   group = true
108
109           [llvm]
110                   dump-obj = true
111                   clang-opt = -g
112
113       You can hide source code of annotate feature setting the config to
114       false with
115
116           % perf config annotate.hide_src_code=true
117
118       If you want to add or modify several config items, you can do like
119
120           % perf config ui.show-headers=false kmem.default=slab
121
122       To modify the sort order of report functionality in user config
123       file(i.e. ~/.perfconfig), do
124
125           % perf config --user report sort-order=srcline
126
127       To change colors of selected line to other foreground and background
128       colors in system config file (i.e. $(sysconf)/perfconfig), do
129
130           % perf config --system colors.selected=yellow,green
131
132       To query the record mode of call graph, do
133
134           % perf config call-graph.record-mode
135
136       If you want to know multiple config key/value pairs, you can do like
137
138           % perf config report.queue-size call-graph.order report.children
139
140       To query the config value of sort order of call graph in user config
141       file (i.e. ~/.perfconfig), do
142
143           % perf config --user call-graph.sort-order
144
145       To query the config value of buildid directory in system config file
146       (i.e. $(sysconf)/perfconfig), do
147
148           % perf config --system buildid.dir
149
150   Variables
151       colors.*
152           The variables for customizing the colors used in the output for the
153           report, top and annotate in the TUI. They should specify the
154           foreground and background colors, separated by a comma, for
155           example:
156
157               medium = green, lightgray
158
159               If you want to use the color configured for you terminal, just leave it
160               as 'default', for example:
161
162               medium = default, lightgray
163
164               Available colors:
165               red, yellow, green, cyan, gray, black, blue,
166               white, default, magenta, lightgray
167
168       colors.top
169           top means a overhead percentage which is more than 5%. And values
170           of this variable specify percentage colors. Basic key values are
171           foreground-color red and background-color default.
172
173       colors.medium
174           medium means a overhead percentage which has more than 0.5%.
175           Default values are green and default.
176
177       colors.normal
178           normal means the rest of overhead percentages except top, medium,
179           selected. Default values are lightgray and default.
180
181       colors.selected
182           This selects the colors for the current entry in a list of entries
183           from sub-commands (top, report, annotate). Default values are black
184           and lightgray.
185
186       colors.jump_arrows
187           Colors for jump arrows on assembly code listings such as jns, jmp,
188           jane, etc. Default values are blue, default.
189
190       colors.addr
191           This selects colors for addresses from annotate. Default values are
192           magenta, default.
193
194       colors.root
195           Colors for headers in the output of a sub-commands (top, report).
196           Default values are white, blue.
197
198       core.*, core.proc-map-timeout
199           Sets a timeout (in milliseconds) for parsing /proc/<pid>/maps
200           files. Can be overridden by the --proc-map-timeout option on
201           supported subcommands. The default timeout is 500ms.
202
203       tui., gtk.
204           Subcommands that can be configured here are top, report and
205           annotate. These values are booleans, for example:
206
207               [tui]
208                       top = true
209
210               will make the TUI be the default for the 'top' subcommand. Those will be
211               available if the required libs were detected at tool build time.
212
213       buildid.*, buildid.dir
214           Each executable and shared library in modern distributions comes
215           with a content based identifier that, if available, will be
216           inserted in a perf.data file header to, at analysis time find what
217           is needed to do symbol resolution, code annotation, etc.
218
219               The recording tools also stores a hard link or copy in a per-user
220               directory, $HOME/.debug/, of binaries, shared libraries, /proc/kallsyms
221               and /proc/kcore files to be used at analysis time.
222
223               The buildid.dir variable can be used to either change this directory
224               cache location, or to disable it altogether. If you want to disable it,
225               set buildid.dir to /dev/null. The default is $HOME/.debug
226
227       annotate.*
228           These options work only for TUI. These are in control of addresses,
229           jump function, source code in lines of assembly code from a
230           specific program.
231
232       annotate.hide_src_code
233           If a program which is analyzed has source code, this option lets
234           annotate print a list of assembly code with the source code. For
235           example, let’s see a part of a program. There’re four lines. If
236           this option is true, they can be printed without source code from a
237           program as below.
238
239               │        push   %rbp
240               │        mov    %rsp,%rbp
241               │        sub    $0x10,%rsp
242               │        mov    (%rdi),%rdx
243
244               But if this option is 'false', source code of the part
245               can be also printed as below. Default is 'false'.
246
247               │      struct rb_node *rb_next(const struct rb_node *node)
248               │      {
249               │        push   %rbp
250               │        mov    %rsp,%rbp
251               │        sub    $0x10,%rsp
252               │              struct rb_node *parent;
253
254               │              if (RB_EMPTY_NODE(node))
255               │        mov    (%rdi),%rdx
256               │              return n;
257
258       annotate.use_offset
259           Basing on a first address of a loaded function, offset can be used.
260           Instead of using original addresses of assembly code, addresses
261           subtracted from a base address can be printed. Let’s illustrate an
262           example. If a base address is 0XFFFFFFFF81624d50 as below,
263
264               ffffffff81624d50 <load0>
265
266               an address on assembly code has a specific absolute address as below
267
268               ffffffff816250b8:│  mov    0x8(%r14),%rdi
269
270               but if use_offset is 'true', an address subtracted from a base address is printed.
271               Default is true. This option is only applied to TUI.
272
273               368:│  mov    0x8(%r14),%rdi
274
275       annotate.jump_arrows
276           There can be jump instruction among assembly code. Depending on a
277           boolean value of jump_arrows, arrows can be printed or not which
278           represent where do the instruction jump into as below.
279
280               │     ┌──jmp    1333
281               │     │  xchg   %ax,%ax
282               │1330:│  mov    %r15,%r10
283               │1333:└─→cmp    %r15,%r14
284
285               If jump_arrow is 'false', the arrows isn't printed as below.
286               Default is 'false'.
287
288               │      ↓ jmp    1333
289               │        xchg   %ax,%ax
290               │1330:   mov    %r15,%r10
291               │1333:   cmp    %r15,%r14
292
293       annotate.show_linenr
294           When showing source code if this option is true, line numbers are
295           printed as below.
296
297               │1628         if (type & PERF_SAMPLE_IDENTIFIER) {
298               │     ↓ jne    508
299               │1628                 data->id = *array;
300               │1629                 array++;
301               │1630         }
302
303               However if this option is 'false', they aren't printed as below.
304               Default is 'false'.
305
306               │             if (type & PERF_SAMPLE_IDENTIFIER) {
307               │     ↓ jne    508
308               │                     data->id = *array;
309               │                     array++;
310               │             }
311
312       annotate.show_nr_jumps
313           Let’s see a part of assembly code.
314
315               │1382:   movb   $0x1,-0x270(%rbp)
316
317               If use this, the number of branches jumping to that address can be printed as below.
318               Default is 'false'.
319
320               │1 1382:   movb   $0x1,-0x270(%rbp)
321
322       annotate.show_total_period
323           To compare two records on an instruction base, with this option
324           provided, display total number of samples that belong to a line in
325           assembly code. If this option is true, total periods are printed
326           instead of percent values as below.
327
328               302 │      mov    %eax,%eax
329
330               But if this option is 'false', percent values for overhead are printed i.e.
331               Default is 'false'.
332
333               99.93 │      mov    %eax,%eax
334
335       annotate.offset_level
336           Default is 1, meaning just jump targets will have offsets show
337           right beside the instruction. When set to 2 call instructions will
338           also have its offsets shown, 3 or higher will show offsets for all
339           instructions.
340
341       hist.*, hist.percentage
342           This option control the way to calculate overhead of filtered
343           entries - that means the value of this option is effective only if
344           there’s a filter (by comm, dso or symbol name). Suppose a following
345           example:
346
347               Overhead  Symbols
348               ........  .......
349                33.33%     foo
350                33.33%     bar
351                33.33%     baz
352
353               This is an original overhead and we'll filter out the first 'foo'
354               entry. The value of 'relative' would increase the overhead of 'bar'
355               and 'baz' to 50.00% for each, while 'absolute' would show their
356               current overhead (33.33%).
357
358       ui.*, ui.show-headers
359           This option controls display of column headers (like Overhead and
360           Symbol) in report and top. If this option is false, they are
361           hidden. This option is only applied to TUI.
362
363       call-graph.*
364           When sub-commands top and report work with -g/—-children there’re
365           options in control of call-graph.
366
367       call-graph.record-mode
368           The record-mode can be fp (frame pointer), dwarf and lbr. The value
369           of dwarf is effective only if perf detect needed library (libunwind
370           or a recent version of libdw).  lbr only work for cpus that support
371           it.
372
373       call-graph.dump-size
374           The size of stack to dump in order to do post-unwinding. Default is
375           8192 (byte). When using dwarf into record-mode, the default size
376           will be used if omitted.
377
378       call-graph.print-type
379           The print-types can be graph (graph absolute), fractal (graph
380           relative), flat and folded. This option controls a way to show
381           overhead for each callchain entry. Suppose a following example.
382
383               Overhead  Symbols
384               ........  .......
385                 40.00%  foo
386                         |
387                         ---foo
388                            |
389                            |--50.00%--bar
390                            |          main
391                            |
392                             --50.00%--baz
393                                       main
394
395               This output is a 'fractal' format. The 'foo' came from 'bar' and 'baz' exactly
396               half and half so 'fractal' shows 50.00% for each
397               (meaning that it assumes 100% total overhead of 'foo').
398
399               The 'graph' uses absolute overhead value of 'foo' as total so each of
400               'bar' and 'baz' callchain will have 20.00% of overhead.
401               If 'flat' is used, single column and linear exposure of call chains.
402               'folded' mean call chains are displayed in a line, separated by semicolons.
403
404       call-graph.order
405           This option controls print order of callchains. The default is
406           callee which means callee is printed at top and then followed by
407           its caller and so on. The caller prints it in reverse order.
408
409               If this option is not set and report.children or top.children is
410               set to true (or the equivalent command line option is given),
411               the default value of this option is changed to 'caller' for the
412               execution of 'perf report' or 'perf top'. Other commands will
413               still default to 'callee'.
414
415       call-graph.sort-key
416           The callchains are merged if they contain same information. The
417           sort-key option determines a way to compare the callchains. A value
418           of sort-key can be function or address. The default is function.
419
420       call-graph.threshold
421           When there’re many callchains it’d print tons of lines. So perf
422           omits small callchains under a certain overhead (threshold) and
423           this option control the threshold. Default is 0.5 (%). The overhead
424           is calculated by value depends on call-graph.print-type.
425
426       call-graph.print-limit
427           This is a maximum number of lines of callchain printed for a single
428           histogram entry. Default is 0 which means no limitation.
429
430       report.*, report.sort_order
431           Allows changing the default sort order from "comm,dso,symbol" to
432           some other default, for instance "sym,dso" may be more fitting for
433           kernel developers.
434
435       report.percent-limit
436           This one is mostly the same as call-graph.threshold but works for
437           histogram entries. Entries having an overhead lower than this
438           percentage will not be printed. Default is 0. If percent-limit is
439           10, only entries which have more than 10% of overhead will be
440           printed.
441
442       report.queue-size
443           This option sets up the maximum allocation size of the internal
444           event queue for ordering events. Default is 0, meaning no limit.
445
446       report.children
447           Children means functions called from another function. If this
448           option is true, perf report cumulates callchains of children and
449           show (accumulated) total overhead as well as Self overhead. Please
450           refer to the perf report manual. The default is true.
451
452       report.group
453           This option is to show event group information together. Example
454           output with this turned on, notice that there is one column per
455           event in the group, ref-cycles and cycles:
456
457               # group: {ref-cycles,cycles}
458               # ========
459               #
460               # Samples: 7K of event 'anon group { ref-cycles, cycles }'
461               # Event count (approx.): 6876107743
462               #
463               #         Overhead  Command      Shared Object               Symbol
464               # ................  .......  .................  ...................
465               #
466                   99.84%  99.76%  noploop  noploop            [.] main
467                    0.07%   0.00%  noploop  ld-2.15.so         [.] strcmp
468                    0.03%   0.00%  noploop  [kernel.kallsyms]  [k] timerqueue_del
469
470       top.*, top.children
471           Same as report.children. So if it is enabled, the output of top
472           command will have Children overhead column as well as Self overhead
473           column by default. The default is true.
474
475       man.*, man.viewer
476           This option can assign a tool to view manual pages when help
477           subcommand was invoked. Supported tools are man, woman (with emacs
478           client) and konqueror. Default is man.
479
480               New man viewer tool can be also added using 'man.<tool>.cmd'
481               or use different path using 'man.<tool>.path' config option.
482
483       pager.*, pager.<subcommand>
484           When the subcommand is run on stdio, determine whether it uses
485           pager or not based on this value. Default is unspecified.
486
487       kmem.*, kmem.default
488           This option decides which allocator is to be analyzed if neither
489           --slab nor --page option is used. Default is slab.
490
491       record.*, record.build-id
492           This option can be cache, no-cache or skip.  cache is to
493           post-process data and save/update the binaries into the build-id
494           cache (in ~/.debug). This is the default. But if this option is
495           no-cache, it will not update the build-id cache.  skip skips
496           post-processing and does not update the cache.
497
498       diff.*, diff.order
499           This option sets the number of columns to sort the result. The
500           default is 0, which means sorting by baseline. Setting it to 1 will
501           sort the result by delta (or other compute method selected).
502
503       diff.compute
504           This options sets the method for computing the diff result.
505           Possible values are delta, delta-abs, ratio and wdiff. Default is
506           delta.
507
508       trace.*, trace.add_events
509           Allows adding a set of events to add to the ones specified by the
510           user, or use as a default one if none was specified. The initial
511           use case is to add augmented_raw_syscalls.o to activate the perf
512           trace logic that looks for syscall pointer contents after the
513           normal tracepoint payload.
514
515       trace.args_alignment
516           Number of columns to align the argument list, default is 70, use 40
517           for the strace default, zero to no alignment.
518
519       trace.no_inherit
520           Do not follow children threads.
521
522       trace.show_arg_names
523           Should syscall argument names be printed? If not then
524           trace.show_zeros will be set.
525
526       trace.show_duration
527           Show syscall duration.
528
529       trace.show_prefix
530           If set to yes will show common string prefixes in tables. The
531           default is to remove the common prefix in things like "MAP_SHARED",
532           showing just "SHARED".
533
534       trace.show_timestamp
535           Show syscall start timestamp.
536
537       trace.show_zeros
538           Do not suppress syscall arguments that are equal to zero.
539
540       llvm.*, llvm.clang-path
541           Path to clang. If omit, search it from $PATH.
542
543       llvm.clang-bpf-cmd-template
544           Cmdline template. Below lines show its default value. Environment
545           variable is used to pass options. "$CLANG_EXEC -DKERNEL
546           $CLANG_OPTIONS $KERNEL_INC_OPTIONS \ -Wno-unused-value
547           -Wno-pointer-sign -working-directory \ $WORKING_DIR -c
548           $CLANG_SOURCE -target bpf -O2 -o -"
549
550       llvm.clang-opt
551           Options passed to clang.
552
553       llvm.kbuild-dir
554           kbuild directory. If not set, use /lib/modules/uname -r/build. If
555           set to "" deliberately, skip kernel header auto-detector.
556
557       llvm.kbuild-opts
558           Options passed to make when detecting kernel header options.
559
560       llvm.dump-obj
561           Enable perf dump BPF object files compiled by LLVM.
562
563       llvm.opts
564           Options passed to llc.
565
566       samples.*, samples.context
567           Define how many ns worth of time to show around samples in perf
568           report sample context browser.
569
570       scripts.*
571           Any option defines a script that is added to the scripts menu in
572           the interactive perf browser and whose output is displayed. The
573           name of the option is the name, the value is a script command line.
574           The script gets the same options passed as a full perf script, in
575           particular -i perfdata file, --cpu, --tid
576

SEE ALSO

578       perf(1)
579
580
581
582perf                              06/03/2019                    PERF-CONFIG(1)
Impressum