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