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.addr2line::
254		addr2line binary to use for file names and line numbers.
255
256	annotate.objdump::
257		objdump binary to use for disassembly and annotations.
258
259	annotate.disassembler_style::
260		Use this to change the default disassembler style to some other value
261		supported by binutils, such as "intel", see the '-M' option help in the
262		'objdump' man page.
263
264	annotate.hide_src_code::
265		If a program which is analyzed has source code,
266		this option lets 'annotate' print a list of assembly code with the source code.
267		For example, let's see a part of a program. There're four lines.
268		If this option is 'true', they can be printed
269		without source code from a program as below.
270
271		│        push   %rbp
272		│        mov    %rsp,%rbp
273		│        sub    $0x10,%rsp
274		│        mov    (%rdi),%rdx
275
276		But if this option is 'false', source code of the part
277		can be also printed as below. Default is 'false'.
278
279		│      struct rb_node *rb_next(const struct rb_node *node)
280		│      {
281		│        push   %rbp
282		│        mov    %rsp,%rbp
283		│        sub    $0x10,%rsp
284		│              struct rb_node *parent;
285286		│              if (RB_EMPTY_NODE(node))
287		│        mov    (%rdi),%rdx
288		│              return n;
289
290		This option works with tui, stdio2 browsers.
291
292        annotate.use_offset::
293		Basing on a first address of a loaded function, offset can be used.
294		Instead of using original addresses of assembly code,
295		addresses subtracted from a base address can be printed.
296		Let's illustrate an example.
297		If a base address is 0XFFFFFFFF81624d50 as below,
298
299		ffffffff81624d50 <load0>
300
301		an address on assembly code has a specific absolute address as below
302
303		ffffffff816250b8:│  mov    0x8(%r14),%rdi
304
305		but if use_offset is 'true', an address subtracted from a base address is printed.
306		Default is true. This option is only applied to TUI.
307
308		             368:│  mov    0x8(%r14),%rdi
309
310		This option works with tui, stdio2 browsers.
311
312	annotate.jump_arrows::
313		There can be jump instruction among assembly code.
314		Depending on a boolean value of jump_arrows,
315		arrows can be printed or not which represent
316		where do the instruction jump into as below.
317
318		│     ┌──jmp    1333
319		│     │  xchg   %ax,%ax
320		│1330:│  mov    %r15,%r10
321		│1333:└─→cmp    %r15,%r14
322
323		If jump_arrow is 'false', the arrows isn't printed as below.
324		Default is 'false'.
325
326		│      ↓ jmp    1333
327		│        xchg   %ax,%ax
328		│1330:   mov    %r15,%r10
329		│1333:   cmp    %r15,%r14
330
331		This option works with tui browser.
332
333        annotate.show_linenr::
334		When showing source code if this option is 'true',
335		line numbers are printed as below.
336
337		│1628         if (type & PERF_SAMPLE_IDENTIFIER) {
338		│     ↓ jne    508
339		│1628                 data->id = *array;
340		│1629                 array++;
341		│1630         }
342
343		However if this option is 'false', they aren't printed as below.
344		Default is 'false'.
345
346		│             if (type & PERF_SAMPLE_IDENTIFIER) {
347		│     ↓ jne    508
348		│                     data->id = *array;
349		│                     array++;
350		│             }
351
352		This option works with tui, stdio2 browsers.
353
354        annotate.show_nr_jumps::
355		Let's see a part of assembly code.
356
357		│1382:   movb   $0x1,-0x270(%rbp)
358
359		If use this, the number of branches jumping to that address can be printed as below.
360		Default is 'false'.
361
362		│1 1382:   movb   $0x1,-0x270(%rbp)
363
364		This option works with tui, stdio2 browsers.
365
366        annotate.show_total_period::
367		To compare two records on an instruction base, with this option
368		provided, display total number of samples that belong to a line
369		in assembly code. If this option is 'true', total periods are printed
370		instead of percent values as below.
371
372		  302 │      mov    %eax,%eax
373
374		But if this option is 'false', percent values for overhead are printed i.e.
375		Default is 'false'.
376
377		99.93 │      mov    %eax,%eax
378
379		This option works with tui, stdio2, stdio browsers.
380
381	annotate.show_nr_samples::
382		By default perf annotate shows percentage of samples. This option
383		can be used to print absolute number of samples. Ex, when set as
384		false:
385
386		Percent│
387		 74.03 │      mov    %fs:0x28,%rax
388
389		When set as true:
390
391		Samples│
392		     6 │      mov    %fs:0x28,%rax
393
394		This option works with tui, stdio2, stdio browsers.
395
396	annotate.offset_level::
397		Default is '1', meaning just jump targets will have offsets show right beside
398		the instruction. When set to '2' 'call' instructions will also have its offsets
399		shown, 3 or higher will show offsets for all instructions.
400
401		This option works with tui, stdio2 browsers.
402
403	annotate.demangle::
404		Demangle symbol names to human readable form. Default is 'true'.
405
406	annotate.demangle_kernel::
407		Demangle kernel symbol names to human readable form. Default is 'true'.
408
409hist.*::
410	hist.percentage::
411		This option control the way to calculate overhead of filtered entries -
412		that means the value of this option is effective only if there's a
413		filter (by comm, dso or symbol name). Suppose a following example:
414
415		       Overhead  Symbols
416		       ........  .......
417		        33.33%     foo
418		        33.33%     bar
419		        33.33%     baz
420
421	       This is an original overhead and we'll filter out the first 'foo'
422	       entry. The value of 'relative' would increase the overhead of 'bar'
423	       and 'baz' to 50.00% for each, while 'absolute' would show their
424	       current overhead (33.33%).
425
426ui.*::
427	ui.show-headers::
428		This option controls display of column headers (like 'Overhead' and 'Symbol')
429		in 'report' and 'top'. If this option is false, they are hidden.
430		This option is only applied to TUI.
431
432call-graph.*::
433	The following controls the handling of call-graphs (obtained via the
434	-g/--call-graph options).
435
436	call-graph.record-mode::
437		The mode for user space can be 'fp' (frame pointer), 'dwarf'
438		and 'lbr'.  The value 'dwarf' is effective only if libunwind
439		(or a recent version of libdw) is present on the system;
440		the value 'lbr' only works for certain cpus. The method for
441		kernel space is controlled not by this option but by the
442		kernel config (CONFIG_UNWINDER_*).
443
444	call-graph.dump-size::
445		The size of stack to dump in order to do post-unwinding. Default is 8192 (byte).
446		When using dwarf into record-mode, the default size will be used if omitted.
447
448	call-graph.print-type::
449		The print-types can be graph (graph absolute), fractal (graph relative),
450		flat and folded. This option controls a way to show overhead for each callchain
451		entry. Suppose a following example.
452
453                Overhead  Symbols
454                ........  .......
455                  40.00%  foo
456                          |
457                          ---foo
458                             |
459                             |--50.00%--bar
460                             |          main
461                             |
462                              --50.00%--baz
463                                        main
464
465		This output is a 'fractal' format. The 'foo' came from 'bar' and 'baz' exactly
466		half and half so 'fractal' shows 50.00% for each
467		(meaning that it assumes 100% total overhead of 'foo').
468
469		The 'graph' uses absolute overhead value of 'foo' as total so each of
470		'bar' and 'baz' callchain will have 20.00% of overhead.
471		If 'flat' is used, single column and linear exposure of call chains.
472		'folded' mean call chains are displayed in a line, separated by semicolons.
473
474	call-graph.order::
475		This option controls print order of callchains. The default is
476		'callee' which means callee is printed at top and then followed by its
477		caller and so on. The 'caller' prints it in reverse order.
478
479		If this option is not set and report.children or top.children is
480		set to true (or the equivalent command line option is given),
481		the default value of this option is changed to 'caller' for the
482		execution of 'perf report' or 'perf top'. Other commands will
483		still default to 'callee'.
484
485	call-graph.sort-key::
486		The callchains are merged if they contain same information.
487		The sort-key option determines a way to compare the callchains.
488		A value of 'sort-key' can be 'function' or 'address'.
489		The default is 'function'.
490
491	call-graph.threshold::
492		When there're many callchains it'd print tons of lines. So perf omits
493		small callchains under a certain overhead (threshold) and this option
494		control the threshold. Default is 0.5 (%). The overhead is calculated
495		by value depends on call-graph.print-type.
496
497	call-graph.print-limit::
498		This is a maximum number of lines of callchain printed for a single
499		histogram entry. Default is 0 which means no limitation.
500
501report.*::
502	report.sort_order::
503		Allows changing the default sort order from "comm,dso,symbol" to
504		some other default, for instance "sym,dso" may be more fitting for
505		kernel developers.
506	report.percent-limit::
507		This one is mostly the same as call-graph.threshold but works for
508		histogram entries. Entries having an overhead lower than this
509		percentage will not be printed. Default is '0'. If percent-limit
510		is '10', only entries which have more than 10% of overhead will be
511		printed.
512
513	report.queue-size::
514		This option sets up the maximum allocation size of the internal
515		event queue for ordering events. Default is 0, meaning no limit.
516
517	report.children::
518		'Children' means functions called from another function.
519		If this option is true, 'perf report' cumulates callchains of children
520		and show (accumulated) total overhead as well as 'Self' overhead.
521		Please refer to the 'perf report' manual. The default is 'true'.
522
523	report.group::
524		This option is to show event group information together.
525		Example output with this turned on, notice that there is one column
526		per event in the group, ref-cycles and cycles:
527
528		# group: {ref-cycles,cycles}
529		# ========
530		#
531		# Samples: 7K of event 'anon group { ref-cycles, cycles }'
532		# Event count (approx.): 6876107743
533		#
534		#         Overhead  Command      Shared Object               Symbol
535		# ................  .......  .................  ...................
536		#
537		    99.84%  99.76%  noploop  noploop            [.] main
538		     0.07%   0.00%  noploop  ld-2.15.so         [.] strcmp
539		     0.03%   0.00%  noploop  [kernel.kallsyms]  [k] timerqueue_del
540
541	report.skip-empty::
542		This option can change default stat behavior with empty results.
543		If it's set true, 'perf report --stat' will not show 0 stats.
544
545top.*::
546	top.children::
547		Same as 'report.children'. So if it is enabled, the output of 'top'
548		command will have 'Children' overhead column as well as 'Self' overhead
549		column by default.
550		The default is 'true'.
551
552	top.call-graph::
553		This is identical to 'call-graph.record-mode', except it is
554		applicable only for 'top' subcommand. This option ONLY setup
555		the unwind method. To enable 'perf top' to actually use it,
556		the command line option -g must be specified.
557
558man.*::
559	man.viewer::
560		This option can assign a tool to view manual pages when 'help'
561		subcommand was invoked. Supported tools are 'man', 'woman'
562		(with emacs client) and 'konqueror'. Default is 'man'.
563
564		New man viewer tool can be also added using 'man.<tool>.cmd'
565		or use different path using 'man.<tool>.path' config option.
566
567pager.*::
568	pager.<subcommand>::
569		When the subcommand is run on stdio, determine whether it uses
570		pager or not based on this value. Default is 'unspecified'.
571
572kmem.*::
573	kmem.default::
574		This option decides which allocator is to be analyzed if neither
575		'--slab' nor '--page' option is used. Default is 'slab'.
576
577record.*::
578	record.build-id::
579		This option can be 'cache', 'no-cache', 'skip' or 'mmap'.
580		'cache' is to post-process data and save/update the binaries into
581		the build-id cache (in ~/.debug). This is the default.
582		But if this option is 'no-cache', it will not update the build-id cache.
583		'skip' skips post-processing and does not update the cache.
584		'mmap' skips post-processing and reads build-ids from MMAP events.
585
586	record.call-graph::
587		This is identical to 'call-graph.record-mode', except it is
588		applicable only for 'record' subcommand. This option ONLY setup
589		the unwind method. To enable 'perf record' to actually use it,
590		the command line option -g must be specified.
591
592	record.aio::
593		Use 'n' control blocks in asynchronous (Posix AIO) trace writing
594		mode ('n' default: 1, max: 4).
595
596	record.debuginfod::
597		Specify debuginfod URL to be used when cacheing perf.data binaries,
598		it follows the same syntax as the DEBUGINFOD_URLS variable, like:
599
600		  http://192.168.122.174:8002
601
602		If the URLs is 'system', the value of DEBUGINFOD_URLS system environment
603		variable is used.
604
605diff.*::
606	diff.order::
607		This option sets the number of columns to sort the result.
608		The default is 0, which means sorting by baseline.
609		Setting it to 1 will sort the result by delta (or other
610		compute method selected).
611
612	diff.compute::
613		This options sets the method for computing the diff result.
614		Possible values are 'delta', 'delta-abs', 'ratio' and
615		'wdiff'.  Default is 'delta'.
616
617trace.*::
618	trace.add_events::
619		Allows adding a set of events to add to the ones specified
620		by the user, or use as a default one if none was specified.
621		The initial use case is to add augmented_raw_syscalls.o to
622		activate the 'perf trace' logic that looks for syscall
623		pointer contents after the normal tracepoint payload.
624
625	trace.args_alignment::
626		Number of columns to align the argument list, default is 70,
627		use 40 for the strace default, zero to no alignment.
628
629	trace.no_inherit::
630		Do not follow children threads.
631
632	trace.show_arg_names::
633		Should syscall argument names be printed? If not then trace.show_zeros
634		will be set.
635
636	trace.show_duration::
637		Show syscall duration.
638
639	trace.show_prefix::
640		If set to 'yes' will show common string prefixes in tables. The default
641		is to remove the common prefix in things like "MAP_SHARED", showing just "SHARED".
642
643	trace.show_timestamp::
644		Show syscall start timestamp.
645
646	trace.show_zeros::
647		Do not suppress syscall arguments that are equal to zero.
648
649	trace.tracepoint_beautifiers::
650		Use "libtraceevent" to use that library to augment the tracepoint arguments,
651		"libbeauty", the default, to use the same argument beautifiers used in the
652		strace-like sys_enter+sys_exit lines.
653
654ftrace.*::
655	ftrace.tracer::
656		Can be used to select the default tracer when neither -G nor
657		-F option is not specified. Possible values are 'function' and
658		'function_graph'.
659
660llvm.*::
661	llvm.clang-path::
662		Path to clang. If omit, search it from $PATH.
663
664	llvm.clang-bpf-cmd-template::
665		Cmdline template. Below lines show its default value. Environment
666		variable is used to pass options.
667		"$CLANG_EXEC -D__KERNEL__ -D__NR_CPUS__=$NR_CPUS "\
668		"-DLINUX_VERSION_CODE=$LINUX_VERSION_CODE "	\
669		"$CLANG_OPTIONS $PERF_BPF_INC_OPTIONS $KERNEL_INC_OPTIONS " \
670		"-Wno-unused-value -Wno-pointer-sign "		\
671		"-working-directory $WORKING_DIR "		\
672		"-c \"$CLANG_SOURCE\" --target=bpf $CLANG_EMIT_LLVM -O2 -o - $LLVM_OPTIONS_PIPE"
673
674	llvm.clang-opt::
675		Options passed to clang.
676
677	llvm.kbuild-dir::
678		kbuild directory. If not set, use /lib/modules/`uname -r`/build.
679		If set to "" deliberately, skip kernel header auto-detector.
680
681	llvm.kbuild-opts::
682		Options passed to 'make' when detecting kernel header options.
683
684	llvm.dump-obj::
685		Enable perf dump BPF object files compiled by LLVM.
686
687	llvm.opts::
688		Options passed to llc.
689
690samples.*::
691
692	samples.context::
693		Define how many ns worth of time to show
694		around samples in perf report sample context browser.
695
696scripts.*::
697
698	Any option defines a script that is added to the scripts menu
699	in the interactive perf browser and whose output is displayed.
700	The name of the option is the name, the value is a script command line.
701	The script gets the same options passed as a full perf script,
702	in particular -i perfdata file, --cpu, --tid
703
704convert.*::
705
706	convert.queue-size::
707		Limit the size of ordered_events queue, so we could control
708		allocation size of perf data files without proper finished
709		round events.
710stat.*::
711
712	stat.big-num::
713		(boolean) Change the default for "--big-num". To make
714		"--no-big-num" the default, set "stat.big-num=false".
715
716intel-pt.*::
717
718	intel-pt.cache-divisor::
719
720	intel-pt.mispred-all::
721		If set, Intel PT decoder will set the mispred flag on all
722		branches.
723
724	intel-pt.max-loops::
725		If set and non-zero, the maximum number of unconditional
726		branches decoded without consuming any trace packets. If
727		the maximum is exceeded there will be a "Never-ending loop"
728		error. The default is 100000.
729
730auxtrace.*::
731
732	auxtrace.dumpdir::
733		s390 only. The directory to save the auxiliary trace buffer
734		can be changed using this option. Ex, auxtrace.dumpdir=/tmp.
735		If the directory does not exist or has the wrong file type,
736		the current directory is used.
737
738itrace.*::
739
740	debug-log-buffer-size::
741		Log size in bytes to output when using the option --itrace=d+e
742		Refer 'itrace' option of linkperf:perf-script[1] or
743		linkperf:perf-report[1]. The default is 16384.
744
745daemon.*::
746
747	daemon.base::
748		Base path for daemon data. All sessions data are stored under
749		this path.
750
751session-<NAME>.*::
752
753	session-<NAME>.run::
754
755		Defines new record session for daemon. The value is record's
756		command line without the 'record' keyword.
757
758
759SEE ALSO
760--------
761linkperf:perf[1]
762