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 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 } 166 167 // A Sym describes a single symbol in an object file. 168 type Sym struct { 169 Name []string // names of symbol (many if symbol was dedup'ed) 170 File string // object file containing symbol 171 Start uint64 // start virtual address 172 End uint64 // virtual address of last byte in sym (Start+size-1) 173 } 174 175 // A UI manages user interactions. 176 type UI interface { 177 // Read returns a line of text (a command) read from the user. 178 // prompt is printed before reading the command. 179 ReadLine(prompt string) (string, error) 180 181 // Print shows a message to the user. 182 // It formats the text as fmt.Print would and adds a final \n if not already present. 183 // For line-based UI, Print writes to standard error. 184 // (Standard output is reserved for report data.) 185 Print(...interface{}) 186 187 // PrintErr shows an error message to the user. 188 // It formats the text as fmt.Print would and adds a final \n if not already present. 189 // For line-based UI, PrintErr writes to standard error. 190 PrintErr(...interface{}) 191 192 // IsTerminal returns whether the UI is known to be tied to an 193 // interactive terminal (as opposed to being redirected to a file). 194 IsTerminal() bool 195 196 // WantBrowser indicates whether a browser should be opened with the -http option. 197 WantBrowser() bool 198 199 // SetAutoComplete instructs the UI to call complete(cmd) to obtain 200 // the auto-completion of cmd, if the UI supports auto-completion at all. 201 SetAutoComplete(complete func(string) string) 202 } 203 204 // HTTPServerArgs contains arguments needed by an HTTP server that 205 // is exporting a pprof web interface. 206 type HTTPServerArgs struct { 207 // Hostport contains the http server address (derived from flags). 208 Hostport string 209 210 Host string // Host portion of Hostport 211 Port int // Port portion of Hostport 212 213 // Handlers maps from URL paths to the handler to invoke to 214 // serve that path. 215 Handlers map[string]http.Handler 216 } 217