1 perf-config(1)
2 ==============
3
4 NAME
5 ----
6 perf-config - Get and set variables in a confi
7
8 SYNOPSIS
9 --------
10 [verse]
11 'perf config' [<file-option>] [section.name[=v
12 or
13 'perf config' [<file-option>] -l | --list
14
15 DESCRIPTION
16 -----------
17 You can manage variables in a configuration fi
18
19 OPTIONS
20 -------
21
22 -l::
23 --list::
24 Show current config variables, name an
25
26 --user::
27 For writing and reading options: write
28 '$HOME/.perfconfig' file or read it.
29
30 --system::
31 For writing and reading options: write
32 '$(sysconfdir)/perfconfig' or read it.
33
34 CONFIGURATION FILE
35 ------------------
36
37 The perf configuration file contains many vari
38 aspects of each of its tools, including output
39 The '$HOME/.perfconfig' file is used to store
40 The file '$(sysconfdir)/perfconfig' can be use
41 store a system-wide default configuration.
42
43 One an disable reading config files by setting
44 variable to /dev/null, or provide an alternate
45 variable.
46
47 When reading or writing, the values are read f
48 configuration files by default, and options '-
49 can be used to tell the command to read from o
50
51 Syntax
52 ~~~~~~
53
54 The file consist of sections. A section starts
55 surrounded by square brackets and continues ti
56 begins. Each variable must be in a section, an
57 'name = value', for example:
58
59 [section]
60 name1 = value1
61 name2 = value2
62
63 Section names are case sensitive and can conta
64 newline (double quote `"` and backslash have t
65 respectively). Section headers can't span mult
66
67 Example
68 ~~~~~~~
69
70 Given a $HOME/.perfconfig like this:
71
72 #
73 # This is the config file, and
74 # a '#' and ';' character indicates a comment
75 #
76
77 [colors]
78 # Color variables
79 top = red, default
80 medium = green, default
81 normal = lightgray, default
82 selected = white, lightgray
83 jump_arrows = blue, default
84 addr = magenta, default
85 root = white, blue
86
87 [tui]
88 # Defaults if linked with libs
89 report = on
90 annotate = on
91 top = on
92
93 [buildid]
94 # Default, disable using /dev/
95 dir = ~/.debug
96
97 [annotate]
98 # Defaults
99 hide_src_code = false
100 use_offset = true
101 jump_arrows = true
102 show_nr_jumps = false
103
104 [help]
105 # Format can be man, info, web
106 format = man
107 autocorrect = 0
108
109 [ui]
110 show-headers = true
111
112 [call-graph]
113 # fp (framepointer), dwarf
114 record-mode = fp
115 print-type = graph
116 order = caller
117 sort-key = function
118
119 [report]
120 # Defaults
121 sort_order = comm,dso,symbol
122 percent-limit = 0
123 queue-size = 0
124 children = true
125 group = true
126 skip-empty = true
127
128
129 You can hide source code of annotate feature s
130
131 % perf config annotate.hide_src_code=t
132
133 If you want to add or modify several config it
134
135 % perf config ui.show-headers=false km
136
137 To modify the sort order of report functionali
138
139 % perf config --user report.sort-order
140
141 To change colors of selected line to other for
142 in system config file (i.e. `$(sysconf)/perfco
143
144 % perf config --system colors.selected
145
146 To query the record mode of call graph, do
147
148 % perf config call-graph.record-mode
149
150 If you want to know multiple config key/value
151
152 % perf config report.queue-size call-g
153
154 To query the config value of sort order of cal
155
156 % perf config --user call-graph.sort-o
157
158 To query the config value of buildid directory
159
160 % perf config --system buildid.dir
161
162 Variables
163 ~~~~~~~~~
164
165 colors.*::
166 The variables for customizing the colo
167 'report', 'top' and 'annotate' in the
168 foreground and background colors, sepa
169
170 medium = green, lightgray
171
172 If you want to use the color configure
173 as 'default', for example:
174
175 medium = default, lightgray
176
177 Available colors:
178 red, yellow, green, cyan, gray, black,
179 white, default, magenta, lightgray
180
181 colors.top::
182 'top' means a overhead percent
183 And values of this variable sp
184 Basic key values are foregroun
185 background-color 'default'.
186 colors.medium::
187 'medium' means a overhead perc
188 Default values are 'green' and
189 colors.normal::
190 'normal' means the rest of ove
191 except 'top', 'medium', 'selec
192 Default values are 'lightgray'
193 colors.selected::
194 This selects the colors for th
195 from sub-commands (top, report
196 Default values are 'black' and
197 colors.jump_arrows::
198 Colors for jump arrows on asse
199 such as 'jns', 'jmp', 'jane',
200 Default values are 'blue', 'de
201 colors.addr::
202 This selects colors for addres
203 Default values are 'magenta',
204 colors.root::
205 Colors for headers in the outp
206 Default values are 'white', 'b
207
208 core.*::
209 core.proc-map-timeout::
210 Sets a timeout (in millisecond
211 Can be overridden by the --pro
212 subcommands. The default timeo
213
214 tui.*, gtk.*::
215 Subcommands that can be configured her
216 These values are booleans, for example
217
218 [tui]
219 top = true
220
221 will make the TUI be the default for t
222 available if the required libs were de
223
224 buildid.*::
225 buildid.dir::
226 Each executable and shared lib
227 content based identifier that,
228 'perf.data' file header to, at
229 symbol resolution, code annota
230
231 The recording tools also store
232 directory, $HOME/.debug/, of b
233 and /proc/kcore files to be us
234
235 The buildid.dir variable can b
236 cache location, or to disable
237 set buildid.dir to /dev/null.
238
239 buildid-cache.*::
240 buildid-cache.debuginfod=URLs
241 Specify debuginfod URLs to be
242 it follows the same syntax as
243
244 buildid-cache.debuginfod=htt
245
246 annotate.*::
247 These are in control of addresses, jum
248 in lines of assembly code from a speci
249
250 annotate.addr2line::
251 addr2line binary to use for fi
252
253 annotate.objdump::
254 objdump binary to use for disa
255 including in the 'perf test' c
256
257 annotate.disassembler_style::
258 Use this to change the default
259 supported by binutils, such as
260 'objdump' man page.
261
262 annotate.hide_src_code::
263 If a program which is analyzed
264 this option lets 'annotate' pr
265 For example, let's see a part
266 If this option is 'true', they
267 without source code from a pro
268
269 │ push %rbp
270 │ mov %rsp,%rbp
271 │ sub $0x10,%rsp
272 │ mov (%rdi),%rdx
273
274 But if this option is 'false',
275 can be also printed as below.
276
277 │ struct rb_node *rb_ne
278 │ {
279 │ push %rbp
280 │ mov %rsp,%rbp
281 │ sub $0x10,%rsp
282 │ struct rb_nod
283 │
284 │ if (RB_EMPTY_
285 │ mov (%rdi),%rdx
286 │ return n;
287
288 This option works with tui, st
289
290 annotate.use_offset::
291 Basing on a first address of a
292 Instead of using original addr
293 addresses subtracted from a ba
294 Let's illustrate an example.
295 If a base address is 0XFFFFFFF
296
297 ffffffff81624d50 <load0>
298
299 an address on assembly code ha
300
301 ffffffff816250b8:│ mov 0
302
303 but if use_offset is 'true', a
304 Default is true. This option i
305
306 368:│ mov 0
307
308 This option works with tui, st
309
310 annotate.jump_arrows::
311 There can be jump instruction
312 Depending on a boolean value o
313 arrows can be printed or not w
314 where do the instruction jump
315
316 │ ┌──jmp 1333
317 │ │ xchg %ax,%ax
318 │1330:│ mov %r15,%r10
319 │1333:└─→cmp %r15,%
320
321 If jump_arrow is 'false', the
322 Default is 'false'.
323
324 │ ↓ jmp 1333
325 │ xchg %ax,%ax
326 │1330: mov %r15,%r10
327 │1333: cmp %r15,%r14
328
329 This option works with tui bro
330
331 annotate.show_linenr::
332 When showing source code if th
333 line numbers are printed as be
334
335 │1628 if (type & PER
336 │ ↓ jne 508
337 │1628 data->
338 │1629 array+
339 │1630 }
340
341 However if this option is 'fal
342 Default is 'false'.
343
344 │ if (type & PER
345 │ ↓ jne 508
346 │ data->
347 │ array+
348 │ }
349
350 This option works with tui, st
351
352 annotate.show_nr_jumps::
353 Let's see a part of assembly c
354
355 │1382: movb $0x1,-0x270(
356
357 If use this, the number of bra
358 Default is 'false'.
359
360 │1 1382: movb $0x1,-0x27
361
362 This option works with tui, st
363
364 annotate.show_total_period::
365 To compare two records on an i
366 provided, display total number
367 in assembly code. If this opti
368 instead of percent values as b
369
370 302 │ mov %eax,%ea
371
372 But if this option is 'false',
373 Default is 'false'.
374
375 99.93 │ mov %eax,%ea
376
377 This option works with tui, st
378
379 annotate.show_nr_samples::
380 By default perf annotate shows
381 can be used to print absolute
382 false:
383
384 Percent│
385 74.03 │ mov %fs:0x2
386
387 When set as true:
388
389 Samples│
390 6 │ mov %fs:0x2
391
392 This option works with tui, st
393
394 annotate.offset_level::
395 Default is '1', meaning just j
396 the instruction. When set to '
397 shown, 3 or higher will show o
398
399 This option works with tui, st
400
401 annotate.demangle::
402 Demangle symbol names to human
403
404 annotate.demangle_kernel::
405 Demangle kernel symbol names t
406
407 hist.*::
408 hist.percentage::
409 This option control the way to
410 that means the value of this o
411 filter (by comm, dso or symbol
412
413 Overhead Symbols
414 ........ .......
415 33.33% foo
416 33.33% bar
417 33.33% baz
418
419 This is an original overhead an
420 entry. The value of 'relative'
421 and 'baz' to 50.00% for each, w
422 current overhead (33.33%).
423
424 ui.*::
425 ui.show-headers::
426 This option controls display o
427 in 'report' and 'top'. If this
428 This option is only applied to
429
430 call-graph.*::
431 The following controls the handling of
432 -g/--call-graph options).
433
434 call-graph.record-mode::
435 The mode for user space can be
436 and 'lbr'. The value 'dwarf'
437 (or a recent version of libdw)
438 the value 'lbr' only works for
439 kernel space is controlled not
440 kernel config (CONFIG_UNWINDER
441
442 call-graph.dump-size::
443 The size of stack to dump in o
444 When using dwarf into record-m
445
446 call-graph.print-type::
447 The print-types can be graph (
448 flat and folded. This option c
449 entry. Suppose a following exa
450
451 Overhead Symbols
452 ........ .......
453 40.00% foo
454 |
455 ---foo
456 |
457 |--50.00%--bar
458 | main
459 |
460 --50.00%--baz
461 main
462
463 This output is a 'fractal' for
464 half and half so 'fractal' sho
465 (meaning that it assumes 100%
466
467 The 'graph' uses absolute over
468 'bar' and 'baz' callchain will
469 If 'flat' is used, single colu
470 'folded' mean call chains are
471
472 call-graph.order::
473 This option controls print ord
474 'callee' which means callee is
475 caller and so on. The 'caller'
476
477 If this option is not set and
478 set to true (or the equivalent
479 the default value of this opti
480 execution of 'perf report' or
481 still default to 'callee'.
482
483 call-graph.sort-key::
484 The callchains are merged if t
485 The sort-key option determines
486 A value of 'sort-key' can be '
487 The default is 'function'.
488
489 call-graph.threshold::
490 When there're many callchains
491 small callchains under a certa
492 control the threshold. Default
493 by value depends on call-graph
494
495 call-graph.print-limit::
496 This is a maximum number of li
497 histogram entry. Default is 0
498
499 report.*::
500 report.sort_order::
501 Allows changing the default so
502 some other default, for instan
503 kernel developers.
504 report.percent-limit::
505 This one is mostly the same as
506 histogram entries. Entries hav
507 percentage will not be printed
508 is '10', only entries which ha
509 printed.
510
511 report.queue-size::
512 This option sets up the maximu
513 event queue for ordering event
514
515 report.children::
516 'Children' means functions cal
517 If this option is true, 'perf
518 and show (accumulated) total o
519 Please refer to the 'perf repo
520
521 report.group::
522 This option is to show event g
523 Example output with this turne
524 per event in the group, ref-cy
525
526 # group: {ref-cycles,cycles}
527 # ========
528 #
529 # Samples: 7K of event 'anon g
530 # Event count (approx.): 68761
531 #
532 # Overhead Command
533 # ................ ....... .
534 #
535 99.84% 99.76% noploop n
536 0.07% 0.00% noploop l
537 0.03% 0.00% noploop [
538
539 report.skip-empty::
540 This option can change default
541 If it's set true, 'perf report
542
543 top.*::
544 top.children::
545 Same as 'report.children'. So
546 command will have 'Children' o
547 column by default.
548 The default is 'true'.
549
550 top.call-graph::
551 This is identical to 'call-gra
552 applicable only for 'top' subc
553 the unwind method. To enable '
554 the command line option -g mus
555
556 man.*::
557 man.viewer::
558 This option can assign a tool
559 subcommand was invoked. Suppor
560 (with emacs client) and 'konqu
561
562 New man viewer tool can be als
563 or use different path using 'm
564
565 pager.*::
566 pager.<subcommand>::
567 When the subcommand is run on
568 pager or not based on this val
569
570 kmem.*::
571 kmem.default::
572 This option decides which allo
573 '--slab' nor '--page' option i
574
575 record.*::
576 record.build-id::
577 This option can be 'cache', 'n
578 'cache' is to post-process dat
579 the build-id cache (in ~/.debu
580 But if this option is 'no-cach
581 'skip' skips post-processing a
582 'mmap' skips post-processing a
583
584 record.call-graph::
585 This is identical to 'call-gra
586 applicable only for 'record' s
587 the unwind method. To enable '
588 the command line option -g mus
589
590 record.aio::
591 Use 'n' control blocks in asyn
592 mode ('n' default: 1, max: 4).
593
594 record.debuginfod::
595 Specify debuginfod URL to be u
596 it follows the same syntax as
597
598 http://192.168.122.174:8002
599
600 If the URLs is 'system', the v
601 variable is used.
602
603 diff.*::
604 diff.order::
605 This option sets the number of
606 The default is 0, which means
607 Setting it to 1 will sort the
608 compute method selected).
609
610 diff.compute::
611 This options sets the method f
612 Possible values are 'delta', '
613 'wdiff'. Default is 'delta'.
614
615 trace.*::
616 trace.add_events::
617 Allows adding a set of events
618 by the user, or use as a defau
619 The initial use case is to add
620 activate the 'perf trace' logi
621 pointer contents after the nor
622
623 trace.args_alignment::
624 Number of columns to align the
625 use 40 for the strace default,
626
627 trace.no_inherit::
628 Do not follow children threads
629
630 trace.show_arg_names::
631 Should syscall argument names
632 will be set.
633
634 trace.show_duration::
635 Show syscall duration.
636
637 trace.show_prefix::
638 If set to 'yes' will show comm
639 is to remove the common prefix
640
641 trace.show_timestamp::
642 Show syscall start timestamp.
643
644 trace.show_zeros::
645 Do not suppress syscall argume
646
647 trace.tracepoint_beautifiers::
648 Use "libtraceevent" to use tha
649 "libbeauty", the default, to u
650 strace-like sys_enter+sys_exit
651
652 ftrace.*::
653 ftrace.tracer::
654 Can be used to select the defa
655 -F option is not specified. Po
656 'function_graph'.
657
658 samples.*::
659
660 samples.context::
661 Define how many ns worth of ti
662 around samples in perf report
663
664 scripts.*::
665
666 Any option defines a script that is ad
667 in the interactive perf browser and wh
668 The name of the option is the name, th
669 The script gets the same options passe
670 in particular -i perfdata file, --cpu,
671
672 convert.*::
673
674 convert.queue-size::
675 Limit the size of ordered_even
676 allocation size of perf data f
677 round events.
678 stat.*::
679
680 stat.big-num::
681 (boolean) Change the default f
682 "--no-big-num" the default, se
683
684 intel-pt.*::
685
686 intel-pt.cache-divisor::
687
688 intel-pt.mispred-all::
689 If set, Intel PT decoder will
690 branches.
691
692 intel-pt.max-loops::
693 If set and non-zero, the maxim
694 branches decoded without consu
695 the maximum is exceeded there
696 error. The default is 100000.
697
698 auxtrace.*::
699
700 auxtrace.dumpdir::
701 s390 only. The directory to sa
702 can be changed using this opti
703 If the directory does not exis
704 the current directory is used.
705
706 itrace.*::
707
708 debug-log-buffer-size::
709 Log size in bytes to output wh
710 Refer 'itrace' option of linkp
711 linkperf:perf-report[1]. The d
712
713 daemon.*::
714
715 daemon.base::
716 Base path for daemon data. All
717 this path.
718
719 session-<NAME>.*::
720
721 session-<NAME>.run::
722
723 Defines new record session for
724 command line without the 'reco
725
726 SEE ALSO
727 --------
728 linkperf:perf[1]
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.