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