1// Copyright 2014 Google Inc. All Rights Reserved. 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15package driver 16 17import ( 18 "bytes" 19 "fmt" 20 "io" 21 "os" 22 "os/exec" 23 "runtime" 24 "sort" 25 "strings" 26 "time" 27 28 "github.com/google/pprof/internal/plugin" 29 "github.com/google/pprof/internal/report" 30) 31 32// commands describes the commands accepted by pprof. 33type commands map[string]*command 34 35// command describes the actions for a pprof command. Includes a 36// function for command-line completion, the report format to use 37// during report generation, any postprocessing functions, and whether 38// the command expects a regexp parameter (typically a function name). 39type command struct { 40 format int // report format to generate 41 postProcess PostProcessor // postprocessing to run on report 42 visualizer PostProcessor // display output using some callback 43 hasParam bool // collect a parameter from the CLI 44 description string // single-line description text saying what the command does 45 usage string // multi-line help text saying how the command is used 46} 47 48// help returns a help string for a command. 49func (c *command) help(name string) string { 50 message := c.description + "\n" 51 if c.usage != "" { 52 message += " Usage:\n" 53 lines := strings.Split(c.usage, "\n") 54 for _, line := range lines { 55 message += fmt.Sprintf(" %s\n", line) 56 } 57 } 58 return message + "\n" 59} 60 61// AddCommand adds an additional command to the set of commands 62// accepted by pprof. This enables extensions to add new commands for 63// specialized visualization formats. If the command specified already 64// exists, it is overwritten. 65func AddCommand(cmd string, format int, post PostProcessor, desc, usage string) { 66 pprofCommands[cmd] = &command{format, post, nil, false, desc, usage} 67} 68 69// SetVariableDefault sets the default value for a pprof 70// variable. This enables extensions to set their own defaults. 71func SetVariableDefault(variable, value string) { 72 configure(variable, value) 73} 74 75// PostProcessor is a function that applies post-processing to the report output 76type PostProcessor func(input io.Reader, output io.Writer, ui plugin.UI) error 77 78// interactiveMode is true if pprof is running on interactive mode, reading 79// commands from its shell. 80var interactiveMode = false 81 82// pprofCommands are the report generation commands recognized by pprof. 83var pprofCommands = commands{ 84 // Commands that require no post-processing. 85 "comments": {report.Comments, nil, nil, false, "Output all profile comments", ""}, 86 "disasm": {report.Dis, nil, nil, true, "Output assembly listings annotated with samples", listHelp("disasm", true)}, 87 "dot": {report.Dot, nil, nil, false, "Outputs a graph in DOT format", reportHelp("dot", false, true)}, 88 "list": {report.List, nil, nil, true, "Output annotated source for functions matching regexp", listHelp("list", false)}, 89 "peek": {report.Tree, nil, nil, true, "Output callers/callees of functions matching regexp", "peek func_regex\nDisplay callers and callees of functions matching func_regex."}, 90 "raw": {report.Raw, nil, nil, false, "Outputs a text representation of the raw profile", ""}, 91 "tags": {report.Tags, nil, nil, false, "Outputs all tags in the profile", "tags [tag_regex]* [-ignore_regex]* [>file]\nList tags with key:value matching tag_regex and exclude ignore_regex."}, 92 "text": {report.Text, nil, nil, false, "Outputs top entries in text form", reportHelp("text", true, true)}, 93 "top": {report.Text, nil, nil, false, "Outputs top entries in text form", reportHelp("top", true, true)}, 94 "traces": {report.Traces, nil, nil, false, "Outputs all profile samples in text form", ""}, 95 "tree": {report.Tree, nil, nil, false, "Outputs a text rendering of call graph", reportHelp("tree", true, true)}, 96 97 // Save binary formats to a file 98 "callgrind": {report.Callgrind, nil, awayFromTTY("callgraph.out"), false, "Outputs a graph in callgrind format", reportHelp("callgrind", false, true)}, 99 "proto": {report.Proto, nil, awayFromTTY("pb.gz"), false, "Outputs the profile in compressed protobuf format", ""}, 100 "topproto": {report.TopProto, nil, awayFromTTY("pb.gz"), false, "Outputs top entries in compressed protobuf format", ""}, 101 102 // Generate report in DOT format and postprocess with dot 103 "gif": {report.Dot, invokeDot("gif"), awayFromTTY("gif"), false, "Outputs a graph image in GIF format", reportHelp("gif", false, true)}, 104 "pdf": {report.Dot, invokeDot("pdf"), awayFromTTY("pdf"), false, "Outputs a graph in PDF format", reportHelp("pdf", false, true)}, 105 "png": {report.Dot, invokeDot("png"), awayFromTTY("png"), false, "Outputs a graph image in PNG format", reportHelp("png", false, true)}, 106 "ps": {report.Dot, invokeDot("ps"), awayFromTTY("ps"), false, "Outputs a graph in PS format", reportHelp("ps", false, true)}, 107 108 // Save SVG output into a file 109 "svg": {report.Dot, massageDotSVG(), awayFromTTY("svg"), false, "Outputs a graph in SVG format", reportHelp("svg", false, true)}, 110 111 // Visualize postprocessed dot output 112 "eog": {report.Dot, invokeDot("svg"), invokeVisualizer("svg", []string{"eog"}), false, "Visualize graph through eog", reportHelp("eog", false, false)}, 113 "evince": {report.Dot, invokeDot("pdf"), invokeVisualizer("pdf", []string{"evince"}), false, "Visualize graph through evince", reportHelp("evince", false, false)}, 114 "gv": {report.Dot, invokeDot("ps"), invokeVisualizer("ps", []string{"gv --noantialias"}), false, "Visualize graph through gv", reportHelp("gv", false, false)}, 115 "web": {report.Dot, massageDotSVG(), invokeVisualizer("svg", browsers()), false, "Visualize graph through web browser", reportHelp("web", false, false)}, 116 117 // Visualize callgrind output 118 "kcachegrind": {report.Callgrind, nil, invokeVisualizer("grind", kcachegrind), false, "Visualize report in KCachegrind", reportHelp("kcachegrind", false, false)}, 119 120 // Visualize HTML directly generated by report. 121 "weblist": {report.WebList, nil, invokeVisualizer("html", browsers()), true, "Display annotated source in a web browser", listHelp("weblist", false)}, 122} 123 124// configHelp contains help text per configuration parameter. 125var configHelp = map[string]string{ 126 // Filename for file-based output formats, stdout by default. 127 "output": helpText("Output filename for file-based outputs"), 128 129 // Comparisons. 130 "drop_negative": helpText( 131 "Ignore negative differences", 132 "Do not show any locations with values <0."), 133 134 // Graph handling options. 135 "call_tree": helpText( 136 "Create a context-sensitive call tree", 137 "Treat locations reached through different paths as separate."), 138 139 // Display options. 140 "relative_percentages": helpText( 141 "Show percentages relative to focused subgraph", 142 "If unset, percentages are relative to full graph before focusing", 143 "to facilitate comparison with original graph."), 144 "unit": helpText( 145 "Measurement units to display", 146 "Scale the sample values to this unit.", 147 "For time-based profiles, use seconds, milliseconds, nanoseconds, etc.", 148 "For memory profiles, use megabytes, kilobytes, bytes, etc.", 149 "Using auto will scale each value independently to the most natural unit."), 150 "compact_labels": "Show minimal headers", 151 "source_path": "Search path for source files", 152 "trim_path": "Path to trim from source paths before search", 153 "intel_syntax": helpText( 154 "Show assembly in Intel syntax", 155 "Only applicable to commands `disasm` and `weblist`"), 156 157 // Filtering options 158 "nodecount": helpText( 159 "Max number of nodes to show", 160 "Uses heuristics to limit the number of locations to be displayed.", 161 "On graphs, dotted edges represent paths through nodes that have been removed."), 162 "nodefraction": "Hide nodes below <f>*total", 163 "edgefraction": "Hide edges below <f>*total", 164 "trim": helpText( 165 "Honor nodefraction/edgefraction/nodecount defaults", 166 "Set to false to get the full profile, without any trimming."), 167 "focus": helpText( 168 "Restricts to samples going through a node matching regexp", 169 "Discard samples that do not include a node matching this regexp.", 170 "Matching includes the function name, filename or object name."), 171 "ignore": helpText( 172 "Skips paths going through any nodes matching regexp", 173 "If set, discard samples that include a node matching this regexp.", 174 "Matching includes the function name, filename or object name."), 175 "prune_from": helpText( 176 "Drops any functions below the matched frame.", 177 "If set, any frames matching the specified regexp and any frames", 178 "below it will be dropped from each sample."), 179 "hide": helpText( 180 "Skips nodes matching regexp", 181 "Discard nodes that match this location.", 182 "Other nodes from samples that include this location will be shown.", 183 "Matching includes the function name, filename or object name."), 184 "show": helpText( 185 "Only show nodes matching regexp", 186 "If set, only show nodes that match this location.", 187 "Matching includes the function name, filename or object name."), 188 "show_from": helpText( 189 "Drops functions above the highest matched frame.", 190 "If set, all frames above the highest match are dropped from every sample.", 191 "Matching includes the function name, filename or object name."), 192 "tagfocus": helpText( 193 "Restricts to samples with tags in range or matched by regexp", 194 "Use name=value syntax to limit the matching to a specific tag.", 195 "Numeric tag filter examples: 1kb, 1kb:10kb, memory=32mb:", 196 "String tag filter examples: foo, foo.*bar, mytag=foo.*bar"), 197 "tagignore": helpText( 198 "Discard samples with tags in range or matched by regexp", 199 "Use name=value syntax to limit the matching to a specific tag.", 200 "Numeric tag filter examples: 1kb, 1kb:10kb, memory=32mb:", 201 "String tag filter examples: foo, foo.*bar, mytag=foo.*bar"), 202 "tagshow": helpText( 203 "Only consider tags matching this regexp", 204 "Discard tags that do not match this regexp"), 205 "taghide": helpText( 206 "Skip tags matching this regexp", 207 "Discard tags that match this regexp"), 208 // Heap profile options 209 "divide_by": helpText( 210 "Ratio to divide all samples before visualization", 211 "Divide all samples values by a constant, eg the number of processors or jobs."), 212 "mean": helpText( 213 "Average sample value over first value (count)", 214 "For memory profiles, report average memory per allocation.", 215 "For time-based profiles, report average time per event."), 216 "sample_index": helpText( 217 "Sample value to report (0-based index or name)", 218 "Profiles contain multiple values per sample.", 219 "Use sample_index=i to select the ith value (starting at 0)."), 220 "normalize": helpText( 221 "Scales profile based on the base profile."), 222 223 // Data sorting criteria 224 "flat": helpText("Sort entries based on own weight"), 225 "cum": helpText("Sort entries based on cumulative weight"), 226 227 // Output granularity 228 "functions": helpText( 229 "Aggregate at the function level.", 230 "Ignores the filename where the function was defined."), 231 "filefunctions": helpText( 232 "Aggregate at the function level.", 233 "Takes into account the filename where the function was defined."), 234 "files": "Aggregate at the file level.", 235 "lines": "Aggregate at the source code line level.", 236 "addresses": helpText( 237 "Aggregate at the address level.", 238 "Includes functions' addresses in the output."), 239 "noinlines": helpText( 240 "Ignore inlines.", 241 "Attributes inlined functions to their first out-of-line caller."), 242} 243 244func helpText(s ...string) string { 245 return strings.Join(s, "\n") + "\n" 246} 247 248// usage returns a string describing the pprof commands and configuration 249// options. if commandLine is set, the output reflect cli usage. 250func usage(commandLine bool) string { 251 var prefix string 252 if commandLine { 253 prefix = "-" 254 } 255 fmtHelp := func(c, d string) string { 256 return fmt.Sprintf(" %-16s %s", c, strings.SplitN(d, "\n", 2)[0]) 257 } 258 259 var commands []string 260 for name, cmd := range pprofCommands { 261 commands = append(commands, fmtHelp(prefix+name, cmd.description)) 262 } 263 sort.Strings(commands) 264 265 var help string 266 if commandLine { 267 help = " Output formats (select at most one):\n" 268 } else { 269 help = " Commands:\n" 270 commands = append(commands, fmtHelp("o/options", "List options and their current values")) 271 commands = append(commands, fmtHelp("q/quit/exit/^D", "Exit pprof")) 272 } 273 274 help = help + strings.Join(commands, "\n") + "\n\n" + 275 " Options:\n" 276 277 // Print help for configuration options after sorting them. 278 // Collect choices for multi-choice options print them together. 279 var variables []string 280 var radioStrings []string 281 for _, f := range configFields { 282 if len(f.choices) == 0 { 283 variables = append(variables, fmtHelp(prefix+f.name, configHelp[f.name])) 284 continue 285 } 286 // Format help for for this group. 287 s := []string{fmtHelp(f.name, "")} 288 for _, choice := range f.choices { 289 s = append(s, " "+fmtHelp(prefix+choice, configHelp[choice])) 290 } 291 radioStrings = append(radioStrings, strings.Join(s, "\n")) 292 } 293 sort.Strings(variables) 294 sort.Strings(radioStrings) 295 return help + strings.Join(variables, "\n") + "\n\n" + 296 " Option groups (only set one per group):\n" + 297 strings.Join(radioStrings, "\n") 298} 299 300func reportHelp(c string, cum, redirect bool) string { 301 h := []string{ 302 c + " [n] [focus_regex]* [-ignore_regex]*", 303 "Include up to n samples", 304 "Include samples matching focus_regex, and exclude ignore_regex.", 305 } 306 if cum { 307 h[0] += " [-cum]" 308 h = append(h, "-cum sorts the output by cumulative weight") 309 } 310 if redirect { 311 h[0] += " >f" 312 h = append(h, "Optionally save the report on the file f") 313 } 314 return strings.Join(h, "\n") 315} 316 317func listHelp(c string, redirect bool) string { 318 h := []string{ 319 c + "<func_regex|address> [-focus_regex]* [-ignore_regex]*", 320 "Include functions matching func_regex, or including the address specified.", 321 "Include samples matching focus_regex, and exclude ignore_regex.", 322 } 323 if redirect { 324 h[0] += " >f" 325 h = append(h, "Optionally save the report on the file f") 326 } 327 return strings.Join(h, "\n") 328} 329 330// browsers returns a list of commands to attempt for web visualization. 331func browsers() []string { 332 var cmds []string 333 if userBrowser := os.Getenv("BROWSER"); userBrowser != "" { 334 cmds = append(cmds, userBrowser) 335 } 336 switch runtime.GOOS { 337 case "darwin": 338 cmds = append(cmds, "/usr/bin/open") 339 case "windows": 340 cmds = append(cmds, "cmd /c start") 341 default: 342 // Commands opening browsers are prioritized over xdg-open, so browser() 343 // command can be used on linux to open the .svg file generated by the -web 344 // command (the .svg file includes embedded javascript so is best viewed in 345 // a browser). 346 cmds = append(cmds, []string{"chrome", "google-chrome", "chromium", "firefox", "sensible-browser"}...) 347 if os.Getenv("DISPLAY") != "" { 348 // xdg-open is only for use in a desktop environment. 349 cmds = append(cmds, "xdg-open") 350 } 351 } 352 return cmds 353} 354 355var kcachegrind = []string{"kcachegrind"} 356 357// awayFromTTY saves the output in a file if it would otherwise go to 358// the terminal screen. This is used to avoid dumping binary data on 359// the screen. 360func awayFromTTY(format string) PostProcessor { 361 return func(input io.Reader, output io.Writer, ui plugin.UI) error { 362 if output == os.Stdout && (ui.IsTerminal() || interactiveMode) { 363 tempFile, err := newTempFile("", "profile", "."+format) 364 if err != nil { 365 return err 366 } 367 ui.PrintErr("Generating report in ", tempFile.Name()) 368 output = tempFile 369 } 370 _, err := io.Copy(output, input) 371 return err 372 } 373} 374 375func invokeDot(format string) PostProcessor { 376 return func(input io.Reader, output io.Writer, ui plugin.UI) error { 377 cmd := exec.Command("dot", "-T"+format) 378 cmd.Stdin, cmd.Stdout, cmd.Stderr = input, output, os.Stderr 379 if err := cmd.Run(); err != nil { 380 return fmt.Errorf("failed to execute dot. Is Graphviz installed? Error: %v", err) 381 } 382 return nil 383 } 384} 385 386// massageDotSVG invokes the dot tool to generate an SVG image and alters 387// the image to have panning capabilities when viewed in a browser. 388func massageDotSVG() PostProcessor { 389 generateSVG := invokeDot("svg") 390 return func(input io.Reader, output io.Writer, ui plugin.UI) error { 391 baseSVG := new(bytes.Buffer) 392 if err := generateSVG(input, baseSVG, ui); err != nil { 393 return err 394 } 395 _, err := output.Write([]byte(massageSVG(baseSVG.String()))) 396 return err 397 } 398} 399 400func invokeVisualizer(suffix string, visualizers []string) PostProcessor { 401 return func(input io.Reader, output io.Writer, ui plugin.UI) error { 402 tempFile, err := newTempFile(os.TempDir(), "pprof", "."+suffix) 403 if err != nil { 404 return err 405 } 406 deferDeleteTempFile(tempFile.Name()) 407 if _, err := io.Copy(tempFile, input); err != nil { 408 return err 409 } 410 tempFile.Close() 411 // Try visualizers until one is successful 412 for _, v := range visualizers { 413 // Separate command and arguments for exec.Command. 414 args := strings.Split(v, " ") 415 if len(args) == 0 { 416 continue 417 } 418 viewer := exec.Command(args[0], append(args[1:], tempFile.Name())...) 419 viewer.Stderr = os.Stderr 420 if err = viewer.Start(); err == nil { 421 // Wait for a second so that the visualizer has a chance to 422 // open the input file. This needs to be done even if we're 423 // waiting for the visualizer as it can be just a wrapper that 424 // spawns a browser tab and returns right away. 425 defer func(t <-chan time.Time) { 426 <-t 427 }(time.After(time.Second)) 428 // On interactive mode, let the visualizer run in the background 429 // so other commands can be issued. 430 if !interactiveMode { 431 return viewer.Wait() 432 } 433 return nil 434 } 435 } 436 return err 437 } 438} 439 440// stringToBool is a custom parser for bools. We avoid using strconv.ParseBool 441// to remain compatible with old pprof behavior (e.g., treating "" as true). 442func stringToBool(s string) (bool, error) { 443 switch strings.ToLower(s) { 444 case "true", "t", "yes", "y", "1", "": 445 return true, nil 446 case "false", "f", "no", "n", "0": 447 return false, nil 448 default: 449 return false, fmt.Errorf(`illegal value "%s" for bool variable`, s) 450 } 451} 452