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 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
684 perf(1)
685
686
687
688perf 11/28/2023 PERF-CONFIG(1)