Source file src/cmd/vendor/github.com/google/pprof/driver/driver.go

Documentation: cmd/vendor/github.com/google/pprof/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 provides an external entry point to the pprof driver.
    16  package driver
    17  
    18  import (
    19  	"io"
    20  	"net/http"
    21  	"regexp"
    22  	"time"
    23  
    24  	internaldriver "github.com/google/pprof/internal/driver"
    25  	"github.com/google/pprof/internal/plugin"
    26  	"github.com/google/pprof/profile"
    27  )
    28  
    29  // PProf acquires a profile, and symbolizes it using a profile
    30  // manager. Then it generates a report formatted according to the
    31  // options selected through the flags package.
    32  func PProf(o *Options) error {
    33  	return internaldriver.PProf(o.internalOptions())
    34  }
    35  
    36  func (o *Options) internalOptions() *plugin.Options {
    37  	var obj plugin.ObjTool
    38  	if o.Obj != nil {
    39  		obj = &internalObjTool{o.Obj}
    40  	}
    41  	var sym plugin.Symbolizer
    42  	if o.Sym != nil {
    43  		sym = &internalSymbolizer{o.Sym}
    44  	}
    45  	var httpServer func(args *plugin.HTTPServerArgs) error
    46  	if o.HTTPServer != nil {
    47  		httpServer = func(args *plugin.HTTPServerArgs) error {
    48  			return o.HTTPServer(((*HTTPServerArgs)(args)))
    49  		}
    50  	}
    51  	return &plugin.Options{
    52  		Writer:        o.Writer,
    53  		Flagset:       o.Flagset,
    54  		Fetch:         o.Fetch,
    55  		Sym:           sym,
    56  		Obj:           obj,
    57  		UI:            o.UI,
    58  		HTTPServer:    httpServer,
    59  		HTTPTransport: o.HTTPTransport,
    60  	}
    61  }
    62  
    63  // HTTPServerArgs contains arguments needed by an HTTP server that
    64  // is exporting a pprof web interface.
    65  type HTTPServerArgs plugin.HTTPServerArgs
    66  
    67  // Options groups all the optional plugins into pprof.
    68  type Options struct {
    69  	Writer        Writer
    70  	Flagset       FlagSet
    71  	Fetch         Fetcher
    72  	Sym           Symbolizer
    73  	Obj           ObjTool
    74  	UI            UI
    75  	HTTPServer    func(*HTTPServerArgs) error
    76  	HTTPTransport http.RoundTripper
    77  }
    78  
    79  // Writer provides a mechanism to write data under a certain name,
    80  // typically a filename.
    81  type Writer interface {
    82  	Open(name string) (io.WriteCloser, error)
    83  }
    84  
    85  // A FlagSet creates and parses command-line flags.
    86  // It is similar to the standard flag.FlagSet.
    87  type FlagSet interface {
    88  	// Bool, Int, Float64, and String define new flags,
    89  	// like the functions of the same name in package flag.
    90  	Bool(name string, def bool, usage string) *bool
    91  	Int(name string, def int, usage string) *int
    92  	Float64(name string, def float64, usage string) *float64
    93  	String(name string, def string, usage string) *string
    94  
    95  	// BoolVar, IntVar, Float64Var, and StringVar define new flags referencing
    96  	// a given pointer, like the functions of the same name in package flag.
    97  	BoolVar(pointer *bool, name string, def bool, usage string)
    98  	IntVar(pointer *int, name string, def int, usage string)
    99  	Float64Var(pointer *float64, name string, def float64, usage string)
   100  	StringVar(pointer *string, name string, def string, usage string)
   101  
   102  	// StringList is similar to String but allows multiple values for a
   103  	// single flag
   104  	StringList(name string, def string, usage string) *[]*string
   105  
   106  	// ExtraUsage returns any additional text that should be printed after the
   107  	// standard usage message. The extra usage message returned includes all text
   108  	// added with AddExtraUsage().
   109  	// The typical use of ExtraUsage is to show any custom flags defined by the
   110  	// specific pprof plugins being used.
   111  	ExtraUsage() string
   112  
   113  	// AddExtraUsage appends additional text to the end of the extra usage message.
   114  	AddExtraUsage(eu string)
   115  
   116  	// Parse initializes the flags with their values for this run
   117  	// and returns the non-flag command line arguments.
   118  	// If an unknown flag is encountered or there are no arguments,
   119  	// Parse should call usage and return nil.
   120  	Parse(usage func()) []string
   121  }
   122  
   123  // A Fetcher reads and returns the profile named by src, using
   124  // the specified duration and timeout. It returns the fetched
   125  // profile and a string indicating a URL from where the profile
   126  // was fetched, which may be different than src.
   127  type Fetcher interface {
   128  	Fetch(src string, duration, timeout time.Duration) (*profile.Profile, string, error)
   129  }
   130  
   131  // A Symbolizer introduces symbol information into a profile.
   132  type Symbolizer interface {
   133  	Symbolize(mode string, srcs MappingSources, prof *profile.Profile) error
   134  }
   135  
   136  // MappingSources map each profile.Mapping to the source of the profile.
   137  // The key is either Mapping.File or Mapping.BuildId.
   138  type MappingSources map[string][]struct {
   139  	Source string // URL of the source the mapping was collected from
   140  	Start  uint64 // delta applied to addresses from this source (to represent Merge adjustments)
   141  }
   142  
   143  // An ObjTool inspects shared libraries and executable files.
   144  type ObjTool interface {
   145  	// Open opens the named object file. If the object is a shared
   146  	// library, start/limit/offset are the addresses where it is mapped
   147  	// into memory in the address space being inspected.
   148  	Open(file string, start, limit, offset uint64) (ObjFile, error)
   149  
   150  	// Disasm disassembles the named object file, starting at
   151  	// the start address and stopping at (before) the end address.
   152  	Disasm(file string, start, end uint64) ([]Inst, error)
   153  }
   154  
   155  // An Inst is a single instruction in an assembly listing.
   156  type Inst struct {
   157  	Addr     uint64 // virtual address of instruction
   158  	Text     string // instruction text
   159  	Function string // function name
   160  	File     string // source file
   161  	Line     int    // source line
   162  }
   163  
   164  // An ObjFile is a single object file: a shared library or executable.
   165  type ObjFile interface {
   166  	// Name returns the underlying file name, if available.
   167  	Name() string
   168  
   169  	// Base returns the base address to use when looking up symbols in the file.
   170  	Base() uint64
   171  
   172  	// BuildID returns the GNU build ID of the file, or an empty string.
   173  	BuildID() string
   174  
   175  	// SourceLine reports the source line information for a given
   176  	// address in the file. Due to inlining, the source line information
   177  	// is in general a list of positions representing a call stack,
   178  	// with the leaf function first.
   179  	SourceLine(addr uint64) ([]Frame, error)
   180  
   181  	// Symbols returns a list of symbols in the object file.
   182  	// If r is not nil, Symbols restricts the list to symbols
   183  	// with names matching the regular expression.
   184  	// If addr is not zero, Symbols restricts the list to symbols
   185  	// containing that address.
   186  	Symbols(r *regexp.Regexp, addr uint64) ([]*Sym, error)
   187  
   188  	// Close closes the file, releasing associated resources.
   189  	Close() error
   190  }
   191  
   192  // A Frame describes a single line in a source file.
   193  type Frame struct {
   194  	Func string // name of function
   195  	File string // source file name
   196  	Line int    // line in file
   197  }
   198  
   199  // A Sym describes a single symbol in an object file.
   200  type Sym struct {
   201  	Name  []string // names of symbol (many if symbol was dedup'ed)
   202  	File  string   // object file containing symbol
   203  	Start uint64   // start virtual address
   204  	End   uint64   // virtual address of last byte in sym (Start+size-1)
   205  }
   206  
   207  // A UI manages user interactions.
   208  type UI interface {
   209  	// Read returns a line of text (a command) read from the user.
   210  	// prompt is printed before reading the command.
   211  	ReadLine(prompt string) (string, error)
   212  
   213  	// Print shows a message to the user.
   214  	// It formats the text as fmt.Print would and adds a final \n if not already present.
   215  	// For line-based UI, Print writes to standard error.
   216  	// (Standard output is reserved for report data.)
   217  	Print(...interface{})
   218  
   219  	// PrintErr shows an error message to the user.
   220  	// It formats the text as fmt.Print would and adds a final \n if not already present.
   221  	// For line-based UI, PrintErr writes to standard error.
   222  	PrintErr(...interface{})
   223  
   224  	// IsTerminal returns whether the UI is known to be tied to an
   225  	// interactive terminal (as opposed to being redirected to a file).
   226  	IsTerminal() bool
   227  
   228  	// WantBrowser indicates whether browser should be opened with the -http option.
   229  	WantBrowser() bool
   230  
   231  	// SetAutoComplete instructs the UI to call complete(cmd) to obtain
   232  	// the auto-completion of cmd, if the UI supports auto-completion at all.
   233  	SetAutoComplete(complete func(string) string)
   234  }
   235  
   236  // internalObjTool is a wrapper to map from the pprof external
   237  // interface to the internal interface.
   238  type internalObjTool struct {
   239  	ObjTool
   240  }
   241  
   242  func (o *internalObjTool) Open(file string, start, limit, offset uint64) (plugin.ObjFile, error) {
   243  	f, err := o.ObjTool.Open(file, start, limit, offset)
   244  	if err != nil {
   245  		return nil, err
   246  	}
   247  	return &internalObjFile{f}, err
   248  }
   249  
   250  type internalObjFile struct {
   251  	ObjFile
   252  }
   253  
   254  func (f *internalObjFile) SourceLine(frame uint64) ([]plugin.Frame, error) {
   255  	frames, err := f.ObjFile.SourceLine(frame)
   256  	if err != nil {
   257  		return nil, err
   258  	}
   259  	var pluginFrames []plugin.Frame
   260  	for _, f := range frames {
   261  		pluginFrames = append(pluginFrames, plugin.Frame(f))
   262  	}
   263  	return pluginFrames, nil
   264  }
   265  
   266  func (f *internalObjFile) Symbols(r *regexp.Regexp, addr uint64) ([]*plugin.Sym, error) {
   267  	syms, err := f.ObjFile.Symbols(r, addr)
   268  	if err != nil {
   269  		return nil, err
   270  	}
   271  	var pluginSyms []*plugin.Sym
   272  	for _, s := range syms {
   273  		ps := plugin.Sym(*s)
   274  		pluginSyms = append(pluginSyms, &ps)
   275  	}
   276  	return pluginSyms, nil
   277  }
   278  
   279  func (o *internalObjTool) Disasm(file string, start, end uint64) ([]plugin.Inst, error) {
   280  	insts, err := o.ObjTool.Disasm(file, start, end)
   281  	if err != nil {
   282  		return nil, err
   283  	}
   284  	var pluginInst []plugin.Inst
   285  	for _, inst := range insts {
   286  		pluginInst = append(pluginInst, plugin.Inst(inst))
   287  	}
   288  	return pluginInst, nil
   289  }
   290  
   291  // internalSymbolizer is a wrapper to map from the pprof external
   292  // interface to the internal interface.
   293  type internalSymbolizer struct {
   294  	Symbolizer
   295  }
   296  
   297  func (s *internalSymbolizer) Symbolize(mode string, srcs plugin.MappingSources, prof *profile.Profile) error {
   298  	isrcs := MappingSources{}
   299  	for m, s := range srcs {
   300  		isrcs[m] = s
   301  	}
   302  	return s.Symbolizer.Symbolize(mode, isrcs, prof)
   303  }
   304  

View as plain text