commands.go

Documentation: cmd/vendor/github.com/google/pprof/internal/driver

     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  	"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  
   244  func 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.
   250  func 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  
   300  func 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  
   317  func 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.
   331  func 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  
   355  var 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.
   360  func 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  
   375  func 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.
   388  func 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  
   400  func 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).
   442  func 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
View as plain text