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