plugin.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 plugin defines the plugin implementations that the main pprof driver requires.
    16  package plugin
    17  
    18  import (
    19  	"io"
    20  	"net/http"
    21  	"regexp"
    22  	"time"
    23  
    24  	"github.com/google/pprof/profile"
    25  )
    26  
    27  // Options groups all the optional plugins into pprof.
    28  type Options struct {
    29  	Writer  Writer
    30  	Flagset FlagSet
    31  	Fetch   Fetcher
    32  	Sym     Symbolizer
    33  	Obj     ObjTool
    34  	UI      UI
    35  
    36  	// HTTPServer is a function that should block serving http requests,
    37  	// including the handlers specified in args.  If non-nil, pprof will
    38  	// invoke this function if necessary to provide a web interface.
    39  	//
    40  	// If HTTPServer is nil, pprof will use its own internal HTTP server.
    41  	//
    42  	// A common use for a custom HTTPServer is to provide custom
    43  	// authentication checks.
    44  	HTTPServer    func(args *HTTPServerArgs) error
    45  	HTTPTransport http.RoundTripper
    46  }
    47  
    48  // Writer provides a mechanism to write data under a certain name,
    49  // typically a filename.
    50  type Writer interface {
    51  	Open(name string) (io.WriteCloser, error)
    52  }
    53  
    54  // A FlagSet creates and parses command-line flags.
    55  // It is similar to the standard flag.FlagSet.
    56  type FlagSet interface {
    57  	// Bool, Int, Float64, and String define new flags,
    58  	// like the functions of the same name in package flag.
    59  	Bool(name string, def bool, usage string) *bool
    60  	Int(name string, def int, usage string) *int
    61  	Float64(name string, def float64, usage string) *float64
    62  	String(name string, def string, usage string) *string
    63  
    64  	// StringList is similar to String but allows multiple values for a
    65  	// single flag
    66  	StringList(name string, def string, usage string) *[]*string
    67  
    68  	// ExtraUsage returns any additional text that should be printed after the
    69  	// standard usage message. The extra usage message returned includes all text
    70  	// added with AddExtraUsage().
    71  	// The typical use of ExtraUsage is to show any custom flags defined by the
    72  	// specific pprof plugins being used.
    73  	ExtraUsage() string
    74  
    75  	// AddExtraUsage appends additional text to the end of the extra usage message.
    76  	AddExtraUsage(eu string)
    77  
    78  	// Parse initializes the flags with their values for this run
    79  	// and returns the non-flag command line arguments.
    80  	// If an unknown flag is encountered or there are no arguments,
    81  	// Parse should call usage and return nil.
    82  	Parse(usage func()) []string
    83  }
    84  
    85  // A Fetcher reads and returns the profile named by src. src can be a
    86  // local file path or a URL. duration and timeout are units specified
    87  // by the end user, or 0 by default. duration refers to the length of
    88  // the profile collection, if applicable, and timeout is the amount of
    89  // time to wait for a profile before returning an error. Returns the
    90  // fetched profile, the URL of the actual source of the profile, or an
    91  // error.
    92  type Fetcher interface {
    93  	Fetch(src string, duration, timeout time.Duration) (*profile.Profile, string, error)
    94  }
    95  
    96  // A Symbolizer introduces symbol information into a profile.
    97  type Symbolizer interface {
    98  	Symbolize(mode string, srcs MappingSources, prof *profile.Profile) error
    99  }
   100  
   101  // MappingSources map each profile.Mapping to the source of the profile.
   102  // The key is either Mapping.File or Mapping.BuildId.
   103  type MappingSources map[string][]struct {
   104  	Source string // URL of the source the mapping was collected from
   105  	Start  uint64 // delta applied to addresses from this source (to represent Merge adjustments)
   106  }
   107  
   108  // An ObjTool inspects shared libraries and executable files.
   109  type ObjTool interface {
   110  	// Open opens the named object file. If the object is a shared
   111  	// library, start/limit/offset are the addresses where it is mapped
   112  	// into memory in the address space being inspected. If the object
   113  	// is a linux kernel, relocationSymbol is the name of the symbol
   114  	// corresponding to the start address.
   115  	Open(file string, start, limit, offset uint64, relocationSymbol string) (ObjFile, error)
   116  
   117  	// Disasm disassembles the named object file, starting at
   118  	// the start address and stopping at (before) the end address.
   119  	Disasm(file string, start, end uint64, intelSyntax bool) ([]Inst, error)
   120  }
   121  
   122  // An Inst is a single instruction in an assembly listing.
   123  type Inst struct {
   124  	Addr     uint64 // virtual address of instruction
   125  	Text     string // instruction text
   126  	Function string // function name
   127  	File     string // source file
   128  	Line     int    // source line
   129  }
   130  
   131  // An ObjFile is a single object file: a shared library or executable.
   132  type ObjFile interface {
   133  	// Name returns the underlyinf file name, if available
   134  	Name() string
   135  
   136  	// ObjAddr returns the objdump (linker) address corresponding to a runtime
   137  	// address, and an error.
   138  	ObjAddr(addr uint64) (uint64, error)
   139  
   140  	// BuildID returns the GNU build ID of the file, or an empty string.
   141  	BuildID() string
   142  
   143  	// SourceLine reports the source line information for a given
   144  	// address in the file. Due to inlining, the source line information
   145  	// is in general a list of positions representing a call stack,
   146  	// with the leaf function first.
   147  	SourceLine(addr uint64) ([]Frame, error)
   148  
   149  	// Symbols returns a list of symbols in the object file.
   150  	// If r is not nil, Symbols restricts the list to symbols
   151  	// with names matching the regular expression.
   152  	// If addr is not zero, Symbols restricts the list to symbols
   153  	// containing that address.
   154  	Symbols(r *regexp.Regexp, addr uint64) ([]*Sym, error)
   155  
   156  	// Close closes the file, releasing associated resources.
   157  	Close() error
   158  }
   159  
   160  // A Frame describes a location in a single line in a source file.
   161  type Frame struct {
   162  	Func          string // name of function
   163  	File          string // source file name
   164  	Line          int    // line in file
   165  	Column        int    // column in line (if available)
   166  	StartLine     int    // start line of function (if available)
   167  }
   168  
   169  // A Sym describes a single symbol in an object file.
   170  type Sym struct {
   171  	Name  []string // names of symbol (many if symbol was dedup'ed)
   172  	File  string   // object file containing symbol
   173  	Start uint64   // start virtual address
   174  	End   uint64   // virtual address of last byte in sym (Start+size-1)
   175  }
   176  
   177  // A UI manages user interactions.
   178  type UI interface {
   179  	// ReadLine returns a line of text (a command) read from the user.
   180  	// prompt is printed before reading the command.
   181  	ReadLine(prompt string) (string, error)
   182  
   183  	// Print shows a message to the user.
   184  	// It formats the text as fmt.Print would and adds a final \n if not already present.
   185  	// For line-based UI, Print writes to standard error.
   186  	// (Standard output is reserved for report data.)
   187  	Print(...interface{})
   188  
   189  	// PrintErr shows an error message to the user.
   190  	// It formats the text as fmt.Print would and adds a final \n if not already present.
   191  	// For line-based UI, PrintErr writes to standard error.
   192  	PrintErr(...interface{})
   193  
   194  	// IsTerminal returns whether the UI is known to be tied to an
   195  	// interactive terminal (as opposed to being redirected to a file).
   196  	IsTerminal() bool
   197  
   198  	// WantBrowser indicates whether a browser should be opened with the -http option.
   199  	WantBrowser() bool
   200  
   201  	// SetAutoComplete instructs the UI to call complete(cmd) to obtain
   202  	// the auto-completion of cmd, if the UI supports auto-completion at all.
   203  	SetAutoComplete(complete func(string) string)
   204  }
   205  
   206  // HTTPServerArgs contains arguments needed by an HTTP server that
   207  // is exporting a pprof web interface.
   208  type HTTPServerArgs struct {
   209  	// Hostport contains the http server address (derived from flags).
   210  	Hostport string
   211  
   212  	Host string // Host portion of Hostport
   213  	Port int    // Port portion of Hostport
   214  
   215  	// Handlers maps from URL paths to the handler to invoke to
   216  	// serve that path.
   217  	Handlers map[string]http.Handler
   218  }
   219
View as plain text