tools/perf/Documentation/perf-config.txt

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