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

SEE ALSO

710       perf(1)
711
712
713
714perf                              01/12/2023                    PERF-CONFIG(1)
Impressum