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