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. 16package plugin 17 18import ( 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. 28type 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. 50type 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. 56type 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. 92type 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. 97type 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. 103type 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. 109type 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. 113 Open(file string, start, limit, offset uint64) (ObjFile, error) 114 115 // Disasm disassembles the named object file, starting at 116 // the start address and stopping at (before) the end address. 117 Disasm(file string, start, end uint64, intelSyntax bool) ([]Inst, error) 118} 119 120// An Inst is a single instruction in an assembly listing. 121type Inst struct { 122 Addr uint64 // virtual address of instruction 123 Text string // instruction text 124 Function string // function name 125 File string // source file 126 Line int // source line 127} 128 129// An ObjFile is a single object file: a shared library or executable. 130type ObjFile interface { 131 // Name returns the underlyinf file name, if available 132 Name() string 133 134 // Base returns the base address to use when looking up symbols in the file. 135 Base() uint64 136 137 // BuildID returns the GNU build ID of the file, or an empty string. 138 BuildID() string 139 140 // SourceLine reports the source line information for a given 141 // address in the file. Due to inlining, the source line information 142 // is in general a list of positions representing a call stack, 143 // with the leaf function first. 144 SourceLine(addr uint64) ([]Frame, error) 145 146 // Symbols returns a list of symbols in the object file. 147 // If r is not nil, Symbols restricts the list to symbols 148 // with names matching the regular expression. 149 // If addr is not zero, Symbols restricts the list to symbols 150 // containing that address. 151 Symbols(r *regexp.Regexp, addr uint64) ([]*Sym, error) 152 153 // Close closes the file, releasing associated resources. 154 Close() error 155} 156 157// A Frame describes a single line in a source file. 158type Frame struct { 159 Func string // name of function 160 File string // source file name 161 Line int // line in file 162} 163 164// A Sym describes a single symbol in an object file. 165type Sym struct { 166 Name []string // names of symbol (many if symbol was dedup'ed) 167 File string // object file containing symbol 168 Start uint64 // start virtual address 169 End uint64 // virtual address of last byte in sym (Start+size-1) 170} 171 172// A UI manages user interactions. 173type UI interface { 174 // Read returns a line of text (a command) read from the user. 175 // prompt is printed before reading the command. 176 ReadLine(prompt string) (string, error) 177 178 // Print shows a message to the user. 179 // It formats the text as fmt.Print would and adds a final \n if not already present. 180 // For line-based UI, Print writes to standard error. 181 // (Standard output is reserved for report data.) 182 Print(...interface{}) 183 184 // PrintErr shows an error message to the user. 185 // It formats the text as fmt.Print would and adds a final \n if not already present. 186 // For line-based UI, PrintErr writes to standard error. 187 PrintErr(...interface{}) 188 189 // IsTerminal returns whether the UI is known to be tied to an 190 // interactive terminal (as opposed to being redirected to a file). 191 IsTerminal() bool 192 193 // WantBrowser indicates whether a browser should be opened with the -http option. 194 WantBrowser() bool 195 196 // SetAutoComplete instructs the UI to call complete(cmd) to obtain 197 // the auto-completion of cmd, if the UI supports auto-completion at all. 198 SetAutoComplete(complete func(string) string) 199} 200 201// HTTPServerArgs contains arguments needed by an HTTP server that 202// is exporting a pprof web interface. 203type HTTPServerArgs struct { 204 // Hostport contains the http server address (derived from flags). 205 Hostport string 206 207 Host string // Host portion of Hostport 208 Port int // Port portion of Hostport 209 210 // Handlers maps from URL paths to the handler to invoke to 211 // serve that path. 212 Handlers map[string]http.Handler 213} 214