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 specfied 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 // BoolVar, IntVar, Float64Var, and StringVar define new flags referencing 65 // a given pointer, like the functions of the same name in package flag. 66 BoolVar(pointer *bool, name string, def bool, usage string) 67 IntVar(pointer *int, name string, def int, usage string) 68 Float64Var(pointer *float64, name string, def float64, usage string) 69 StringVar(pointer *string, name string, def string, usage string) 70 71 // StringList is similar to String but allows multiple values for a 72 // single flag 73 StringList(name string, def string, usage string) *[]*string 74 75 // ExtraUsage returns any additional text that should be printed after the 76 // standard usage message. The extra usage message returned includes all text 77 // added with AddExtraUsage(). 78 // The typical use of ExtraUsage is to show any custom flags defined by the 79 // specific pprof plugins being used. 80 ExtraUsage() string 81 82 // AddExtraUsage appends additional text to the end of the extra usage message. 83 AddExtraUsage(eu string) 84 85 // Parse initializes the flags with their values for this run 86 // and returns the non-flag command line arguments. 87 // If an unknown flag is encountered or there are no arguments, 88 // Parse should call usage and return nil. 89 Parse(usage func()) []string 90 } 91 92 // A Fetcher reads and returns the profile named by src. src can be a 93 // local file path or a URL. duration and timeout are units specified 94 // by the end user, or 0 by default. duration refers to the length of 95 // the profile collection, if applicable, and timeout is the amount of 96 // time to wait for a profile before returning an error. Returns the 97 // fetched profile, the URL of the actual source of the profile, or an 98 // error. 99 type Fetcher interface { 100 Fetch(src string, duration, timeout time.Duration) (*profile.Profile, string, error) 101 } 102 103 // A Symbolizer introduces symbol information into a profile. 104 type Symbolizer interface { 105 Symbolize(mode string, srcs MappingSources, prof *profile.Profile) error 106 } 107 108 // MappingSources map each profile.Mapping to the source of the profile. 109 // The key is either Mapping.File or Mapping.BuildId. 110 type MappingSources map[string][]struct { 111 Source string // URL of the source the mapping was collected from 112 Start uint64 // delta applied to addresses from this source (to represent Merge adjustments) 113 } 114 115 // An ObjTool inspects shared libraries and executable files. 116 type ObjTool interface { 117 // Open opens the named object file. If the object is a shared 118 // library, start/limit/offset are the addresses where it is mapped 119 // into memory in the address space being inspected. 120 Open(file string, start, limit, offset uint64) (ObjFile, error) 121 122 // Disasm disassembles the named object file, starting at 123 // the start address and stopping at (before) the end address. 124 Disasm(file string, start, end uint64) ([]Inst, error) 125 } 126 127 // An Inst is a single instruction in an assembly listing. 128 type Inst struct { 129 Addr uint64 // virtual address of instruction 130 Text string // instruction text 131 Function string // function name 132 File string // source file 133 Line int // source line 134 } 135 136 // An ObjFile is a single object file: a shared library or executable. 137 type ObjFile interface { 138 // Name returns the underlyinf file name, if available 139 Name() string 140 141 // Base returns the base address to use when looking up symbols in the file. 142 Base() uint64 143 144 // BuildID returns the GNU build ID of the file, or an empty string. 145 BuildID() string 146 147 // SourceLine reports the source line information for a given 148 // address in the file. Due to inlining, the source line information 149 // is in general a list of positions representing a call stack, 150 // with the leaf function first. 151 SourceLine(addr uint64) ([]Frame, error) 152 153 // Symbols returns a list of symbols in the object file. 154 // If r is not nil, Symbols restricts the list to symbols 155 // with names matching the regular expression. 156 // If addr is not zero, Symbols restricts the list to symbols 157 // containing that address. 158 Symbols(r *regexp.Regexp, addr uint64) ([]*Sym, error) 159 160 // Close closes the file, releasing associated resources. 161 Close() error 162 } 163 164 // A Frame describes a single line in a source file. 165 type Frame struct { 166 Func string // name of function 167 File string // source file name 168 Line int // line in file 169 } 170 171 // A Sym describes a single symbol in an object file. 172 type Sym struct { 173 Name []string // names of symbol (many if symbol was dedup'ed) 174 File string // object file containing symbol 175 Start uint64 // start virtual address 176 End uint64 // virtual address of last byte in sym (Start+size-1) 177 } 178 179 // A UI manages user interactions. 180 type UI interface { 181 // Read returns a line of text (a command) read from the user. 182 // prompt is printed before reading the command. 183 ReadLine(prompt string) (string, error) 184 185 // Print shows a message to the user. 186 // It formats the text as fmt.Print would and adds a final \n if not already present. 187 // For line-based UI, Print writes to standard error. 188 // (Standard output is reserved for report data.) 189 Print(...interface{}) 190 191 // PrintErr shows an error message to the user. 192 // It formats the text as fmt.Print would and adds a final \n if not already present. 193 // For line-based UI, PrintErr writes to standard error. 194 PrintErr(...interface{}) 195 196 // IsTerminal returns whether the UI is known to be tied to an 197 // interactive terminal (as opposed to being redirected to a file). 198 IsTerminal() bool 199 200 // WantBrowser indicates whether a browser should be opened with the -http option. 201 WantBrowser() bool 202 203 // SetAutoComplete instructs the UI to call complete(cmd) to obtain 204 // the auto-completion of cmd, if the UI supports auto-completion at all. 205 SetAutoComplete(complete func(string) string) 206 } 207 208 // HTTPServerArgs contains arguments needed by an HTTP server that 209 // is exporting a pprof web interface. 210 type HTTPServerArgs struct { 211 // Hostport contains the http server address (derived from flags). 212 Hostport string 213 214 Host string // Host portion of Hostport 215 Port int // Port portion of Hostport 216 217 // Handlers maps from URL paths to the handler to invoke to 218 // serve that path. 219 Handlers map[string]http.Handler 220 } 221