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' -l | --list
  12
  13 DESCRIPTION
  14 -----------
  15 You can manage variables in a configuration file with this command.
  16
  17 OPTIONS
  18 -------
  19
  20 -l::
  21 --list::
  22         Show current config variables, name and value, for all sections.
  23
  24 CONFIGURATION FILE
  25 ------------------
  26
  27 The perf configuration file contains many variables to change various
  28 aspects of each of its tools, including output, disk usage, etc.
  29 The '$HOME/.perfconfig' file is used to store a per-user configuration.
  30 The file '$(sysconfdir)/perfconfig' can be used to
  31 store a system-wide default configuration.
  32
  33 Syntax
  34 ~~~~~~
  35
  36 The file consist of sections. A section starts with its name
  37 surrounded by square brackets and continues till the next section
  38 begins. Each variable must be in a section, and have the form
  39 'name = value', for example:
  40
  41         [section]
  42                 name1 = value1
  43                 name2 = value2
  44
  45 Section names are case sensitive and can contain any characters except
  46 newline (double quote `"` and backslash have to be escaped as `\"` and `\\`,
  47 respectively). Section headers can't span multiple lines.
  48
  49 Example
  50 ~~~~~~~
  51
  52 Given a $HOME/.perfconfig like this:
  53
  54 #
  55 # This is the config file, and
  56 # a '#' and ';' character indicates a comment
  57 #
  58
  59         [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
  69         [tui]
  70                 # Defaults if linked with libslang
  71                 report = on
  72                 annotate = on
  73                 top = on
  74
  75         [buildid]
  76                 # Default, disable using /dev/null
  77                 dir = ~/.debug
  78
  79         [annotate]
  80                 # Defaults
  81                 hide_src_code = false
  82                 use_offset = true
  83                 jump_arrows = true
  84                 show_nr_jumps = false
  85
  86         [help]
  87                 # Format can be man, info, web or html
  88                 format = man
  89                 autocorrect = 0
  90
  91         [ui]
  92                 show-headers = true
  93
  94         [call-graph]
  95                 # fp (framepointer), dwarf
  96                 record-mode = fp
  97                 print-type = graph
  98                 order = caller
  99                 sort-key = function
 100
 101 Variables
 102 ~~~~~~~~~
 103
 104 colors.*::
 105         The variables for customizing the colors used in the output for the
 106         'report', 'top' and 'annotate' in the TUI. They should specify the
 107         foreground and background colors, separated by a comma, for example:
 108
 109                 medium = green, lightgray
 110
 111         If you want to use the color configured for you terminal, just leave it
 112         as 'default', for example:
 113
 114                 medium = default, lightgray
 115
 116         Available colors:
 117         red, yellow, green, cyan, gray, black, blue,
 118         white, default, magenta, lightgray
 119
 120         colors.top::
 121                 'top' means a overhead percentage which is more than 5%.
 122                 And values of this variable specify percentage colors.
 123                 Basic key values are foreground-color 'red' and
 124                 background-color 'default'.
 125         colors.medium::
 126                 'medium' means a overhead percentage which has more than 0.5%.
 127                 Default values are 'green' and 'default'.
 128         colors.normal::
 129                 'normal' means the rest of overhead percentages
 130                 except 'top', 'medium', 'selected'.
 131                 Default values are 'lightgray' and 'default'.
 132         colors.selected::
 133                 This selects the colors for the current entry in a list of entries
 134                 from sub-commands (top, report, annotate).
 135                 Default values are 'black' and 'lightgray'.
 136         colors.jump_arrows::
 137                 Colors for jump arrows on assembly code listings
 138                 such as 'jns', 'jmp', 'jane', etc.
 139                 Default values are 'blue', 'default'.
 140         colors.addr::
 141                 This selects colors for addresses from 'annotate'.
 142                 Default values are 'magenta', 'default'.
 143         colors.root::
 144                 Colors for headers in the output of a sub-commands (top, report).
 145                 Default values are 'white', 'blue'.
 146
 147 tui.*, gtk.*::
 148         Subcommands that can be configured here are 'top', 'report' and 'annotate'.
 149         These values are booleans, for example:
 150
 151         [tui]
 152                 top = true
 153
 154         will make the TUI be the default for the 'top' subcommand. Those will be
 155         available if the required libs were detected at tool build time.
 156
 157 buildid.*::
 158         buildid.dir::
 159                 Each executable and shared library in modern distributions comes with a
 160                 content based identifier that, if available, will be inserted in a
 161                 'perf.data' file header to, at analysis time find what is needed to do
 162                 symbol resolution, code annotation, etc.
 163
 164                 The recording tools also stores a hard link or copy in a per-user
 165                 directory, $HOME/.debug/, of binaries, shared libraries, /proc/kallsyms
 166                 and /proc/kcore files to be used at analysis time.
 167
 168                 The buildid.dir variable can be used to either change this directory
 169                 cache location, or to disable it altogether. If you want to disable it,
 170                 set buildid.dir to /dev/null. The default is $HOME/.debug
 171
 172 annotate.*::
 173         These options work only for TUI.
 174         These are in control of addresses, jump function, source code
 175         in lines of assembly code from a specific program.
 176
 177         annotate.hide_src_code::
 178                 If a program which is analyzed has source code,
 179                 this option lets 'annotate' print a list of assembly code with the source code.
 180                 For example, let's see a part of a program. There're four lines.
 181                 If this option is 'true', they can be printed
 182                 without source code from a program as below.
 183
 184                 │        push   %rbp
 185                 │        mov    %rsp,%rbp
 186                 │        sub    $0x10,%rsp
 187                 │        mov    (%rdi),%rdx
 188
 189                 But if this option is 'false', source code of the part
 190                 can be also printed as below. Default is 'false'.
 191
 192                 │      struct rb_node *rb_next(const struct rb_node *node)
 193                 │      {
 194                 │        push   %rbp
 195                 │        mov    %rsp,%rbp
 196                 │        sub    $0x10,%rsp
 197                 │              struct rb_node *parent;
 198                 │
 199                 │              if (RB_EMPTY_NODE(node))
 200                 │        mov    (%rdi),%rdx
 201                 │              return n;
 202
 203         annotate.use_offset::
 204                 Basing on a first address of a loaded function, offset can be used.
 205                 Instead of using original addresses of assembly code,
 206                 addresses subtracted from a base address can be printed.
 207                 Let's illustrate an example.
 208                 If a base address is 0XFFFFFFFF81624d50 as below,
 209
 210                 ffffffff81624d50 <load0>
 211
 212                 an address on assembly code has a specific absolute address as below
 213
 214                 ffffffff816250b8:│  mov    0x8(%r14),%rdi
 215
 216                 but if use_offset is 'true', an address subtracted from a base address is printed.
 217                 Default is true. This option is only applied to TUI.
 218
 219                              368:│  mov    0x8(%r14),%rdi
 220
 221         annotate.jump_arrows::
 222                 There can be jump instruction among assembly code.
 223                 Depending on a boolean value of jump_arrows,
 224                 arrows can be printed or not which represent
 225                 where do the instruction jump into as below.
 226
 227                 │     ┌──jmp    1333
 228                 │     │  xchg   %ax,%ax
 229                 │1330:│  mov    %r15,%r10
 230                 │1333:└─→cmp    %r15,%r14
 231
 232                 If jump_arrow is 'false', the arrows isn't printed as below.
 233                 Default is 'false'.
 234
 235                 │      ↓ jmp    1333
 236                 │        xchg   %ax,%ax
 237                 │1330:   mov    %r15,%r10
 238                 │1333:   cmp    %r15,%r14
 239
 240         annotate.show_linenr::
 241                 When showing source code if this option is 'true',
 242                 line numbers are printed as below.
 243
 244                 │1628         if (type & PERF_SAMPLE_IDENTIFIER) {
 245                 │     ↓ jne    508
 246                 │1628                 data->id = *array;
 247                 │1629                 array++;
 248                 │1630         }
 249
 250                 However if this option is 'false', they aren't printed as below.
 251                 Default is 'false'.
 252
 253                 │             if (type & PERF_SAMPLE_IDENTIFIER) {
 254                 │     ↓ jne    508
 255                 │                     data->id = *array;
 256                 │                     array++;
 257                 │             }
 258
 259         annotate.show_nr_jumps::
 260                 Let's see a part of assembly code.
 261
 262                 │1382:   movb   $0x1,-0x270(%rbp)
 263
 264                 If use this, the number of branches jumping to that address can be printed as below.
 265                 Default is 'false'.
 266
 267                 │1 1382:   movb   $0x1,-0x270(%rbp)
 268
 269         annotate.show_total_period::
 270                 To compare two records on an instruction base, with this option
 271                 provided, display total number of samples that belong to a line
 272                 in assembly code. If this option is 'true', total periods are printed
 273                 instead of percent values as below.
 274
 275                   302 │      mov    %eax,%eax
 276
 277                 But if this option is 'false', percent values for overhead are printed i.e.
 278                 Default is 'false'.
 279
 280                 99.93 │      mov    %eax,%eax
 281
 282 hist.*::
 283         hist.percentage::
 284                 This option control the way to calculate overhead of filtered entries -
 285                 that means the value of this option is effective only if there's a
 286                 filter (by comm, dso or symbol name). Suppose a following example:
 287
 288                        Overhead  Symbols
 289                        ........  .......
 290                         33.33%     foo
 291                         33.33%     bar
 292                         33.33%     baz
 293
 294                This is an original overhead and we'll filter out the first 'foo'
 295                entry. The value of 'relative' would increase the overhead of 'bar'
 296                and 'baz' to 50.00% for each, while 'absolute' would show their
 297                current overhead (33.33%).
 298
 299 ui.*::
 300         ui.show-headers::
 301                 This option controls display of column headers (like 'Overhead' and 'Symbol')
 302                 in 'report' and 'top'. If this option is false, they are hidden.
 303                 This option is only applied to TUI.
 304
 305 call-graph.*::
 306         When sub-commands 'top' and 'report' work with -g/—-children
 307         there're options in control of call-graph.
 308
 309         call-graph.record-mode::
 310                 The record-mode can be 'fp' (frame pointer), 'dwarf' and 'lbr'.
 311                 The value of 'dwarf' is effective only if perf detect needed library
 312                 (libunwind or a recent version of libdw).
 313                 'lbr' only work for cpus that support it.
 314
 315         call-graph.dump-size::
 316                 The size of stack to dump in order to do post-unwinding. Default is 8192 (byte).
 317                 When using dwarf into record-mode, the default size will be used if omitted.
 318
 319         call-graph.print-type::
 320                 The print-types can be graph (graph absolute), fractal (graph relative),
 321                 flat and folded. This option controls a way to show overhead for each callchain
 322                 entry. Suppose a following example.
 323
 324                 Overhead  Symbols
 325                 ........  .......
 326                   40.00%  foo
 327                           |
 328                           ---foo
 329                              |
 330                              |--50.00%--bar
 331                              |          main
 332                              |
 333                               --50.00%--baz
 334                                         main
 335
 336                 This output is a 'fractal' format. The 'foo' came from 'bar' and 'baz' exactly
 337                 half and half so 'fractal' shows 50.00% for each
 338                 (meaning that it assumes 100% total overhead of 'foo').
 339
 340                 The 'graph' uses absolute overhead value of 'foo' as total so each of
 341                 'bar' and 'baz' callchain will have 20.00% of overhead.
 342                 If 'flat' is used, single column and linear exposure of call chains.
 343                 'folded' mean call chains are displayed in a line, separated by semicolons.
 344
 345         call-graph.order::
 346                 This option controls print order of callchains. The default is
 347                 'callee' which means callee is printed at top and then followed by its
 348                 caller and so on. The 'caller' prints it in reverse order.
 349
 350                 If this option is not set and report.children or top.children is
 351                 set to true (or the equivalent command line option is given),
 352                 the default value of this option is changed to 'caller' for the
 353                 execution of 'perf report' or 'perf top'. Other commands will
 354                 still default to 'callee'.
 355
 356         call-graph.sort-key::
 357                 The callchains are merged if they contain same information.
 358                 The sort-key option determines a way to compare the callchains.
 359                 A value of 'sort-key' can be 'function' or 'address'.
 360                 The default is 'function'.
 361
 362         call-graph.threshold::
 363                 When there're many callchains it'd print tons of lines. So perf omits
 364                 small callchains under a certain overhead (threshold) and this option
 365                 control the threshold. Default is 0.5 (%). The overhead is calculated
 366                 by value depends on call-graph.print-type.
 367
 368         call-graph.print-limit::
 369                 This is a maximum number of lines of callchain printed for a single
 370                 histogram entry. Default is 0 which means no limitation.
 371
 372 report.*::
 373         report.percent-limit::
 374                 This one is mostly the same as call-graph.threshold but works for
 375                 histogram entries. Entries having an overhead lower than this
 376                 percentage will not be printed. Default is '0'. If percent-limit
 377                 is '10', only entries which have more than 10% of overhead will be
 378                 printed.
 379
 380         report.queue-size::
 381                 This option sets up the maximum allocation size of the internal
 382                 event queue for ordering events. Default is 0, meaning no limit.
 383
 384         report.children::
 385                 'Children' means functions called from another function.
 386                 If this option is true, 'perf report' cumulates callchains of children
 387                 and show (accumulated) total overhead as well as 'Self' overhead.
 388                 Please refer to the 'perf report' manual. The default is 'true'.
 389
 390         report.group::
 391                 This option is to show event group information together.
 392                 Example output with this turned on, notice that there is one column
 393                 per event in the group, ref-cycles and cycles:
 394
 395                 # group: {ref-cycles,cycles}
 396                 # ========
 397                 #
 398                 # Samples: 7K of event 'anon group { ref-cycles, cycles }'
 399                 # Event count (approx.): 6876107743
 400                 #
 401                 #         Overhead  Command      Shared Object               Symbol
 402                 # ................  .......  .................  ...................
 403                 #
 404                     99.84%  99.76%  noploop  noploop            [.] main
 405                      0.07%   0.00%  noploop  ld-2.15.so         [.] strcmp
 406                      0.03%   0.00%  noploop  [kernel.kallsyms]  [k] timerqueue_del
 407
 408 top.*::
 409         top.children::
 410                 Same as 'report.children'. So if it is enabled, the output of 'top'
 411                 command will have 'Children' overhead column as well as 'Self' overhead
 412                 column by default.
 413                 The default is 'true'.
 414
 415 man.*::
 416         man.viewer::
 417                 This option can assign a tool to view manual pages when 'help'
 418                 subcommand was invoked. Supported tools are 'man', 'woman'
 419                 (with emacs client) and 'konqueror'. Default is 'man'.
 420
 421                 New man viewer tool can be also added using 'man.<tool>.cmd'
 422                 or use different path using 'man.<tool>.path' config option.
 423
 424 pager.*::
 425         pager.<subcommand>::
 426                 When the subcommand is run on stdio, determine whether it uses
 427                 pager or not based on this value. Default is 'unspecified'.
 428
 429 kmem.*::
 430         kmem.default::
 431                 This option decides which allocator is to be analyzed if neither
 432                 '--slab' nor '--page' option is used. Default is 'slab'.
 433
 434 record.*::
 435         record.build-id::
 436                 This option can be 'cache', 'no-cache' or 'skip'.
 437                 'cache' is to post-process data and save/update the binaries into
 438                 the build-id cache (in ~/.debug). This is the default.
 439                 But if this option is 'no-cache', it will not update the build-id cache.
 440                 'skip' skips post-processing and does not update the cache.
 441
 442 SEE ALSO
 443 --------
 444 linkperf:perf[1]