1PERF-CONFIG(1) perf Manual PERF-CONFIG(1)
2
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 --user
21 For writing and reading options: write to user $HOME/.perfconfig
22 file or read it.
23 --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 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 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 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 [section]
50 name1 = value1
51 name2 = value2
52 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 Example
58 Given a $HOME/.perfconfig like this:
59 # # This is the config file, and # a # and ; character indicates a
61 comment #
62 [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 [tui]
74 # Defaults if linked with libslang
75 report = on
76 annotate = on
77 top = on
78 [buildid]
80 # Default, disable using /dev/null
81 dir = ~/.debug
82 [annotate]
84 # Defaults
85 hide_src_code = false
86 use_offset = true
87 jump_arrows = true
88 show_nr_jumps = false
89 [help]
91 # Format can be man, info, web or html
92 format = man
93 autocorrect = 0
94 [ui]
96 show-headers = true
97 [call-graph]
99 # fp (framepointer), dwarf
100 record-mode = fp
101 print-type = graph
102 order = caller
103 sort-key = function
104 [report]
106 # Defaults
107 sort_order = comm,dso,symbol
108 percent-limit = 0
109 queue-size = 0
110 children = true
111 group = true
112 [llvm]
114 dump-obj = true
115 clang-opt = -g
116 You can hide source code of annotate feature setting the config to
118 false with
119 % perf config annotate.hide_src_code=true
121 If you want to add or modify several config items, you can do like
123 % perf config ui.show-headers=false kmem.default=slab
125 To modify the sort order of report functionality in user config
127 file(i.e. ~/.perfconfig), do
128 % perf config --user report.sort-order=srcline
130 To change colors of selected line to other foreground and background
132 colors in system config file (i.e. $(sysconf)/perfconfig), do
133 % perf config --system colors.selected=yellow,green
135 To query the record mode of call graph, do
137 % perf config call-graph.record-mode
139 If you want to know multiple config key/value pairs, you can do like
141 % perf config report.queue-size call-graph.order report.children
143 To query the config value of sort order of call graph in user config
145 file (i.e. ~/.perfconfig), do
146 % perf config --user call-graph.sort-order
148 To query the config value of buildid directory in system config file
150 (i.e. $(sysconf)/perfconfig), do
151 % perf config --system buildid.dir
153 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 medium = green, lightgray
162 If you want to use the color configured for you terminal, just leave it
164 as 'default', for example:
165 medium = default, lightgray
167 Available colors:
169 red, yellow, green, cyan, gray, black, blue,
170 white, default, magenta, lightgray
171 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 colors.medium
178 medium means a overhead percentage which has more than 0.5%.
179 Default values are green and default.
180 colors.normal
182 normal means the rest of overhead percentages except top, medium,
183 selected. Default values are lightgray and default.
184 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 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 colors.addr
195 This selects colors for addresses from annotate. Default values are
196 magenta, default.
197 colors.root
199 Colors for headers in the output of a sub-commands (top, report).
200 Default values are white, blue.
201 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 tui., gtk.
208 Subcommands that can be configured here are top, report and
209 annotate. These values are booleans, for example:
210 [tui]
212 top = true
213 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 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 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 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 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 buildid-cache.debuginfod=http://192.168.122.174:8002
237 annotate.*
239 These are in control of addresses, jump function, source code in
240 lines of assembly code from a specific program.
241 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 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 │ push %rbp
255 │ mov %rsp,%rbp
256 │ sub $0x10,%rsp
257 │ mov (%rdi),%rdx
258 But if this option is 'false', source code of the part
260 can be also printed as below. Default is 'false'.
261 │ 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 This option works with tui, stdio2 browsers.
274 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 ffffffff81624d50 <load0>
282 an address on assembly code has a specific absolute address as below
284 ffffffff816250b8:│ mov 0x8(%r14),%rdi
286 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 368:│ mov 0x8(%r14),%rdi
291 This option works with tui, stdio2 browsers.
293 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 │ ┌──jmp 1333
300 │ │ xchg %ax,%ax
301 │1330:│ mov %r15,%r10
302 │1333:└─→cmp %r15,%r14
303 If jump_arrow is 'false', the arrows isn't printed as below.
305 Default is 'false'.
306 │ ↓ jmp 1333
308 │ xchg %ax,%ax
309 │1330: mov %r15,%r10
310 │1333: cmp %r15,%r14
311 This option works with tui browser.
313 annotate.show_linenr
315 When showing source code if this option is true, line numbers are
316 printed as below.
317 │1628 if (type & PERF_SAMPLE_IDENTIFIER) {
319 │ ↓ jne 508
320 │1628 data->id = *array;
321 │1629 array++;
322 │1630 }
323 However if this option is 'false', they aren't printed as below.
325 Default is 'false'.
326 │ if (type & PERF_SAMPLE_IDENTIFIER) {
328 │ ↓ jne 508
329 │ data->id = *array;
330 │ array++;
331 │ }
332 This option works with tui, stdio2 browsers.
334 annotate.show_nr_jumps
336 Let’s see a part of assembly code.
337 │1382: movb $0x1,-0x270(%rbp)
339 If use this, the number of branches jumping to that address can be printed as below.
341 Default is 'false'.
342 │1 1382: movb $0x1,-0x270(%rbp)
344 This option works with tui, stdio2 browsers.
346 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 302 │ mov %eax,%eax
354 But if this option is 'false', percent values for overhead are printed i.e.
356 Default is 'false'.
357 99.93 │ mov %eax,%eax
359 This option works with tui, stdio2, stdio browsers.
361 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 Percent│
368 74.03 │ mov %fs:0x28,%rax
369 When set as true:
371 Samples│
373 6 │ mov %fs:0x28,%rax
374 This option works with tui, stdio2, stdio browsers.
376 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 This option works with tui, stdio2 browsers.
384 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 Overhead Symbols
392 ........ .......
393 33.33% foo
394 33.33% bar
395 33.33% baz
396 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 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 call-graph.*
408 The following controls the handling of call-graphs (obtained via
409 the -g/--call-graph options).
410 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 # 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 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 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 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 New man viewer tool can be also added using 'man.<tool>.cmd'
532 or use different path using 'man.<tool>.path' config option.
533 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 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 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 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 record.aio
557 Use n control blocks in asynchronous (Posix AIO) trace writing mode
558 (n default: 1, max: 4).
559 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 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 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 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 trace.no_inherit
582 Do not follow children threads.
583 trace.show_arg_names
585 Should syscall argument names be printed? If not then
586 trace.show_zeros will be set.
587 trace.show_duration
589 Show syscall duration.
590 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 trace.show_timestamp
597 Show syscall start timestamp.
598 trace.show_zeros
600 Do not suppress syscall arguments that are equal to zero.
601 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 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 llvm.*, llvm.clang-path
613 Path to clang. If omit, search it from $PATH.
614 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 llvm.clang-opt
625 Options passed to clang.
626 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 llvm.kbuild-opts
632 Options passed to make when detecting kernel header options.
633 llvm.dump-obj
635 Enable perf dump BPF object files compiled by LLVM.
636 llvm.opts
638 Options passed to llc.
639 samples.*, samples.context
641 Define how many ns worth of time to show around samples in perf
642 report sample context browser.
643 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 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 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 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 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 daemon.*, daemon.base
670 Base path for daemon data. All sessions data are stored under this
671 path.
672 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
678 perf(1)
679perf 06/03/2021 PERF-CONFIG(1)