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 305SEE ALSO 306-------- 307linkperf:perf[1] 308