1perf-config(1)
2==============
3
4NAME
5----
6perf-config - Get and set variables in a configuration file.
7
8SYNOPSIS
9--------
10[verse]
11'perf config' [<file-option>] [section.name[=value] ...]
12or
13'perf config' [<file-option>] -l | --list
14
15DESCRIPTION
16-----------
17You can manage variables in a configuration file with this command.
18
19OPTIONS
20-------
21
22-l::
23--list::
24	Show current config variables, name and value, for all sections.
25
26--user::
27	For writing and reading options: write to user
28	'$HOME/.perfconfig' file or read it.
29
30--system::
31	For writing and reading options: write to system-wide
32	'$(sysconfdir)/perfconfig' or read it.
33
34CONFIGURATION FILE
35------------------
36
37The perf configuration file contains many variables to change various
38aspects of each of its tools, including output, disk usage, etc.
39The '$HOME/.perfconfig' file is used to store a per-user configuration.
40The file '$(sysconfdir)/perfconfig' can be used to
41store a system-wide default configuration.
42
43One an disable reading config files by setting the PERF_CONFIG environment
44variable to /dev/null, or provide an alternate config file by setting that
45variable.
46
47When reading or writing, the values are read from the system and user
48configuration files by default, and options '--system' and '--user'
49can be used to tell the command to read from or write to only that location.
50
51Syntax
52~~~~~~
53
54The file consist of sections. A section starts with its name
55surrounded by square brackets and continues till the next section
56begins. Each variable must be in a section, and have the form
57'name = value', for example:
58
59	[section]
60		name1 = value1
61		name2 = value2
62
63Section names are case sensitive and can contain any characters except
64newline (double quote `"` and backslash have to be escaped as `\"` and `\\`,
65respectively). Section headers can't span multiple lines.
66
67Example
68~~~~~~~
69
70Given 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 libslang
89		report = on
90		annotate = on
91		top = on
92
93	[buildid]
94		# Default, disable using /dev/null
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 or html
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	[llvm]
129		dump-obj = true
130		clang-opt = -g
131
132You can hide source code of annotate feature setting the config to false with
133
134	% perf config annotate.hide_src_code=true
135
136If you want to add or modify several config items, you can do like
137
138	% perf config ui.show-headers=false kmem.default=slab
139
140To modify the sort order of report functionality in user config file(i.e. `~/.perfconfig`), do
141
142	% perf config --user report.sort-order=srcline
143
144To change colors of selected line to other foreground and background colors
145in system config file (i.e. `$(sysconf)/perfconfig`), do
146
147	% perf config --system colors.selected=yellow,green
148
149To query the record mode of call graph, do
150
151	% perf config call-graph.record-mode
152
153If you want to know multiple config key/value pairs, you can do like
154
155	% perf config report.queue-size call-graph.order report.children
156
157To query the config value of sort order of call graph in user config file (i.e. `~/.perfconfig`), do
158
159	% perf config --user call-graph.sort-order
160
161To query the config value of buildid directory in system config file (i.e. `$(sysconf)/perfconfig`), do
162
163	% perf config --system buildid.dir
164
165Variables
166~~~~~~~~~
167
168colors.*::
169	The variables for customizing the colors used in the output for the
170	'report', 'top' and 'annotate' in the TUI. They should specify the
171	foreground and background colors, separated by a comma, for example:
172
173		medium = green, lightgray
174
175	If you want to use the color configured for you terminal, just leave it
176	as 'default', for example:
177
178		medium = default, lightgray
179
180	Available colors:
181	red, yellow, green, cyan, gray, black, blue,
182	white, default, magenta, lightgray
183
184	colors.top::
185		'top' means a overhead percentage which is more than 5%.
186		And values of this variable specify percentage colors.
187		Basic key values are foreground-color 'red' and
188		background-color 'default'.
189	colors.medium::
190		'medium' means a overhead percentage which has more than 0.5%.
191		Default values are 'green' and 'default'.
192	colors.normal::
193		'normal' means the rest of overhead percentages
194		except 'top', 'medium', 'selected'.
195		Default values are 'lightgray' and 'default'.
196	colors.selected::
197		This selects the colors for the current entry in a list of entries
198		from sub-commands (top, report, annotate).
199		Default values are 'black' and 'lightgray'.
200	colors.jump_arrows::
201		Colors for jump arrows on assembly code listings
202		such as 'jns', 'jmp', 'jane', etc.
203		Default values are 'blue', 'default'.
204	colors.addr::
205		This selects colors for addresses from 'annotate'.
206		Default values are 'magenta', 'default'.
207	colors.root::
208		Colors for headers in the output of a sub-commands (top, report).
209		Default values are 'white', 'blue'.
210
211core.*::
212	core.proc-map-timeout::
213		Sets a timeout (in milliseconds) for parsing /proc/<pid>/maps files.
214		Can be overridden by the --proc-map-timeout option on supported
215		subcommands. The default timeout is 500ms.
216
217tui.*, gtk.*::
218	Subcommands that can be configured here are 'top', 'report' and 'annotate'.
219	These values are booleans, for example:
220
221	[tui]
222		top = true
223
224	will make the TUI be the default for the 'top' subcommand. Those will be
225	available if the required libs were detected at tool build time.
226
227buildid.*::
228	buildid.dir::
229		Each executable and shared library in modern distributions comes with a
230		content based identifier that, if available, will be inserted in a
231		'perf.data' file header to, at analysis time find what is needed to do
232		symbol resolution, code annotation, etc.
233
234		The recording tools also stores a hard link or copy in a per-user
235		directory, $HOME/.debug/, of binaries, shared libraries, /proc/kallsyms
236		and /proc/kcore files to be used at analysis time.
237
238		The buildid.dir variable can be used to either change this directory
239		cache location, or to disable it altogether. If you want to disable it,
240		set buildid.dir to /dev/null. The default is $HOME/.debug
241
242buildid-cache.*::
243	buildid-cache.debuginfod=URLs
244		Specify debuginfod URLs to be used when retrieving perf.data binaries,
245		it follows the same syntax as the DEBUGINFOD_URLS variable, like:
246
247		  buildid-cache.debuginfod=http://192.168.122.174:8002
248
249annotate.*::
250	These are in control of addresses, jump function, source code
251	in lines of assembly code from a specific program.
252
253	annotate.disassembler_style:
254		Use this to change the default disassembler style to some other value
255		supported by binutils, such as "intel", see the '-M' option help in the
256		'objdump' man page.
257
258	annotate.hide_src_code::
259		If a program which is analyzed has source code,
260		this option lets 'annotate' print a list of assembly code with the source code.
261		For example, let's see a part of a program. There're four lines.
262		If this option is 'true', they can be printed
263		without source code from a program as below.
264
265		│        push   %rbp
266		│        mov    %rsp,%rbp
267		│        sub    $0x10,%rsp
268		│        mov    (%rdi),%rdx
269
270		But if this option is 'false', source code of the part
271		can be also printed as below. Default is 'false'.
272
273		│      struct rb_node *rb_next(const struct rb_node *node)
274		│      {
275		│        push   %rbp
276		│        mov    %rsp,%rbp
277		│        sub    $0x10,%rsp
278		│              struct rb_node *parent;
279280		│              if (RB_EMPTY_NODE(node))
281		│        mov    (%rdi),%rdx
282		│              return n;
283
284		This option works with tui, stdio2 browsers.
285
286        annotate.use_offset::
287		Basing on a first address of a loaded function, offset can be used.
288		Instead of using original addresses of assembly code,
289		addresses subtracted from a base address can be printed.
290		Let's illustrate an example.
291		If a base address is 0XFFFFFFFF81624d50 as below,
292
293		ffffffff81624d50 <load0>
294
295		an address on assembly code has a specific absolute address as below
296
297		ffffffff816250b8:│  mov    0x8(%r14),%rdi
298
299		but if use_offset is 'true', an address subtracted from a base address is printed.
300		Default is true. This option is only applied to TUI.
301
302		             368:│  mov    0x8(%r14),%rdi
303
304		This option works with tui, stdio2 browsers.
305
306	annotate.jump_arrows::
307		There can be jump instruction among assembly code.
308		Depending on a boolean value of jump_arrows,
309		arrows can be printed or not which represent
310		where do the instruction jump into as below.
311
312		│     ┌──jmp    1333
313		│     │  xchg   %ax,%ax
314		│1330:│  mov    %r15,%r10
315		│1333:└─→cmp    %r15,%r14
316
317		If jump_arrow is 'false', the arrows isn't printed as below.
318		Default is 'false'.
319
320		│      ↓ jmp    1333
321		│        xchg   %ax,%ax
322		│1330:   mov    %r15,%r10
323		│1333:   cmp    %r15,%r14
324
325		This option works with tui browser.
326
327        annotate.show_linenr::
328		When showing source code if this option is 'true',
329		line numbers are printed as below.
330
331		│1628         if (type & PERF_SAMPLE_IDENTIFIER) {
332		│     ↓ jne    508
333		│1628                 data->id = *array;
334		│1629                 array++;
335		│1630         }
336
337		However if this option is 'false', they aren't printed as below.
338		Default is 'false'.
339
340		│             if (type & PERF_SAMPLE_IDENTIFIER) {
341		│     ↓ jne    508
342		│                     data->id = *array;
343		│                     array++;
344		│             }
345
346		This option works with tui, stdio2 browsers.
347
348        annotate.show_nr_jumps::
349		Let's see a part of assembly code.
350
351		│1382:   movb   $0x1,-0x270(%rbp)
352
353		If use this, the number of branches jumping to that address can be printed as below.
354		Default is 'false'.
355
356		│1 1382:   movb   $0x1,-0x270(%rbp)
357
358		This option works with tui, stdio2 browsers.
359
360        annotate.show_total_period::
361		To compare two records on an instruction base, with this option
362		provided, display total number of samples that belong to a line
363		in assembly code. If this option is 'true', total periods are printed
364		instead of percent values as below.
365
366		  302 │      mov    %eax,%eax
367
368		But if this option is 'false', percent values for overhead are printed i.e.
369		Default is 'false'.
370
371		99.93 │      mov    %eax,%eax
372
373		This option works with tui, stdio2, stdio browsers.
374
375	annotate.show_nr_samples::
376		By default perf annotate shows percentage of samples. This option
377		can be used to print absolute number of samples. Ex, when set as
378		false:
379
380		Percent│
381		 74.03 │      mov    %fs:0x28,%rax
382
383		When set as true:
384
385		Samples│
386		     6 │      mov    %fs:0x28,%rax
387
388		This option works with tui, stdio2, stdio browsers.
389
390	annotate.offset_level::
391		Default is '1', meaning just jump targets will have offsets show right beside
392		the instruction. When set to '2' 'call' instructions will also have its offsets
393		shown, 3 or higher will show offsets for all instructions.
394
395		This option works with tui, stdio2 browsers.
396
397	annotate.demangle::
398		Demangle symbol names to human readable form. Default is 'true'.
399
400	annotate.demangle_kernel::
401		Demangle kernel symbol names to human readable form. Default is 'true'.
402
403hist.*::
404	hist.percentage::
405		This option control the way to calculate overhead of filtered entries -
406		that means the value of this option is effective only if there's a
407		filter (by comm, dso or symbol name). Suppose a following example:
408
409		       Overhead  Symbols
410		       ........  .......
411		        33.33%     foo
412		        33.33%     bar
413		        33.33%     baz
414
415	       This is an original overhead and we'll filter out the first 'foo'
416	       entry. The value of 'relative' would increase the overhead of 'bar'
417	       and 'baz' to 50.00% for each, while 'absolute' would show their
418	       current overhead (33.33%).
419
420ui.*::
421	ui.show-headers::
422		This option controls display of column headers (like 'Overhead' and 'Symbol')
423		in 'report' and 'top'. If this option is false, they are hidden.
424		This option is only applied to TUI.
425
426call-graph.*::
427	The following controls the handling of call-graphs (obtained via the
428	-g/--call-graph options).
429
430	call-graph.record-mode::
431		The mode for user space can be 'fp' (frame pointer), 'dwarf'
432		and 'lbr'.  The value 'dwarf' is effective only if libunwind
433		(or a recent version of libdw) is present on the system;
434		the value 'lbr' only works for certain cpus. The method for
435		kernel space is controlled not by this option but by the
436		kernel config (CONFIG_UNWINDER_*).
437
438	call-graph.dump-size::
439		The size of stack to dump in order to do post-unwinding. Default is 8192 (byte).
440		When using dwarf into record-mode, the default size will be used if omitted.
441
442	call-graph.print-type::
443		The print-types can be graph (graph absolute), fractal (graph relative),
444		flat and folded. This option controls a way to show overhead for each callchain
445		entry. Suppose a following example.
446
447                Overhead  Symbols
448                ........  .......
449                  40.00%  foo
450                          |
451                          ---foo
452                             |
453                             |--50.00%--bar
454                             |          main
455                             |
456                              --50.00%--baz
457                                        main
458
459		This output is a 'fractal' format. The 'foo' came from 'bar' and 'baz' exactly
460		half and half so 'fractal' shows 50.00% for each
461		(meaning that it assumes 100% total overhead of 'foo').
462
463		The 'graph' uses absolute overhead value of 'foo' as total so each of
464		'bar' and 'baz' callchain will have 20.00% of overhead.
465		If 'flat' is used, single column and linear exposure of call chains.
466		'folded' mean call chains are displayed in a line, separated by semicolons.
467
468	call-graph.order::
469		This option controls print order of callchains. The default is
470		'callee' which means callee is printed at top and then followed by its
471		caller and so on. The 'caller' prints it in reverse order.
472
473		If this option is not set and report.children or top.children is
474		set to true (or the equivalent command line option is given),
475		the default value of this option is changed to 'caller' for the
476		execution of 'perf report' or 'perf top'. Other commands will
477		still default to 'callee'.
478
479	call-graph.sort-key::
480		The callchains are merged if they contain same information.
481		The sort-key option determines a way to compare the callchains.
482		A value of 'sort-key' can be 'function' or 'address'.
483		The default is 'function'.
484
485	call-graph.threshold::
486		When there're many callchains it'd print tons of lines. So perf omits
487		small callchains under a certain overhead (threshold) and this option
488		control the threshold. Default is 0.5 (%). The overhead is calculated
489		by value depends on call-graph.print-type.
490
491	call-graph.print-limit::
492		This is a maximum number of lines of callchain printed for a single
493		histogram entry. Default is 0 which means no limitation.
494
495report.*::
496	report.sort_order::
497		Allows changing the default sort order from "comm,dso,symbol" to
498		some other default, for instance "sym,dso" may be more fitting for
499		kernel developers.
500	report.percent-limit::
501		This one is mostly the same as call-graph.threshold but works for
502		histogram entries. Entries having an overhead lower than this
503		percentage will not be printed. Default is '0'. If percent-limit
504		is '10', only entries which have more than 10% of overhead will be
505		printed.
506
507	report.queue-size::
508		This option sets up the maximum allocation size of the internal
509		event queue for ordering events. Default is 0, meaning no limit.
510
511	report.children::
512		'Children' means functions called from another function.
513		If this option is true, 'perf report' cumulates callchains of children
514		and show (accumulated) total overhead as well as 'Self' overhead.
515		Please refer to the 'perf report' manual. The default is 'true'.
516
517	report.group::
518		This option is to show event group information together.
519		Example output with this turned on, notice that there is one column
520		per event in the group, ref-cycles and cycles:
521
522		# group: {ref-cycles,cycles}
523		# ========
524		#
525		# Samples: 7K of event 'anon group { ref-cycles, cycles }'
526		# Event count (approx.): 6876107743
527		#
528		#         Overhead  Command      Shared Object               Symbol
529		# ................  .......  .................  ...................
530		#
531		    99.84%  99.76%  noploop  noploop            [.] main
532		     0.07%   0.00%  noploop  ld-2.15.so         [.] strcmp
533		     0.03%   0.00%  noploop  [kernel.kallsyms]  [k] timerqueue_del
534
535	report.skip-empty::
536		This option can change default stat behavior with empty results.
537		If it's set true, 'perf report --stat' will not show 0 stats.
538
539top.*::
540	top.children::
541		Same as 'report.children'. So if it is enabled, the output of 'top'
542		command will have 'Children' overhead column as well as 'Self' overhead
543		column by default.
544		The default is 'true'.
545
546	top.call-graph::
547		This is identical to 'call-graph.record-mode', except it is
548		applicable only for 'top' subcommand. This option ONLY setup
549		the unwind method. To enable 'perf top' to actually use it,
550		the command line option -g must be specified.
551
552man.*::
553	man.viewer::
554		This option can assign a tool to view manual pages when 'help'
555		subcommand was invoked. Supported tools are 'man', 'woman'
556		(with emacs client) and 'konqueror'. Default is 'man'.
557
558		New man viewer tool can be also added using 'man.<tool>.cmd'
559		or use different path using 'man.<tool>.path' config option.
560
561pager.*::
562	pager.<subcommand>::
563		When the subcommand is run on stdio, determine whether it uses
564		pager or not based on this value. Default is 'unspecified'.
565
566kmem.*::
567	kmem.default::
568		This option decides which allocator is to be analyzed if neither
569		'--slab' nor '--page' option is used. Default is 'slab'.
570
571record.*::
572	record.build-id::
573		This option can be 'cache', 'no-cache', 'skip' or 'mmap'.
574		'cache' is to post-process data and save/update the binaries into
575		the build-id cache (in ~/.debug). This is the default.
576		But if this option is 'no-cache', it will not update the build-id cache.
577		'skip' skips post-processing and does not update the cache.
578		'mmap' skips post-processing and reads build-ids from MMAP events.
579
580	record.call-graph::
581		This is identical to 'call-graph.record-mode', except it is
582		applicable only for 'record' subcommand. This option ONLY setup
583		the unwind method. To enable 'perf record' to actually use it,
584		the command line option -g must be specified.
585
586	record.aio::
587		Use 'n' control blocks in asynchronous (Posix AIO) trace writing
588		mode ('n' default: 1, max: 4).
589
590	record.debuginfod::
591		Specify debuginfod URL to be used when cacheing perf.data binaries,
592		it follows the same syntax as the DEBUGINFOD_URLS variable, like:
593
594		  http://192.168.122.174:8002
595
596		If the URLs is 'system', the value of DEBUGINFOD_URLS system environment
597		variable is used.
598
599diff.*::
600	diff.order::
601		This option sets the number of columns to sort the result.
602		The default is 0, which means sorting by baseline.
603		Setting it to 1 will sort the result by delta (or other
604		compute method selected).
605
606	diff.compute::
607		This options sets the method for computing the diff result.
608		Possible values are 'delta', 'delta-abs', 'ratio' and
609		'wdiff'.  Default is 'delta'.
610
611trace.*::
612	trace.add_events::
613		Allows adding a set of events to add to the ones specified
614		by the user, or use as a default one if none was specified.
615		The initial use case is to add augmented_raw_syscalls.o to
616		activate the 'perf trace' logic that looks for syscall
617		pointer contents after the normal tracepoint payload.
618
619	trace.args_alignment::
620		Number of columns to align the argument list, default is 70,
621		use 40 for the strace default, zero to no alignment.
622
623	trace.no_inherit::
624		Do not follow children threads.
625
626	trace.show_arg_names::
627		Should syscall argument names be printed? If not then trace.show_zeros
628		will be set.
629
630	trace.show_duration::
631		Show syscall duration.
632
633	trace.show_prefix::
634		If set to 'yes' will show common string prefixes in tables. The default
635		is to remove the common prefix in things like "MAP_SHARED", showing just "SHARED".
636
637	trace.show_timestamp::
638		Show syscall start timestamp.
639
640	trace.show_zeros::
641		Do not suppress syscall arguments that are equal to zero.
642
643	trace.tracepoint_beautifiers::
644		Use "libtraceevent" to use that library to augment the tracepoint arguments,
645		"libbeauty", the default, to use the same argument beautifiers used in the
646		strace-like sys_enter+sys_exit lines.
647
648ftrace.*::
649	ftrace.tracer::
650		Can be used to select the default tracer when neither -G nor
651		-F option is not specified. Possible values are 'function' and
652		'function_graph'.
653
654llvm.*::
655	llvm.clang-path::
656		Path to clang. If omit, search it from $PATH.
657
658	llvm.clang-bpf-cmd-template::
659		Cmdline template. Below lines show its default value. Environment
660		variable is used to pass options.
661		"$CLANG_EXEC -D__KERNEL__ -D__NR_CPUS__=$NR_CPUS "\
662		"-DLINUX_VERSION_CODE=$LINUX_VERSION_CODE "	\
663		"$CLANG_OPTIONS $PERF_BPF_INC_OPTIONS $KERNEL_INC_OPTIONS " \
664		"-Wno-unused-value -Wno-pointer-sign "		\
665		"-working-directory $WORKING_DIR "		\
666		"-c \"$CLANG_SOURCE\" -target bpf $CLANG_EMIT_LLVM -O2 -o - $LLVM_OPTIONS_PIPE"
667
668	llvm.clang-opt::
669		Options passed to clang.
670
671	llvm.kbuild-dir::
672		kbuild directory. If not set, use /lib/modules/`uname -r`/build.
673		If set to "" deliberately, skip kernel header auto-detector.
674
675	llvm.kbuild-opts::
676		Options passed to 'make' when detecting kernel header options.
677
678	llvm.dump-obj::
679		Enable perf dump BPF object files compiled by LLVM.
680
681	llvm.opts::
682		Options passed to llc.
683
684samples.*::
685
686	samples.context::
687		Define how many ns worth of time to show
688		around samples in perf report sample context browser.
689
690scripts.*::
691
692	Any option defines a script that is added to the scripts menu
693	in the interactive perf browser and whose output is displayed.
694	The name of the option is the name, the value is a script command line.
695	The script gets the same options passed as a full perf script,
696	in particular -i perfdata file, --cpu, --tid
697
698convert.*::
699
700	convert.queue-size::
701		Limit the size of ordered_events queue, so we could control
702		allocation size of perf data files without proper finished
703		round events.
704stat.*::
705
706	stat.big-num::
707		(boolean) Change the default for "--big-num". To make
708		"--no-big-num" the default, set "stat.big-num=false".
709
710intel-pt.*::
711
712	intel-pt.cache-divisor::
713
714	intel-pt.mispred-all::
715		If set, Intel PT decoder will set the mispred flag on all
716		branches.
717
718	intel-pt.max-loops::
719		If set and non-zero, the maximum number of unconditional
720		branches decoded without consuming any trace packets. If
721		the maximum is exceeded there will be a "Never-ending loop"
722		error. The default is 100000.
723
724auxtrace.*::
725
726	auxtrace.dumpdir::
727		s390 only. The directory to save the auxiliary trace buffer
728		can be changed using this option. Ex, auxtrace.dumpdir=/tmp.
729		If the directory does not exist or has the wrong file type,
730		the current directory is used.
731
732daemon.*::
733
734	daemon.base::
735		Base path for daemon data. All sessions data are stored under
736		this path.
737
738session-<NAME>.*::
739
740	session-<NAME>.run::
741
742		Defines new record session for daemon. The value is record's
743		command line without the 'record' keyword.
744
745
746SEE ALSO
747--------
748linkperf:perf[1]
749