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

SEE ALSO

678       perf(1)
679
680
681
682perf                              06/03/2021                    PERF-CONFIG(1)
Impressum