1PERF-CONFIG(1) perf Manual PERF-CONFIG(1)
2
6 perf-config - Get and set variables in a configuration file.
7
9 perf config [<file-option>] [section.name[=value] ...]
10 or
11 perf config [<file-option>] -l | --list
12
14 You can manage variables in a configuration file with this command.
15
17 -l, --list
18 Show current config variables, name and value, for all sections.
19 --user
21 For writing and reading options: write to user $HOME/.perfconfig
22 file or read it.
23 --system
25 For writing and reading options: write to system-wide
26 $(sysconfdir)/perfconfig or read it.
27
29 The perf configuration file contains many variables to change various
30 aspects of each of its tools, including output, disk usage, etc. The
31 $HOME/.perfconfig file is used to store a per-user configuration. The
32 file $(sysconfdir)/perfconfig can be used to store a system-wide
33 default configuration.
34 When reading or writing, the values are read from the system and user
36 configuration files by default, and options --system and --user can be
37 used to tell the command to read from or write to only that location.
38 Syntax
40 The file consist of sections. A section starts with its name surrounded
41 by square brackets and continues till the next section begins. Each
42 variable must be in a section, and have the form name = value, for
43 example:
44 [section]
46 name1 = value1
47 name2 = value2
48 Section names are case sensitive and can contain any characters except
50 newline (double quote " and backslash have to be escaped as \" and \\,
51 respectively). Section headers can’t span multiple lines.
52 Example
54 Given a $HOME/.perfconfig like this:
55 # # This is the config file, and # a # and ; character indicates a
57 comment #
58 [colors]
60 # Color variables
61 top = red, default
62 medium = green, default
63 normal = lightgray, default
64 selected = white, lightgray
65 jump_arrows = blue, default
66 addr = magenta, default
67 root = white, blue
68 [tui]
70 # Defaults if linked with libslang
71 report = on
72 annotate = on
73 top = on
74 [buildid]
76 # Default, disable using /dev/null
77 dir = ~/.debug
78 [annotate]
80 # Defaults
81 hide_src_code = false
82 use_offset = true
83 jump_arrows = true
84 show_nr_jumps = false
85 [help]
87 # Format can be man, info, web or html
88 format = man
89 autocorrect = 0
90 [ui]
92 show-headers = true
93 [call-graph]
95 # fp (framepointer), dwarf
96 record-mode = fp
97 print-type = graph
98 order = caller
99 sort-key = function
100 [report]
102 # Defaults
103 sort_order = comm,dso,symbol
104 percent-limit = 0
105 queue-size = 0
106 children = true
107 group = true
108 [llvm]
110 dump-obj = true
111 clang-opt = -g
112 You can hide source code of annotate feature setting the config to
114 false with
115 % perf config annotate.hide_src_code=true
117 If you want to add or modify several config items, you can do like
119 % perf config ui.show-headers=false kmem.default=slab
121 To modify the sort order of report functionality in user config
123 file(i.e. ~/.perfconfig), do
124 % perf config --user report sort-order=srcline
126 To change colors of selected line to other foreground and background
128 colors in system config file (i.e. $(sysconf)/perfconfig), do
129 % perf config --system colors.selected=yellow,green
131 To query the record mode of call graph, do
133 % perf config call-graph.record-mode
135 If you want to know multiple config key/value pairs, you can do like
137 % perf config report.queue-size call-graph.order report.children
139 To query the config value of sort order of call graph in user config
141 file (i.e. ~/.perfconfig), do
142 % perf config --user call-graph.sort-order
144 To query the config value of buildid directory in system config file
146 (i.e. $(sysconf)/perfconfig), do
147 % perf config --system buildid.dir
149 Variables
151 colors.*
152 The variables for customizing the colors used in the output for the
153 report, top and annotate in the TUI. They should specify the
154 foreground and background colors, separated by a comma, for
155 example:
156 medium = green, lightgray
158 If you want to use the color configured for you terminal, just leave it
160 as 'default', for example:
161 medium = default, lightgray
163 Available colors:
165 red, yellow, green, cyan, gray, black, blue,
166 white, default, magenta, lightgray
167 colors.top
169 top means a overhead percentage which is more than 5%. And values
170 of this variable specify percentage colors. Basic key values are
171 foreground-color red and background-color default.
172 colors.medium
174 medium means a overhead percentage which has more than 0.5%.
175 Default values are green and default.
176 colors.normal
178 normal means the rest of overhead percentages except top, medium,
179 selected. Default values are lightgray and default.
180 colors.selected
182 This selects the colors for the current entry in a list of entries
183 from sub-commands (top, report, annotate). Default values are black
184 and lightgray.
185 colors.jump_arrows
187 Colors for jump arrows on assembly code listings such as jns, jmp,
188 jane, etc. Default values are blue, default.
189 colors.addr
191 This selects colors for addresses from annotate. Default values are
192 magenta, default.
193 colors.root
195 Colors for headers in the output of a sub-commands (top, report).
196 Default values are white, blue.
197 core.*, core.proc-map-timeout
199 Sets a timeout (in milliseconds) for parsing /proc/<pid>/maps
200 files. Can be overridden by the --proc-map-timeout option on
201 supported subcommands. The default timeout is 500ms.
202 tui., gtk.
204 Subcommands that can be configured here are top, report and
205 annotate. These values are booleans, for example:
206 [tui]
208 top = true
209 will make the TUI be the default for the 'top' subcommand. Those will be
211 available if the required libs were detected at tool build time.
212 buildid.*, buildid.dir
214 Each executable and shared library in modern distributions comes
215 with a content based identifier that, if available, will be
216 inserted in a perf.data file header to, at analysis time find what
217 is needed to do symbol resolution, code annotation, etc.
218 The recording tools also stores a hard link or copy in a per-user
220 directory, $HOME/.debug/, of binaries, shared libraries, /proc/kallsyms
221 and /proc/kcore files to be used at analysis time.
222 The buildid.dir variable can be used to either change this directory
224 cache location, or to disable it altogether. If you want to disable it,
225 set buildid.dir to /dev/null. The default is $HOME/.debug
226 annotate.*
228 These options work only for TUI. These are in control of addresses,
229 jump function, source code in lines of assembly code from a
230 specific program.
231 annotate.hide_src_code
233 If a program which is analyzed has source code, this option lets
234 annotate print a list of assembly code with the source code. For
235 example, let’s see a part of a program. There’re four lines. If
236 this option is true, they can be printed without source code from a
237 program as below.
238 │ push %rbp
240 │ mov %rsp,%rbp
241 │ sub $0x10,%rsp
242 │ mov (%rdi),%rdx
243 But if this option is 'false', source code of the part
245 can be also printed as below. Default is 'false'.
246 │ struct rb_node *rb_next(const struct rb_node *node)
248 │ {
249 │ push %rbp
250 │ mov %rsp,%rbp
251 │ sub $0x10,%rsp
252 │ struct rb_node *parent;
253 │
254 │ if (RB_EMPTY_NODE(node))
255 │ mov (%rdi),%rdx
256 │ return n;
257 annotate.use_offset
259 Basing on a first address of a loaded function, offset can be used.
260 Instead of using original addresses of assembly code, addresses
261 subtracted from a base address can be printed. Let’s illustrate an
262 example. If a base address is 0XFFFFFFFF81624d50 as below,
263 ffffffff81624d50 <load0>
265 an address on assembly code has a specific absolute address as below
267 ffffffff816250b8:│ mov 0x8(%r14),%rdi
269 but if use_offset is 'true', an address subtracted from a base address is printed.
271 Default is true. This option is only applied to TUI.
272 368:│ mov 0x8(%r14),%rdi
274 annotate.jump_arrows
276 There can be jump instruction among assembly code. Depending on a
277 boolean value of jump_arrows, arrows can be printed or not which
278 represent where do the instruction jump into as below.
279 │ ┌──jmp 1333
281 │ │ xchg %ax,%ax
282 │1330:│ mov %r15,%r10
283 │1333:└─→cmp %r15,%r14
284 If jump_arrow is 'false', the arrows isn't printed as below.
286 Default is 'false'.
287 │ ↓ jmp 1333
289 │ xchg %ax,%ax
290 │1330: mov %r15,%r10
291 │1333: cmp %r15,%r14
292 annotate.show_linenr
294 When showing source code if this option is true, line numbers are
295 printed as below.
296 │1628 if (type & PERF_SAMPLE_IDENTIFIER) {
298 │ ↓ jne 508
299 │1628 data->id = *array;
300 │1629 array++;
301 │1630 }
302 However if this option is 'false', they aren't printed as below.
304 Default is 'false'.
305 │ if (type & PERF_SAMPLE_IDENTIFIER) {
307 │ ↓ jne 508
308 │ data->id = *array;
309 │ array++;
310 │ }
311 annotate.show_nr_jumps
313 Let’s see a part of assembly code.
314 │1382: movb $0x1,-0x270(%rbp)
316 If use this, the number of branches jumping to that address can be printed as below.
318 Default is 'false'.
319 │1 1382: movb $0x1,-0x270(%rbp)
321 annotate.show_total_period
323 To compare two records on an instruction base, with this option
324 provided, display total number of samples that belong to a line in
325 assembly code. If this option is true, total periods are printed
326 instead of percent values as below.
327 302 │ mov %eax,%eax
329 But if this option is 'false', percent values for overhead are printed i.e.
331 Default is 'false'.
332 99.93 │ mov %eax,%eax
334 annotate.offset_level
336 Default is 1, meaning just jump targets will have offsets show
337 right beside the instruction. When set to 2 call instructions will
338 also have its offsets shown, 3 or higher will show offsets for all
339 instructions.
340 hist.*, hist.percentage
342 This option control the way to calculate overhead of filtered
343 entries - that means the value of this option is effective only if
344 there’s a filter (by comm, dso or symbol name). Suppose a following
345 example:
346 Overhead Symbols
348 ........ .......
349 33.33% foo
350 33.33% bar
351 33.33% baz
352 This is an original overhead and we'll filter out the first 'foo'
354 entry. The value of 'relative' would increase the overhead of 'bar'
355 and 'baz' to 50.00% for each, while 'absolute' would show their
356 current overhead (33.33%).
357 ui.*, ui.show-headers
359 This option controls display of column headers (like Overhead and
360 Symbol) in report and top. If this option is false, they are
361 hidden. This option is only applied to TUI.
362 call-graph.*
364 When sub-commands top and report work with -g/—-children there’re
365 options in control of call-graph.
366 call-graph.record-mode
368 The record-mode can be fp (frame pointer), dwarf and lbr. The value
369 of dwarf is effective only if perf detect needed library (libunwind
370 or a recent version of libdw). lbr only work for cpus that support
371 it.
372 call-graph.dump-size
374 The size of stack to dump in order to do post-unwinding. Default is
375 8192 (byte). When using dwarf into record-mode, the default size
376 will be used if omitted.
377 call-graph.print-type
379 The print-types can be graph (graph absolute), fractal (graph
380 relative), flat and folded. This option controls a way to show
381 overhead for each callchain entry. Suppose a following example.
382 Overhead Symbols
384 ........ .......
385 40.00% foo
386 |
387 ---foo
388 |
389 |--50.00%--bar
390 | main
391 |
392 --50.00%--baz
393 main
394 This output is a 'fractal' format. The 'foo' came from 'bar' and 'baz' exactly
396 half and half so 'fractal' shows 50.00% for each
397 (meaning that it assumes 100% total overhead of 'foo').
398 The 'graph' uses absolute overhead value of 'foo' as total so each of
400 'bar' and 'baz' callchain will have 20.00% of overhead.
401 If 'flat' is used, single column and linear exposure of call chains.
402 'folded' mean call chains are displayed in a line, separated by semicolons.
403 call-graph.order
405 This option controls print order of callchains. The default is
406 callee which means callee is printed at top and then followed by
407 its caller and so on. The caller prints it in reverse order.
408 If this option is not set and report.children or top.children is
410 set to true (or the equivalent command line option is given),
411 the default value of this option is changed to 'caller' for the
412 execution of 'perf report' or 'perf top'. Other commands will
413 still default to 'callee'.
414 call-graph.sort-key
416 The callchains are merged if they contain same information. The
417 sort-key option determines a way to compare the callchains. A value
418 of sort-key can be function or address. The default is function.
419 call-graph.threshold
421 When there’re many callchains it’d print tons of lines. So perf
422 omits small callchains under a certain overhead (threshold) and
423 this option control the threshold. Default is 0.5 (%). The overhead
424 is calculated by value depends on call-graph.print-type.
425 call-graph.print-limit
427 This is a maximum number of lines of callchain printed for a single
428 histogram entry. Default is 0 which means no limitation.
429 report.*, report.sort_order
431 Allows changing the default sort order from "comm,dso,symbol" to
432 some other default, for instance "sym,dso" may be more fitting for
433 kernel developers.
434 report.percent-limit
436 This one is mostly the same as call-graph.threshold but works for
437 histogram entries. Entries having an overhead lower than this
438 percentage will not be printed. Default is 0. If percent-limit is
439 10, only entries which have more than 10% of overhead will be
440 printed.
441 report.queue-size
443 This option sets up the maximum allocation size of the internal
444 event queue for ordering events. Default is 0, meaning no limit.
445 report.children
447 Children means functions called from another function. If this
448 option is true, perf report cumulates callchains of children and
449 show (accumulated) total overhead as well as Self overhead. Please
450 refer to the perf report manual. The default is true.
451 report.group
453 This option is to show event group information together. Example
454 output with this turned on, notice that there is one column per
455 event in the group, ref-cycles and cycles:
456 # group: {ref-cycles,cycles}
458 # ========
459 #
460 # Samples: 7K of event 'anon group { ref-cycles, cycles }'
461 # Event count (approx.): 6876107743
462 #
463 # Overhead Command Shared Object Symbol
464 # ................ ....... ................. ...................
465 #
466 99.84% 99.76% noploop noploop [.] main
467 0.07% 0.00% noploop ld-2.15.so [.] strcmp
468 0.03% 0.00% noploop [kernel.kallsyms] [k] timerqueue_del
469 top.*, top.children
471 Same as report.children. So if it is enabled, the output of top
472 command will have Children overhead column as well as Self overhead
473 column by default. The default is true.
474 man.*, man.viewer
476 This option can assign a tool to view manual pages when help
477 subcommand was invoked. Supported tools are man, woman (with emacs
478 client) and konqueror. Default is man.
479 New man viewer tool can be also added using 'man.<tool>.cmd'
481 or use different path using 'man.<tool>.path' config option.
482 pager.*, pager.<subcommand>
484 When the subcommand is run on stdio, determine whether it uses
485 pager or not based on this value. Default is unspecified.
486 kmem.*, kmem.default
488 This option decides which allocator is to be analyzed if neither
489 --slab nor --page option is used. Default is slab.
490 record.*, record.build-id
492 This option can be cache, no-cache or skip. cache is to
493 post-process data and save/update the binaries into the build-id
494 cache (in ~/.debug). This is the default. But if this option is
495 no-cache, it will not update the build-id cache. skip skips
496 post-processing and does not update the cache.
497 diff.*, diff.order
499 This option sets the number of columns to sort the result. The
500 default is 0, which means sorting by baseline. Setting it to 1 will
501 sort the result by delta (or other compute method selected).
502 diff.compute
504 This options sets the method for computing the diff result.
505 Possible values are delta, delta-abs, ratio and wdiff. Default is
506 delta.
507 trace.*, trace.add_events
509 Allows adding a set of events to add to the ones specified by the
510 user, or use as a default one if none was specified. The initial
511 use case is to add augmented_raw_syscalls.o to activate the perf
512 trace logic that looks for syscall pointer contents after the
513 normal tracepoint payload.
514 trace.args_alignment
516 Number of columns to align the argument list, default is 70, use 40
517 for the strace default, zero to no alignment.
518 trace.no_inherit
520 Do not follow children threads.
521 trace.show_arg_names
523 Should syscall argument names be printed? If not then
524 trace.show_zeros will be set.
525 trace.show_duration
527 Show syscall duration.
528 trace.show_prefix
530 If set to yes will show common string prefixes in tables. The
531 default is to remove the common prefix in things like "MAP_SHARED",
532 showing just "SHARED".
533 trace.show_timestamp
535 Show syscall start timestamp.
536 trace.show_zeros
538 Do not suppress syscall arguments that are equal to zero.
539 llvm.*, llvm.clang-path
541 Path to clang. If omit, search it from $PATH.
542 llvm.clang-bpf-cmd-template
544 Cmdline template. Below lines show its default value. Environment
545 variable is used to pass options. "$CLANG_EXEC -DKERNEL
546 $CLANG_OPTIONS $KERNEL_INC_OPTIONS \ -Wno-unused-value
547 -Wno-pointer-sign -working-directory \ $WORKING_DIR -c
548 $CLANG_SOURCE -target bpf -O2 -o -"
549 llvm.clang-opt
551 Options passed to clang.
552 llvm.kbuild-dir
554 kbuild directory. If not set, use /lib/modules/uname -r/build. If
555 set to "" deliberately, skip kernel header auto-detector.
556 llvm.kbuild-opts
558 Options passed to make when detecting kernel header options.
559 llvm.dump-obj
561 Enable perf dump BPF object files compiled by LLVM.
562 llvm.opts
564 Options passed to llc.
565 samples.*, samples.context
567 Define how many ns worth of time to show around samples in perf
568 report sample context browser.
569 scripts.*
571 Any option defines a script that is added to the scripts menu in
572 the interactive perf browser and whose output is displayed. The
573 name of the option is the name, the value is a script command line.
574 The script gets the same options passed as a full perf script, in
575 particular -i perfdata file, --cpu, --tid
576
578 perf(1)
579perf 06/03/2019 PERF-CONFIG(1)