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 annotate.*
232 These are in control of addresses, jump function, source code in
233 lines of assembly code from a specific program.
234 annotate.hide_src_code
236 If a program which is analyzed has source code, this option lets
237 annotate print a list of assembly code with the source code. For
238 example, let’s see a part of a program. There’re four lines. If
239 this option is true, they can be printed without source code from a
240 program as below.
241 │ push %rbp
243 │ mov %rsp,%rbp
244 │ sub $0x10,%rsp
245 │ mov (%rdi),%rdx
246 But if this option is 'false', source code of the part
248 can be also printed as below. Default is 'false'.
249 │ struct rb_node *rb_next(const struct rb_node *node)
251 │ {
252 │ push %rbp
253 │ mov %rsp,%rbp
254 │ sub $0x10,%rsp
255 │ struct rb_node *parent;
256 │
257 │ if (RB_EMPTY_NODE(node))
258 │ mov (%rdi),%rdx
259 │ return n;
260 This option works with tui, stdio2 browsers.
262 annotate.use_offset
264 Basing on a first address of a loaded function, offset can be used.
265 Instead of using original addresses of assembly code, addresses
266 subtracted from a base address can be printed. Let’s illustrate an
267 example. If a base address is 0XFFFFFFFF81624d50 as below,
268 ffffffff81624d50 <load0>
270 an address on assembly code has a specific absolute address as below
272 ffffffff816250b8:│ mov 0x8(%r14),%rdi
274 but if use_offset is 'true', an address subtracted from a base address is printed.
276 Default is true. This option is only applied to TUI.
277 368:│ mov 0x8(%r14),%rdi
279 This option works with tui, stdio2 browsers.
281 annotate.jump_arrows
283 There can be jump instruction among assembly code. Depending on a
284 boolean value of jump_arrows, arrows can be printed or not which
285 represent where do the instruction jump into as below.
286 │ ┌──jmp 1333
288 │ │ xchg %ax,%ax
289 │1330:│ mov %r15,%r10
290 │1333:└─→cmp %r15,%r14
291 If jump_arrow is 'false', the arrows isn't printed as below.
293 Default is 'false'.
294 │ ↓ jmp 1333
296 │ xchg %ax,%ax
297 │1330: mov %r15,%r10
298 │1333: cmp %r15,%r14
299 This option works with tui browser.
301 annotate.show_linenr
303 When showing source code if this option is true, line numbers are
304 printed as below.
305 │1628 if (type & PERF_SAMPLE_IDENTIFIER) {
307 │ ↓ jne 508
308 │1628 data->id = *array;
309 │1629 array++;
310 │1630 }
311 However if this option is 'false', they aren't printed as below.
313 Default is 'false'.
314 │ if (type & PERF_SAMPLE_IDENTIFIER) {
316 │ ↓ jne 508
317 │ data->id = *array;
318 │ array++;
319 │ }
320 This option works with tui, stdio2 browsers.
322 annotate.show_nr_jumps
324 Let’s see a part of assembly code.
325 │1382: movb $0x1,-0x270(%rbp)
327 If use this, the number of branches jumping to that address can be printed as below.
329 Default is 'false'.
330 │1 1382: movb $0x1,-0x270(%rbp)
332 This option works with tui, stdio2 browsers.
334 annotate.show_total_period
336 To compare two records on an instruction base, with this option
337 provided, display total number of samples that belong to a line in
338 assembly code. If this option is true, total periods are printed
339 instead of percent values as below.
340 302 │ mov %eax,%eax
342 But if this option is 'false', percent values for overhead are printed i.e.
344 Default is 'false'.
345 99.93 │ mov %eax,%eax
347 This option works with tui, stdio2, stdio browsers.
349 annotate.show_nr_samples
351 By default perf annotate shows percentage of samples. This option
352 can be used to print absolute number of samples. Ex, when set as
353 false:
354 Percent│
356 74.03 │ mov %fs:0x28,%rax
357 When set as true:
359 Samples│
361 6 │ mov %fs:0x28,%rax
362 This option works with tui, stdio2, stdio browsers.
364 annotate.offset_level
366 Default is 1, meaning just jump targets will have offsets show
367 right beside the instruction. When set to 2 call instructions will
368 also have its offsets shown, 3 or higher will show offsets for all
369 instructions.
370 This option works with tui, stdio2 browsers.
372 hist.*, hist.percentage
374 This option control the way to calculate overhead of filtered
375 entries - that means the value of this option is effective only if
376 there’s a filter (by comm, dso or symbol name). Suppose a following
377 example:
378 Overhead Symbols
380 ........ .......
381 33.33% foo
382 33.33% bar
383 33.33% baz
384 This is an original overhead and we'll filter out the first 'foo'
386 entry. The value of 'relative' would increase the overhead of 'bar'
387 and 'baz' to 50.00% for each, while 'absolute' would show their
388 current overhead (33.33%).
389 ui.*, ui.show-headers
391 This option controls display of column headers (like Overhead and
392 Symbol) in report and top. If this option is false, they are
393 hidden. This option is only applied to TUI.
394 call-graph.*
396 When sub-commands top and report work with -g/—-children there’re
397 options in control of call-graph.
398 call-graph.record-mode
400 The record-mode can be fp (frame pointer), dwarf and lbr. The value
401 of dwarf is effective only if perf detect needed library (libunwind
402 or a recent version of libdw). lbr only work for cpus that support
403 it.
404 call-graph.dump-size
406 The size of stack to dump in order to do post-unwinding. Default is
407 8192 (byte). When using dwarf into record-mode, the default size
408 will be used if omitted.
409 call-graph.print-type
411 The print-types can be graph (graph absolute), fractal (graph
412 relative), flat and folded. This option controls a way to show
413 overhead for each callchain entry. Suppose a following example.
414 Overhead Symbols
416 ........ .......
417 40.00% foo
418 |
419 ---foo
420 |
421 |--50.00%--bar
422 | main
423 |
424 --50.00%--baz
425 main
426 This output is a 'fractal' format. The 'foo' came from 'bar' and 'baz' exactly
428 half and half so 'fractal' shows 50.00% for each
429 (meaning that it assumes 100% total overhead of 'foo').
430 The 'graph' uses absolute overhead value of 'foo' as total so each of
432 'bar' and 'baz' callchain will have 20.00% of overhead.
433 If 'flat' is used, single column and linear exposure of call chains.
434 'folded' mean call chains are displayed in a line, separated by semicolons.
435 call-graph.order
437 This option controls print order of callchains. The default is
438 callee which means callee is printed at top and then followed by
439 its caller and so on. The caller prints it in reverse order.
440 If this option is not set and report.children or top.children is
442 set to true (or the equivalent command line option is given),
443 the default value of this option is changed to 'caller' for the
444 execution of 'perf report' or 'perf top'. Other commands will
445 still default to 'callee'.
446 call-graph.sort-key
448 The callchains are merged if they contain same information. The
449 sort-key option determines a way to compare the callchains. A value
450 of sort-key can be function or address. The default is function.
451 call-graph.threshold
453 When there’re many callchains it’d print tons of lines. So perf
454 omits small callchains under a certain overhead (threshold) and
455 this option control the threshold. Default is 0.5 (%). The overhead
456 is calculated by value depends on call-graph.print-type.
457 call-graph.print-limit
459 This is a maximum number of lines of callchain printed for a single
460 histogram entry. Default is 0 which means no limitation.
461 report.*, report.sort_order
463 Allows changing the default sort order from "comm,dso,symbol" to
464 some other default, for instance "sym,dso" may be more fitting for
465 kernel developers.
466 report.percent-limit
468 This one is mostly the same as call-graph.threshold but works for
469 histogram entries. Entries having an overhead lower than this
470 percentage will not be printed. Default is 0. If percent-limit is
471 10, only entries which have more than 10% of overhead will be
472 printed.
473 report.queue-size
475 This option sets up the maximum allocation size of the internal
476 event queue for ordering events. Default is 0, meaning no limit.
477 report.children
479 Children means functions called from another function. If this
480 option is true, perf report cumulates callchains of children and
481 show (accumulated) total overhead as well as Self overhead. Please
482 refer to the perf report manual. The default is true.
483 report.group
485 This option is to show event group information together. Example
486 output with this turned on, notice that there is one column per
487 event in the group, ref-cycles and cycles:
488 # group: {ref-cycles,cycles}
490 # ========
491 #
492 # Samples: 7K of event 'anon group { ref-cycles, cycles }'
493 # Event count (approx.): 6876107743
494 #
495 # Overhead Command Shared Object Symbol
496 # ................ ....... ................. ...................
497 #
498 99.84% 99.76% noploop noploop [.] main
499 0.07% 0.00% noploop ld-2.15.so [.] strcmp
500 0.03% 0.00% noploop [kernel.kallsyms] [k] timerqueue_del
501 top.*, top.children
503 Same as report.children. So if it is enabled, the output of top
504 command will have Children overhead column as well as Self overhead
505 column by default. The default is true.
506 top.call-graph
508 This is identical to call-graph.record-mode, except it is
509 applicable only for top subcommand. This option ONLY setup the
510 unwind method. To enable perf top to actually use it, the command
511 line option -g must be specified.
512 man.*, man.viewer
514 This option can assign a tool to view manual pages when help
515 subcommand was invoked. Supported tools are man, woman (with emacs
516 client) and konqueror. Default is man.
517 New man viewer tool can be also added using 'man.<tool>.cmd'
519 or use different path using 'man.<tool>.path' config option.
520 pager.*, pager.<subcommand>
522 When the subcommand is run on stdio, determine whether it uses
523 pager or not based on this value. Default is unspecified.
524 kmem.*, kmem.default
526 This option decides which allocator is to be analyzed if neither
527 --slab nor --page option is used. Default is slab.
528 record.*, record.build-id
530 This option can be cache, no-cache or skip. cache is to
531 post-process data and save/update the binaries into the build-id
532 cache (in ~/.debug). This is the default. But if this option is
533 no-cache, it will not update the build-id cache. skip skips
534 post-processing and does not update the cache.
535 record.call-graph
537 This is identical to call-graph.record-mode, except it is
538 applicable only for record subcommand. This option ONLY setup the
539 unwind method. To enable perf record to actually use it, the
540 command line option -g must be specified.
541 record.aio
543 Use n control blocks in asynchronous (Posix AIO) trace writing mode
544 (n default: 1, max: 4).
545 diff.*, diff.order
547 This option sets the number of columns to sort the result. The
548 default is 0, which means sorting by baseline. Setting it to 1 will
549 sort the result by delta (or other compute method selected).
550 diff.compute
552 This options sets the method for computing the diff result.
553 Possible values are delta, delta-abs, ratio and wdiff. Default is
554 delta.
555 trace.*, trace.add_events
557 Allows adding a set of events to add to the ones specified by the
558 user, or use as a default one if none was specified. The initial
559 use case is to add augmented_raw_syscalls.o to activate the perf
560 trace logic that looks for syscall pointer contents after the
561 normal tracepoint payload.
562 trace.args_alignment
564 Number of columns to align the argument list, default is 70, use 40
565 for the strace default, zero to no alignment.
566 trace.no_inherit
568 Do not follow children threads.
569 trace.show_arg_names
571 Should syscall argument names be printed? If not then
572 trace.show_zeros will be set.
573 trace.show_duration
575 Show syscall duration.
576 trace.show_prefix
578 If set to yes will show common string prefixes in tables. The
579 default is to remove the common prefix in things like "MAP_SHARED",
580 showing just "SHARED".
581 trace.show_timestamp
583 Show syscall start timestamp.
584 trace.show_zeros
586 Do not suppress syscall arguments that are equal to zero.
587 trace.tracepoint_beautifiers
589 Use "libtraceevent" to use that library to augment the tracepoint
590 arguments, "libbeauty", the default, to use the same argument
591 beautifiers used in the strace-like sys_enter+sys_exit lines.
592 ftrace.*, ftrace.tracer
594 Can be used to select the default tracer. Possible values are
595 function and function_graph.
596 llvm.*, llvm.clang-path
598 Path to clang. If omit, search it from $PATH.
599 llvm.clang-bpf-cmd-template
601 Cmdline template. Below lines show its default value. Environment
602 variable is used to pass options. "$CLANG_EXEC -DKERNEL
603 -DNR_CPUS=$NR_CPUS "\ "-DLINUX_VERSION_CODE=$LINUX_VERSION_CODE " \
604 "$CLANG_OPTIONS $PERF_BPF_INC_OPTIONS $KERNEL_INC_OPTIONS " \
605 "-Wno-unused-value -Wno-pointer-sign " \ "-working-directory
606 $WORKING_DIR " \ "-c \"$CLANG_SOURCE\" -target bpf $CLANG_EMIT_LLVM
607 -O2 -o - $LLVM_OPTIONS_PIPE"
608 llvm.clang-opt
610 Options passed to clang.
611 llvm.kbuild-dir
613 kbuild directory. If not set, use /lib/modules/uname -r/build. If
614 set to "" deliberately, skip kernel header auto-detector.
615 llvm.kbuild-opts
617 Options passed to make when detecting kernel header options.
618 llvm.dump-obj
620 Enable perf dump BPF object files compiled by LLVM.
621 llvm.opts
623 Options passed to llc.
624 samples.*, samples.context
626 Define how many ns worth of time to show around samples in perf
627 report sample context browser.
628 scripts.*
630 Any option defines a script that is added to the scripts menu in
631 the interactive perf browser and whose output is displayed. The
632 name of the option is the name, the value is a script command line.
633 The script gets the same options passed as a full perf script, in
634 particular -i perfdata file, --cpu, --tid
635 convert.*, convert.queue-size
637 Limit the size of ordered_events queue, so we could control
638 allocation size of perf data files without proper finished round
639 events.
640 intel-pt.*, intel-pt.cache-divisor, intel-pt.mispred-all
642 If set, Intel PT decoder will set the mispred flag on all branches.
643 auxtrace.*, auxtrace.dumpdir
645 s390 only. The directory to save the auxiliary trace buffer can be
646 changed using this option. Ex, auxtrace.dumpdir=/tmp. If the
647 directory does not exist or has the wrong file type, the current
648 directory is used.
649
651 perf(1)
652perf 04/23/2020 PERF-CONFIG(1)