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