1perf-config(1) 2============== 3 4NAME 5---- 6perf-config - Get and set variables in a configuration file. 7 8SYNOPSIS 9-------- 10[verse] 11'perf config' -l | --list 12 13DESCRIPTION 14----------- 15You can manage variables in a configuration file with this command. 16 17OPTIONS 18------- 19 20-l:: 21--list:: 22 Show current config variables, name and value, for all sections. 23 24CONFIGURATION FILE 25------------------ 26 27The perf configuration file contains many variables to change various 28aspects of each of its tools, including output, disk usage, etc. 29The '$HOME/.perfconfig' file is used to store a per-user configuration. 30The file '$(sysconfdir)/perfconfig' can be used to 31store a system-wide default configuration. 32 33Syntax 34~~~~~~ 35 36The file consist of sections. A section starts with its name 37surrounded by square brackets and continues till the next section 38begins. 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 45Section names are case sensitive and can contain any characters except 46newline (double quote `"` and backslash have to be escaped as `\"` and `\\`, 47respectively). Section headers can't span multiple lines. 48 49Example 50~~~~~~~ 51 52Given 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 101Variables 102~~~~~~~~~ 103 104colors.*:: 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 147tui.*, 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 157buildid.*:: 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 172annotate.*:: 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 282hist.*:: 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 299ui.*:: 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 305call-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 372report.*:: 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 408top.*:: 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 415SEE ALSO 416-------- 417linkperf:perf[1] 418