commands.go

     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  
    15  package driver
    16  
    17  import (
    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.
    33  type 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).
    39  type 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.
    49  func (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.
    65  func 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.
    71  func SetVariableDefault(variable, value string) {
    72  	configure(variable, value)
    73  }
    74  
    75  // PostProcessor is a function that applies post-processing to the report output
    76  type 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.
    80  var interactiveMode = false
    81  
    82  // pprofCommands are the report generation commands recognized by pprof.
    83  var 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.
   125  var 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  	"tagroot": helpText(
   193  		"Adds pseudo stack frames for labels key/value pairs at the callstack root.",
   194  		"A comma-separated list of label keys.",
   195  		"The first key creates frames at the new root."),
   196  	"tagleaf": helpText(
   197  		"Adds pseudo stack frames for labels key/value pairs at the callstack leaf.",
   198  		"A comma-separated list of label keys.",
   199  		"The last key creates frames at the new leaf."),
   200  	"tagfocus": helpText(
   201  		"Restricts to samples with tags in range or matched by regexp",
   202  		"Use name=value syntax to limit the matching to a specific tag.",
   203  		"Numeric tag filter examples: 1kb, 1kb:10kb, memory=32mb:",
   204  		"String tag filter examples: foo, foo.*bar, mytag=foo.*bar"),
   205  	"tagignore": helpText(
   206  		"Discard samples with tags in range or matched by regexp",
   207  		"Use name=value syntax to limit the matching to a specific tag.",
   208  		"Numeric tag filter examples: 1kb, 1kb:10kb, memory=32mb:",
   209  		"String tag filter examples: foo, foo.*bar, mytag=foo.*bar"),
   210  	"tagshow": helpText(
   211  		"Only consider tags matching this regexp",
   212  		"Discard tags that do not match this regexp"),
   213  	"taghide": helpText(
   214  		"Skip tags matching this regexp",
   215  		"Discard tags that match this regexp"),
   216  	// Heap profile options
   217  	"divide_by": helpText(
   218  		"Ratio to divide all samples before visualization",
   219  		"Divide all samples values by a constant, eg the number of processors or jobs."),
   220  	"mean": helpText(
   221  		"Average sample value over first value (count)",
   222  		"For memory profiles, report average memory per allocation.",
   223  		"For time-based profiles, report average time per event."),
   224  	"sample_index": helpText(
   225  		"Sample value to report (0-based index or name)",
   226  		"Profiles contain multiple values per sample.",
   227  		"Use sample_index=i to select the ith value (starting at 0)."),
   228  	"normalize": helpText(
   229  		"Scales profile based on the base profile."),
   230  
   231  	// Data sorting criteria
   232  	"flat": helpText("Sort entries based on own weight"),
   233  	"cum":  helpText("Sort entries based on cumulative weight"),
   234  
   235  	// Output granularity
   236  	"functions": helpText(
   237  		"Aggregate at the function level.",
   238  		"Ignores the filename where the function was defined."),
   239  	"filefunctions": helpText(
   240  		"Aggregate at the function level.",
   241  		"Takes into account the filename where the function was defined."),
   242  	"files": "Aggregate at the file level.",
   243  	"lines": "Aggregate at the source code line level.",
   244  	"addresses": helpText(
   245  		"Aggregate at the address level.",
   246  		"Includes functions' addresses in the output."),
   247  	"noinlines": helpText(
   248  		"Ignore inlines.",
   249  		"Attributes inlined functions to their first out-of-line caller."),
   250  }
   251  
   252  func helpText(s ...string) string {
   253  	return strings.Join(s, "\n") + "\n"
   254  }
   255  
   256  // usage returns a string describing the pprof commands and configuration
   257  // options.  if commandLine is set, the output reflect cli usage.
   258  func usage(commandLine bool) string {
   259  	var prefix string
   260  	if commandLine {
   261  		prefix = "-"
   262  	}
   263  	fmtHelp := func(c, d string) string {
   264  		return fmt.Sprintf("    %-16s %s", c, strings.SplitN(d, "\n", 2)[0])
   265  	}
   266  
   267  	var commands []string
   268  	for name, cmd := range pprofCommands {
   269  		commands = append(commands, fmtHelp(prefix+name, cmd.description))
   270  	}
   271  	sort.Strings(commands)
   272  
   273  	var help string
   274  	if commandLine {
   275  		help = "  Output formats (select at most one):\n"
   276  	} else {
   277  		help = "  Commands:\n"
   278  		commands = append(commands, fmtHelp("o/options", "List options and their current values"))
   279  		commands = append(commands, fmtHelp("q/quit/exit/^D", "Exit pprof"))
   280  	}
   281  
   282  	help = help + strings.Join(commands, "\n") + "\n\n" +
   283  		"  Options:\n"
   284  
   285  	// Print help for configuration options after sorting them.
   286  	// Collect choices for multi-choice options print them together.
   287  	var variables []string
   288  	var radioStrings []string
   289  	for _, f := range configFields {
   290  		if len(f.choices) == 0 {
   291  			variables = append(variables, fmtHelp(prefix+f.name, configHelp[f.name]))
   292  			continue
   293  		}
   294  		// Format help for for this group.
   295  		s := []string{fmtHelp(f.name, "")}
   296  		for _, choice := range f.choices {
   297  			s = append(s, "  "+fmtHelp(prefix+choice, configHelp[choice]))
   298  		}
   299  		radioStrings = append(radioStrings, strings.Join(s, "\n"))
   300  	}
   301  	sort.Strings(variables)
   302  	sort.Strings(radioStrings)
   303  	return help + strings.Join(variables, "\n") + "\n\n" +
   304  		"  Option groups (only set one per group):\n" +
   305  		strings.Join(radioStrings, "\n")
   306  }
   307  
   308  func reportHelp(c string, cum, redirect bool) string {
   309  	h := []string{
   310  		c + " [n] [focus_regex]* [-ignore_regex]*",
   311  		"Include up to n samples",
   312  		"Include samples matching focus_regex, and exclude ignore_regex.",
   313  	}
   314  	if cum {
   315  		h[0] += " [-cum]"
   316  		h = append(h, "-cum sorts the output by cumulative weight")
   317  	}
   318  	if redirect {
   319  		h[0] += " >f"
   320  		h = append(h, "Optionally save the report on the file f")
   321  	}
   322  	return strings.Join(h, "\n")
   323  }
   324  
   325  func listHelp(c string, redirect bool) string {
   326  	h := []string{
   327  		c + "<func_regex|address> [-focus_regex]* [-ignore_regex]*",
   328  		"Include functions matching func_regex, or including the address specified.",
   329  		"Include samples matching focus_regex, and exclude ignore_regex.",
   330  	}
   331  	if redirect {
   332  		h[0] += " >f"
   333  		h = append(h, "Optionally save the report on the file f")
   334  	}
   335  	return strings.Join(h, "\n")
   336  }
   337  
   338  // browsers returns a list of commands to attempt for web visualization.
   339  func browsers() []string {
   340  	var cmds []string
   341  	if userBrowser := os.Getenv("BROWSER"); userBrowser != "" {
   342  		cmds = append(cmds, userBrowser)
   343  	}
   344  	switch runtime.GOOS {
   345  	case "darwin":
   346  		cmds = append(cmds, "/usr/bin/open")
   347  	case "windows":
   348  		cmds = append(cmds, "cmd /c start")
   349  	default:
   350  		// Commands opening browsers are prioritized over xdg-open, so browser()
   351  		// command can be used on linux to open the .svg file generated by the -web
   352  		// command (the .svg file includes embedded javascript so is best viewed in
   353  		// a browser).
   354  		cmds = append(cmds, []string{"chrome", "google-chrome", "chromium", "firefox", "sensible-browser"}...)
   355  		if os.Getenv("DISPLAY") != "" {
   356  			// xdg-open is only for use in a desktop environment.
   357  			cmds = append(cmds, "xdg-open")
   358  		}
   359  	}
   360  	return cmds
   361  }
   362  
   363  var kcachegrind = []string{"kcachegrind"}
   364  
   365  // awayFromTTY saves the output in a file if it would otherwise go to
   366  // the terminal screen. This is used to avoid dumping binary data on
   367  // the screen.
   368  func awayFromTTY(format string) PostProcessor {
   369  	return func(input io.Reader, output io.Writer, ui plugin.UI) error {
   370  		if output == os.Stdout && (ui.IsTerminal() || interactiveMode) {
   371  			tempFile, err := newTempFile("", "profile", "."+format)
   372  			if err != nil {
   373  				return err
   374  			}
   375  			ui.PrintErr("Generating report in ", tempFile.Name())
   376  			output = tempFile
   377  		}
   378  		_, err := io.Copy(output, input)
   379  		return err
   380  	}
   381  }
   382  
   383  func invokeDot(format string) PostProcessor {
   384  	return func(input io.Reader, output io.Writer, ui plugin.UI) error {
   385  		cmd := exec.Command("dot", "-T"+format)
   386  		cmd.Stdin, cmd.Stdout, cmd.Stderr = input, output, os.Stderr
   387  		if err := cmd.Run(); err != nil {
   388  			return fmt.Errorf("failed to execute dot. Is Graphviz installed? Error: %v", err)
   389  		}
   390  		return nil
   391  	}
   392  }
   393  
   394  // massageDotSVG invokes the dot tool to generate an SVG image and alters
   395  // the image to have panning capabilities when viewed in a browser.
   396  func massageDotSVG() PostProcessor {
   397  	generateSVG := invokeDot("svg")
   398  	return func(input io.Reader, output io.Writer, ui plugin.UI) error {
   399  		baseSVG := new(bytes.Buffer)
   400  		if err := generateSVG(input, baseSVG, ui); err != nil {
   401  			return err
   402  		}
   403  		_, err := output.Write([]byte(massageSVG(baseSVG.String())))
   404  		return err
   405  	}
   406  }
   407  
   408  func invokeVisualizer(suffix string, visualizers []string) PostProcessor {
   409  	return func(input io.Reader, output io.Writer, ui plugin.UI) error {
   410  		tempFile, err := newTempFile(os.TempDir(), "pprof", "."+suffix)
   411  		if err != nil {
   412  			return err
   413  		}
   414  		deferDeleteTempFile(tempFile.Name())
   415  		if _, err := io.Copy(tempFile, input); err != nil {
   416  			return err
   417  		}
   418  		tempFile.Close()
   419  		// Try visualizers until one is successful
   420  		for _, v := range visualizers {
   421  			// Separate command and arguments for exec.Command.
   422  			args := strings.Split(v, " ")
   423  			if len(args) == 0 {
   424  				continue
   425  			}
   426  			viewer := exec.Command(args[0], append(args[1:], tempFile.Name())...)
   427  			viewer.Stderr = os.Stderr
   428  			if err = viewer.Start(); err == nil {
   429  				// Wait for a second so that the visualizer has a chance to
   430  				// open the input file. This needs to be done even if we're
   431  				// waiting for the visualizer as it can be just a wrapper that
   432  				// spawns a browser tab and returns right away.
   433  				defer func(t <-chan time.Time) {
   434  					<-t
   435  				}(time.After(time.Second))
   436  				// On interactive mode, let the visualizer run in the background
   437  				// so other commands can be issued.
   438  				if !interactiveMode {
   439  					return viewer.Wait()
   440  				}
   441  				return nil
   442  			}
   443  		}
   444  		return err
   445  	}
   446  }
   447  
   448  // stringToBool is a custom parser for bools. We avoid using strconv.ParseBool
   449  // to remain compatible with old pprof behavior (e.g., treating "" as true).
   450  func stringToBool(s string) (bool, error) {
   451  	switch strings.ToLower(s) {
   452  	case "true", "t", "yes", "y", "1", "":
   453  		return true, nil
   454  	case "false", "f", "no", "n", "0":
   455  		return false, nil
   456  	default:
   457  		return false, fmt.Errorf(`illegal value "%s" for bool variable`, s)
   458  	}
   459  }
   460
View as plain text