1PERF-CONFIG(1) perf Manual PERF-CONFIG(1)
2
3
4
6 perf-config - Get and set variables in a configuration file.
7
9 perf config [<file-option>] [section.name[=value] ...]
10 or
11 perf config [<file-option>] -l | --list
12
14 You can manage variables in a configuration file with this command.
15
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
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
710 perf(1)
711
712
713
714perf 01/12/2023 PERF-CONFIG(1)