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