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

SEE ALSO

684       perf(1)
685
686
687
688perf                              11/28/2023                    PERF-CONFIG(1)
Impressum