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  	"showcolumns": helpText(
   251  		"Show column numbers at the source code line level."),
   252  }
   253  
   254  func helpText(s ...string) string {
   255  	return strings.Join(s, "\n") + "\n"
   256  }
   257  
   258  // usage returns a string describing the pprof commands and configuration
   259  // options.  if commandLine is set, the output reflect cli usage.
   260  func usage(commandLine bool) string {
   261  	var prefix string
   262  	if commandLine {
   263  		prefix = "-"
   264  	}
   265  	fmtHelp := func(c, d string) string {
   266  		return fmt.Sprintf("    %-16s %s", c, strings.SplitN(d, "\n", 2)[0])
   267  	}
   268  
   269  	var commands []string
   270  	for name, cmd := range pprofCommands {
   271  		commands = append(commands, fmtHelp(prefix+name, cmd.description))
   272  	}
   273  	sort.Strings(commands)
   274  
   275  	var help string
   276  	if commandLine {
   277  		help = "  Output formats (select at most one):\n"
   278  	} else {
   279  		help = "  Commands:\n"
   280  		commands = append(commands, fmtHelp("o/options", "List options and their current values"))
   281  		commands = append(commands, fmtHelp("q/quit/exit/^D", "Exit pprof"))
   282  	}
   283  
   284  	help = help + strings.Join(commands, "\n") + "\n\n" +
   285  		"  Options:\n"
   286  
   287  	// Print help for configuration options after sorting them.
   288  	// Collect choices for multi-choice options print them together.
   289  	var variables []string
   290  	var radioStrings []string
   291  	for _, f := range configFields {
   292  		if len(f.choices) == 0 {
   293  			variables = append(variables, fmtHelp(prefix+f.name, configHelp[f.name]))
   294  			continue
   295  		}
   296  		// Format help for for this group.
   297  		s := []string{fmtHelp(f.name, "")}
   298  		for _, choice := range f.choices {
   299  			s = append(s, "  "+fmtHelp(prefix+choice, configHelp[choice]))
   300  		}
   301  		radioStrings = append(radioStrings, strings.Join(s, "\n"))
   302  	}
   303  	sort.Strings(variables)
   304  	sort.Strings(radioStrings)
   305  	return help + strings.Join(variables, "\n") + "\n\n" +
   306  		"  Option groups (only set one per group):\n" +
   307  		strings.Join(radioStrings, "\n")
   308  }
   309  
   310  func reportHelp(c string, cum, redirect bool) string {
   311  	h := []string{
   312  		c + " [n] [focus_regex]* [-ignore_regex]*",
   313  		"Include up to n samples",
   314  		"Include samples matching focus_regex, and exclude ignore_regex.",
   315  	}
   316  	if cum {
   317  		h[0] += " [-cum]"
   318  		h = append(h, "-cum sorts the output by cumulative weight")
   319  	}
   320  	if redirect {
   321  		h[0] += " >f"
   322  		h = append(h, "Optionally save the report on the file f")
   323  	}
   324  	return strings.Join(h, "\n")
   325  }
   326  
   327  func listHelp(c string, redirect bool) string {
   328  	h := []string{
   329  		c + "<func_regex|address> [-focus_regex]* [-ignore_regex]*",
   330  		"Include functions matching func_regex, or including the address specified.",
   331  		"Include samples matching focus_regex, and exclude ignore_regex.",
   332  	}
   333  	if redirect {
   334  		h[0] += " >f"
   335  		h = append(h, "Optionally save the report on the file f")
   336  	}
   337  	return strings.Join(h, "\n")
   338  }
   339  
   340  // browsers returns a list of commands to attempt for web visualization.
   341  func browsers() []string {
   342  	var cmds []string
   343  	if userBrowser := os.Getenv("BROWSER"); userBrowser != "" {
   344  		cmds = append(cmds, userBrowser)
   345  	}
   346  	switch runtime.GOOS {
   347  	case "darwin":
   348  		cmds = append(cmds, "/usr/bin/open")
   349  	case "windows":
   350  		cmds = append(cmds, "cmd /c start")
   351  	default:
   352  		// Commands opening browsers are prioritized over xdg-open, so browser()
   353  		// command can be used on linux to open the .svg file generated by the -web
   354  		// command (the .svg file includes embedded javascript so is best viewed in
   355  		// a browser).
   356  		cmds = append(cmds, []string{"chrome", "google-chrome", "chromium", "firefox", "sensible-browser"}...)
   357  		if os.Getenv("DISPLAY") != "" {
   358  			// xdg-open is only for use in a desktop environment.
   359  			cmds = append(cmds, "xdg-open")
   360  		}
   361  	}
   362  	return cmds
   363  }
   364  
   365  var kcachegrind = []string{"kcachegrind"}
   366  
   367  // awayFromTTY saves the output in a file if it would otherwise go to
   368  // the terminal screen. This is used to avoid dumping binary data on
   369  // the screen.
   370  func awayFromTTY(format string) PostProcessor {
   371  	return func(input io.Reader, output io.Writer, ui plugin.UI) error {
   372  		if output == os.Stdout && (ui.IsTerminal() || interactiveMode) {
   373  			tempFile, err := newTempFile("", "profile", "."+format)
   374  			if err != nil {
   375  				return err
   376  			}
   377  			ui.PrintErr("Generating report in ", tempFile.Name())
   378  			output = tempFile
   379  		}
   380  		_, err := io.Copy(output, input)
   381  		return err
   382  	}
   383  }
   384  
   385  func invokeDot(format string) PostProcessor {
   386  	return func(input io.Reader, output io.Writer, ui plugin.UI) error {
   387  		cmd := exec.Command("dot", "-T"+format)
   388  		cmd.Stdin, cmd.Stdout, cmd.Stderr = input, output, os.Stderr
   389  		if err := cmd.Run(); err != nil {
   390  			return fmt.Errorf("failed to execute dot. Is Graphviz installed? Error: %v", err)
   391  		}
   392  		return nil
   393  	}
   394  }
   395  
   396  // massageDotSVG invokes the dot tool to generate an SVG image and alters
   397  // the image to have panning capabilities when viewed in a browser.
   398  func massageDotSVG() PostProcessor {
   399  	generateSVG := invokeDot("svg")
   400  	return func(input io.Reader, output io.Writer, ui plugin.UI) error {
   401  		baseSVG := new(bytes.Buffer)
   402  		if err := generateSVG(input, baseSVG, ui); err != nil {
   403  			return err
   404  		}
   405  		_, err := output.Write([]byte(massageSVG(baseSVG.String())))
   406  		return err
   407  	}
   408  }
   409  
   410  func invokeVisualizer(suffix string, visualizers []string) PostProcessor {
   411  	return func(input io.Reader, output io.Writer, ui plugin.UI) error {
   412  		tempFile, err := newTempFile(os.TempDir(), "pprof", "."+suffix)
   413  		if err != nil {
   414  			return err
   415  		}
   416  		deferDeleteTempFile(tempFile.Name())
   417  		if _, err := io.Copy(tempFile, input); err != nil {
   418  			return err
   419  		}
   420  		tempFile.Close()
   421  		// Try visualizers until one is successful
   422  		for _, v := range visualizers {
   423  			// Separate command and arguments for exec.Command.
   424  			args := strings.Split(v, " ")
   425  			if len(args) == 0 {
   426  				continue
   427  			}
   428  			viewer := exec.Command(args[0], append(args[1:], tempFile.Name())...)
   429  			viewer.Stderr = os.Stderr
   430  			if err = viewer.Start(); err == nil {
   431  				// Wait for a second so that the visualizer has a chance to
   432  				// open the input file. This needs to be done even if we're
   433  				// waiting for the visualizer as it can be just a wrapper that
   434  				// spawns a browser tab and returns right away.
   435  				defer func(t <-chan time.Time) {
   436  					<-t
   437  				}(time.After(time.Second))
   438  				// On interactive mode, let the visualizer run in the background
   439  				// so other commands can be issued.
   440  				if !interactiveMode {
   441  					return viewer.Wait()
   442  				}
   443  				return nil
   444  			}
   445  		}
   446  		return err
   447  	}
   448  }
   449  
   450  // stringToBool is a custom parser for bools. We avoid using strconv.ParseBool
   451  // to remain compatible with old pprof behavior (e.g., treating "" as true).
   452  func stringToBool(s string) (bool, error) {
   453  	switch strings.ToLower(s) {
   454  	case "true", "t", "yes", "y", "1", "":
   455  		return true, nil
   456  	case "false", "f", "no", "n", "0":
   457  		return false, nil
   458  	default:
   459  		return false, fmt.Errorf(`illegal value "%s" for bool variable`, s)
   460  	}
   461  }
   462
View as plain text