cmd/pprof: doc about -alloc_space in Go 1.9

[pierrre]

What version of Go are you using (go version)?

go version go1.9beta1 linux/amd64

What operating system and processor architecture are you using (go env)?

GOARCH="amd64"
GOBIN=""
GOEXE=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOOS="linux"
GOPATH="/home/pierre/go"
GORACE=""
GOROOT="/home/pierre/.gimme/versions/go1.9beta1.src"
GOTOOLDIR="/home/pierre/.gimme/versions/go1.9beta1.src/pkg/tool/linux_amd64"
GCCGO="gccgo"
CC="gcc"
GOGCCFLAGS="-fPIC -m64 -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build452270547=/tmp/go-build -gno-record-gcc-switches"
CXX="g++"
CGO_ENABLED="1"
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"

What did you do?

go tool pprof

What did you expect to see?

Some doc about the flag -alloc_space, like in Go 1.8

What did you see instead?

Nothing about -allocs_space

[bradfitz]

Did it get lost in an update from upstream, or...?

[josharian]

I noticed the same thing, in #19927.

[vcabbage]

The usage output changed significantly when pprof was vendored in 7844ef4.

The pprof package defines a FlagSet interface with a ExtraUsage() string method that can be used to add additional text to the usage.

The missing flags are added to this interface before the usage is printed, but the default ExtraUsage() implementation returns an empty string.

Diff

-usage: pprof [options] [binary] <profile source> ...
-Output format (only set one):
-  -callgrind        Outputs a graph in callgrind format
-  -disasm=p         Output annotated assembly for functions matching regexp or address
-  -dot              Outputs a graph in DOT format
-  -eog              Visualize graph through eog
-  -evince           Visualize graph through evince
-  -gif              Outputs a graph image in GIF format
-  -gv               Visualize graph through gv
-  -list=p           Output annotated source for functions matching regexp
-  -pdf              Outputs a graph in PDF format
-  -peek=p           Output callers/callees of functions matching regexp
-  -png              Outputs a graph image in PNG format
-  -proto            Outputs the profile in compressed protobuf format
-  -ps               Outputs a graph in PS format
-  -raw              Outputs a text representation of the raw profile
-  -svg              Outputs a graph in SVG format
-  -tags             Outputs all tags in the profile
-  -text             Outputs top entries in text form
-  -top              Outputs top entries in text form
-  -tree             Outputs a text rendering of call graph
-  -web              Visualize graph through web browser
-  -weblist=p        Output annotated source in HTML for functions matching regexp or address
-Output file parameters (for file-based output formats):
-  -output=f         Generate output on file f (stdout by default)
-Output granularity (only set one):
-  -functions        Report at function level [default]
-  -files            Report at source file level
-  -lines            Report at source line level
-  -addresses        Report at address level
-Comparison options:
-  -base <profile>   Show delta from this profile
-  -drop_negative    Ignore negative differences
-Sorting options:
-  -cum              Sort by cumulative data
+usage: pprof [options] [-base source] [binary] <source> ...
+  Output formats (select only one):
+    -callgrind       Outputs a graph in callgrind format
+    -comments        Output all profile comments
+    -disasm          Output assembly listings annotated with samples
+    -dot             Outputs a graph in DOT format
+    -eog             Visualize graph through eog
+    -evince          Visualize graph through evince
+    -gif             Outputs a graph image in GIF format
+    -gv              Visualize graph through gv
+    -kcachegrind     Visualize report in KCachegrind
+    -list            Output annotated source for functions matching regexp
+    -pdf             Outputs a graph in PDF format
+    -peek            Output callers/callees of functions matching regexp
+    -png             Outputs a graph image in PNG format
+    -proto           Outputs the profile in compressed protobuf format
+    -ps              Outputs a graph in PS format
+    -raw             Outputs a text representation of the raw profile
+    -svg             Outputs a graph in SVG format
+    -tags            Outputs all tags in the profile
+    -text            Outputs top entries in text form
+    -top             Outputs top entries in text form
+    -topproto        Outputs top entries in compressed protobuf format
+    -traces          Outputs all profile samples in text form
+    -tree            Outputs a text rendering of call graph
+    -web             Visualize graph through web browser
+    -weblist         Display annotated source in a web browser

-Dynamic profile options:
-  -seconds=N        Length of time for dynamic profiles
-Profile trimming options:
-  -nodecount=N      Max number of nodes to show
-  -nodefraction=f   Hide nodes below <f>*total
-  -edgefraction=f   Hide edges below <f>*total
-Sample value selection option (by index):
-  -sample_index      Index of sample value to display
-  -mean              Average sample value over first value
-Sample value selection option (for heap profiles):
-  -inuse_space      Display in-use memory size
-  -inuse_objects    Display in-use object counts
-  -alloc_space      Display allocated memory size
-  -alloc_objects    Display allocated object counts
-Sample value selection option (for contention profiles):
-  -total_delay      Display total delay at each region
-  -contentions      Display number of delays at each region
-  -mean_delay       Display mean delay at each region
-Filtering options:
-  -runtime          Show runtime call frames in memory profiles
-  -focus=r          Restricts to paths going through a node matching regexp
-  -ignore=r         Skips paths going through any nodes matching regexp
-  -tagfocus=r       Restrict to samples tagged with key:value matching regexp
-                    Restrict to samples with numeric tags in range (eg "32kb:1mb")
-  -tagignore=r      Discard samples tagged with key:value matching regexp
-                    Avoid samples with numeric tags in range (eg "1mb:")
-Miscellaneous:
-  -call_tree        Generate a context-sensitive call tree
-  -unit=u           Convert all samples to unit u for display
-  -divide_by=f      Scale all samples by dividing them by f
-  -buildid=id       Override build id for main binary in profile
-  -tools=path       Search path for object-level tools
-  -help             This message
-Environment Variables:
+  Options:
+    -call_tree       Create a context-sensitive call tree
+    -compact_labels  Show minimal headers
+    -divide_by       Ratio to divide all samples before visualization
+    -drop_negative   Ignore negative differences
+    -edgefraction    Hide edges below <f>*total
+    -focus           Restricts to samples going through a node matching regexp
+    -hide            Skips nodes matching regexp
+    -ignore          Skips paths going through any nodes matching regexp
+    -mean            Average sample value over first value (count)
+    -nodecount       Max number of nodes to show
+    -nodefraction    Hide nodes below <f>*total
+    -output          Output filename for file-based outputs
+    -positive_percentages Ignore negative samples when computing percentages
+    -prune_from      Drops any functions below the matched frame.
+    -relative_percentages Show percentages relative to focused subgraph
+    -sample_index    Sample value to report (0-based index or name)
+    -show            Only show nodes matching regexp
+    -source_path     Search path for source files
+    -tagfocus        Restrict to samples with tags in range or matched by regexp
+    -taghide         Skip tags matching this regexp
+    -tagignore       Discard samples with tags in range or matched by regexp
+    -tagshow         Only consider tags matching this regexp
+    -trim            Honor nodefraction/edgefraction/nodecount defaults
+    -unit            Measurement units to display
+
+  Option groups (only set one per group):
+    cumulative
+      -cum             Sort entries based on cumulative weight
+      -flat            Sort entries based on own weight
+    granularity
+      -addresses       Aggregate at the function level.
+      -addressnoinlines Aggregate at the function level, including functions' addresses in the output.
+      -files           Aggregate at the file level.
+      -functionnameonly Aggregate at the function level.
+      -functions       Aggregate at the function level.
+      -lines           Aggregate at the source code line level.
+      -noinlines       Aggregate at the function level.
+
+  Source options:
+    -seconds              Duration for time-based profile collection
+    -timeout              Timeout in seconds for profile collection
+    -buildid              Override build id for main binary
+    -base source          Source of profile to use as baseline
+    profile.pb.gz         Profile in compressed protobuf format
+    legacy_profile        Profile in legacy pprof format
+    http://host/profile   URL for profile handler to retrieve
+    -symbolize=           Controls source of symbol information
+      none                  Do not attempt symbolization
+      local                 Examine only local binaries
+      fastlocal             Only get function names from local binaries
+      remote                Do not examine local binaries
+      force                 Force re-symbolization
+    Binary                  Local path or build id of binary for symbolization
+
+
+  Misc options:
+   -tools                 Search path for object tools
+
+  Environment Variables:
    PPROF_TMPDIR       Location for saved profiles (default $HOME/pprof)
    PPROF_TOOLS        Search path for object-level tools
    PPROF_BINARY_PATH  Search path for local binary files
                       default: $HOME/pprof/binaries
                       finds binaries by $name and $buildid/$name
+   * On Windows, %USERPROFILE% is used instead of $HOME

[ianlancetaylor]

These flags are defined in the upstream sources, so it seems to me that the -help output should be updated in the upstream sources. I filed google/pprof#182. I'm going to close this issue.

[anacrolix]

These options still aren't shown in master.

[mvdan]

@anacrolix pprof is vendored in the Go tree, and it is updated regularly. Since the upstream issue was fixed 5 days ago, I guess the vendored copy hasn't been updated since. It will definitely be updated before 1.10 is released.