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
15package driver
16
17import (
18	"errors"
19	"fmt"
20	"os"
21	"strings"
22
23	"github.com/google/pprof/internal/binutils"
24	"github.com/google/pprof/internal/plugin"
25)
26
27type source struct {
28	Sources   []string
29	ExecName  string
30	BuildID   string
31	Base      []string
32	DiffBase  bool
33	Normalize bool
34
35	Seconds            int
36	Timeout            int
37	Symbolize          string
38	HTTPHostport       string
39	HTTPDisableBrowser bool
40	Comment            string
41}
42
43// parseFlags parses the command lines through the specified flags package
44// and returns the source of the profile and optionally the command
45// for the kind of report to generate (nil for interactive use).
46func parseFlags(o *plugin.Options) (*source, []string, error) {
47	flag := o.Flagset
48	// Comparisons.
49	flagDiffBase := flag.StringList("diff_base", "", "Source of base profile for comparison")
50	flagBase := flag.StringList("base", "", "Source of base profile for profile subtraction")
51	// Source options.
52	flagSymbolize := flag.String("symbolize", "", "Options for profile symbolization")
53	flagBuildID := flag.String("buildid", "", "Override build id for first mapping")
54	flagTimeout := flag.Int("timeout", -1, "Timeout in seconds for fetching a profile")
55	flagAddComment := flag.String("add_comment", "", "Annotation string to record in the profile")
56	// CPU profile options
57	flagSeconds := flag.Int("seconds", -1, "Length of time for dynamic profiles")
58	// Heap profile options
59	flagInUseSpace := flag.Bool("inuse_space", false, "Display in-use memory size")
60	flagInUseObjects := flag.Bool("inuse_objects", false, "Display in-use object counts")
61	flagAllocSpace := flag.Bool("alloc_space", false, "Display allocated memory size")
62	flagAllocObjects := flag.Bool("alloc_objects", false, "Display allocated object counts")
63	// Contention profile options
64	flagTotalDelay := flag.Bool("total_delay", false, "Display total delay at each region")
65	flagContentions := flag.Bool("contentions", false, "Display number of delays at each region")
66	flagMeanDelay := flag.Bool("mean_delay", false, "Display mean delay at each region")
67	flagTools := flag.String("tools", os.Getenv("PPROF_TOOLS"), "Path for object tool pathnames")
68
69	flagHTTP := flag.String("http", "", "Present interactive web UI at the specified http host:port")
70	flagNoBrowser := flag.Bool("no_browser", false, "Skip opening a browswer for the interactive web UI")
71
72	// Flags that set configuration properties.
73	cfg := currentConfig()
74	configFlagSetter := installConfigFlags(flag, &cfg)
75
76	flagCommands := make(map[string]*bool)
77	flagParamCommands := make(map[string]*string)
78	for name, cmd := range pprofCommands {
79		if cmd.hasParam {
80			flagParamCommands[name] = flag.String(name, "", "Generate a report in "+name+" format, matching regexp")
81		} else {
82			flagCommands[name] = flag.Bool(name, false, "Generate a report in "+name+" format")
83		}
84	}
85
86	args := flag.Parse(func() {
87		o.UI.Print(usageMsgHdr +
88			usage(true) +
89			usageMsgSrc +
90			flag.ExtraUsage() +
91			usageMsgVars)
92	})
93	if len(args) == 0 {
94		return nil, nil, errors.New("no profile source specified")
95	}
96
97	var execName string
98	// Recognize first argument as an executable or buildid override.
99	if len(args) > 1 {
100		arg0 := args[0]
101		if file, err := o.Obj.Open(arg0, 0, ^uint64(0), 0); err == nil {
102			file.Close()
103			execName = arg0
104			args = args[1:]
105		} else if *flagBuildID == "" && isBuildID(arg0) {
106			*flagBuildID = arg0
107			args = args[1:]
108		}
109	}
110
111	// Apply any specified flags to cfg.
112	if err := configFlagSetter(); err != nil {
113		return nil, nil, err
114	}
115
116	cmd, err := outputFormat(flagCommands, flagParamCommands)
117	if err != nil {
118		return nil, nil, err
119	}
120	if cmd != nil && *flagHTTP != "" {
121		return nil, nil, errors.New("-http is not compatible with an output format on the command line")
122	}
123
124	if *flagNoBrowser && *flagHTTP == "" {
125		return nil, nil, errors.New("-no_browser only makes sense with -http")
126	}
127
128	si := cfg.SampleIndex
129	si = sampleIndex(flagTotalDelay, si, "delay", "-total_delay", o.UI)
130	si = sampleIndex(flagMeanDelay, si, "delay", "-mean_delay", o.UI)
131	si = sampleIndex(flagContentions, si, "contentions", "-contentions", o.UI)
132	si = sampleIndex(flagInUseSpace, si, "inuse_space", "-inuse_space", o.UI)
133	si = sampleIndex(flagInUseObjects, si, "inuse_objects", "-inuse_objects", o.UI)
134	si = sampleIndex(flagAllocSpace, si, "alloc_space", "-alloc_space", o.UI)
135	si = sampleIndex(flagAllocObjects, si, "alloc_objects", "-alloc_objects", o.UI)
136	cfg.SampleIndex = si
137
138	if *flagMeanDelay {
139		cfg.Mean = true
140	}
141
142	source := &source{
143		Sources:            args,
144		ExecName:           execName,
145		BuildID:            *flagBuildID,
146		Seconds:            *flagSeconds,
147		Timeout:            *flagTimeout,
148		Symbolize:          *flagSymbolize,
149		HTTPHostport:       *flagHTTP,
150		HTTPDisableBrowser: *flagNoBrowser,
151		Comment:            *flagAddComment,
152	}
153
154	if err := source.addBaseProfiles(*flagBase, *flagDiffBase); err != nil {
155		return nil, nil, err
156	}
157
158	normalize := cfg.Normalize
159	if normalize && len(source.Base) == 0 {
160		return nil, nil, errors.New("must have base profile to normalize by")
161	}
162	source.Normalize = normalize
163
164	if bu, ok := o.Obj.(*binutils.Binutils); ok {
165		bu.SetTools(*flagTools)
166	}
167
168	setCurrentConfig(cfg)
169	return source, cmd, nil
170}
171
172// addBaseProfiles adds the list of base profiles or diff base profiles to
173// the source. This function will return an error if both base and diff base
174// profiles are specified.
175func (source *source) addBaseProfiles(flagBase, flagDiffBase []*string) error {
176	base, diffBase := dropEmpty(flagBase), dropEmpty(flagDiffBase)
177	if len(base) > 0 && len(diffBase) > 0 {
178		return errors.New("-base and -diff_base flags cannot both be specified")
179	}
180
181	source.Base = base
182	if len(diffBase) > 0 {
183		source.Base, source.DiffBase = diffBase, true
184	}
185	return nil
186}
187
188// dropEmpty list takes a slice of string pointers, and outputs a slice of
189// non-empty strings associated with the flag.
190func dropEmpty(list []*string) []string {
191	var l []string
192	for _, s := range list {
193		if *s != "" {
194			l = append(l, *s)
195		}
196	}
197	return l
198}
199
200// installConfigFlags creates command line flags for configuration
201// fields and returns a function which can be called after flags have
202// been parsed to copy any flags specified on the command line to
203// *cfg.
204func installConfigFlags(flag plugin.FlagSet, cfg *config) func() error {
205	// List of functions for setting the different parts of a config.
206	var setters []func()
207	var err error // Holds any errors encountered while running setters.
208
209	for _, field := range configFields {
210		n := field.name
211		help := configHelp[n]
212		var setter func()
213		switch ptr := cfg.fieldPtr(field).(type) {
214		case *bool:
215			f := flag.Bool(n, *ptr, help)
216			setter = func() { *ptr = *f }
217		case *int:
218			f := flag.Int(n, *ptr, help)
219			setter = func() { *ptr = *f }
220		case *float64:
221			f := flag.Float64(n, *ptr, help)
222			setter = func() { *ptr = *f }
223		case *string:
224			if len(field.choices) == 0 {
225				f := flag.String(n, *ptr, help)
226				setter = func() { *ptr = *f }
227			} else {
228				// Make a separate flag per possible choice.
229				// Set all flags to initially false so we can
230				// identify conflicts.
231				bools := make(map[string]*bool)
232				for _, choice := range field.choices {
233					bools[choice] = flag.Bool(choice, false, configHelp[choice])
234				}
235				setter = func() {
236					var set []string
237					for k, v := range bools {
238						if *v {
239							set = append(set, k)
240						}
241					}
242					switch len(set) {
243					case 0:
244						// Leave as default value.
245					case 1:
246						*ptr = set[0]
247					default:
248						err = fmt.Errorf("conflicting options set: %v", set)
249					}
250				}
251			}
252		}
253		setters = append(setters, setter)
254	}
255
256	return func() error {
257		// Apply the setter for every flag.
258		for _, setter := range setters {
259			setter()
260			if err != nil {
261				return err
262			}
263		}
264		return nil
265	}
266}
267
268// isBuildID determines if the profile may contain a build ID, by
269// checking that it is a string of hex digits.
270func isBuildID(id string) bool {
271	return strings.Trim(id, "0123456789abcdefABCDEF") == ""
272}
273
274func sampleIndex(flag *bool, si string, sampleType, option string, ui plugin.UI) string {
275	if *flag {
276		if si == "" {
277			return sampleType
278		}
279		ui.PrintErr("Multiple value selections, ignoring ", option)
280	}
281	return si
282}
283
284func outputFormat(bcmd map[string]*bool, acmd map[string]*string) (cmd []string, err error) {
285	for n, b := range bcmd {
286		if *b {
287			if cmd != nil {
288				return nil, errors.New("must set at most one output format")
289			}
290			cmd = []string{n}
291		}
292	}
293	for n, s := range acmd {
294		if *s != "" {
295			if cmd != nil {
296				return nil, errors.New("must set at most one output format")
297			}
298			cmd = []string{n, *s}
299		}
300	}
301	return cmd, nil
302}
303
304var usageMsgHdr = `usage:
305
306Produce output in the specified format.
307
308   pprof <format> [options] [binary] <source> ...
309
310Omit the format to get an interactive shell whose commands can be used
311to generate various views of a profile
312
313   pprof [options] [binary] <source> ...
314
315Omit the format and provide the "-http" flag to get an interactive web
316interface at the specified host:port that can be used to navigate through
317various views of a profile.
318
319   pprof -http [host]:[port] [options] [binary] <source> ...
320
321Details:
322`
323
324var usageMsgSrc = "\n\n" +
325	"  Source options:\n" +
326	"    -seconds              Duration for time-based profile collection\n" +
327	"    -timeout              Timeout in seconds for profile collection\n" +
328	"    -buildid              Override build id for main binary\n" +
329	"    -add_comment          Free-form annotation to add to the profile\n" +
330	"                          Displayed on some reports or with pprof -comments\n" +
331	"    -diff_base source     Source of base profile for comparison\n" +
332	"    -base source          Source of base profile for profile subtraction\n" +
333	"    profile.pb.gz         Profile in compressed protobuf format\n" +
334	"    legacy_profile        Profile in legacy pprof format\n" +
335	"    http://host/profile   URL for profile handler to retrieve\n" +
336	"    -symbolize=           Controls source of symbol information\n" +
337	"      none                  Do not attempt symbolization\n" +
338	"      local                 Examine only local binaries\n" +
339	"      fastlocal             Only get function names from local binaries\n" +
340	"      remote                Do not examine local binaries\n" +
341	"      force                 Force re-symbolization\n" +
342	"    Binary                  Local path or build id of binary for symbolization\n"
343
344var usageMsgVars = "\n\n" +
345	"  Misc options:\n" +
346	"   -http              Provide web interface at host:port.\n" +
347	"                      Host is optional and 'localhost' by default.\n" +
348	"                      Port is optional and a randomly available port by default.\n" +
349	"   -no_browser        Skip opening a browser for the interactive web UI.\n" +
350	"   -tools             Search path for object tools\n" +
351	"\n" +
352	"  Legacy convenience options:\n" +
353	"   -inuse_space           Same as -sample_index=inuse_space\n" +
354	"   -inuse_objects         Same as -sample_index=inuse_objects\n" +
355	"   -alloc_space           Same as -sample_index=alloc_space\n" +
356	"   -alloc_objects         Same as -sample_index=alloc_objects\n" +
357	"   -total_delay           Same as -sample_index=delay\n" +
358	"   -contentions           Same as -sample_index=contentions\n" +
359	"   -mean_delay            Same as -mean -sample_index=delay\n" +
360	"\n" +
361	"  Environment Variables:\n" +
362	"   PPROF_TMPDIR       Location for saved profiles (default $HOME/pprof)\n" +
363	"   PPROF_TOOLS        Search path for object-level tools\n" +
364	"   PPROF_BINARY_PATH  Search path for local binary files\n" +
365	"                      default: $HOME/pprof/binaries\n" +
366	"                      searches $name, $path, $buildid/$name, $path/$buildid\n" +
367	"   * On Windows, %USERPROFILE% is used instead of $HOME"
368