gopls: commands to start/stop profiling, and a new benchmark metric

Total CPU used by gopls is a critical metric for our users, yet was not
previously captured in any benchmark. This change uses the new pprof
parsing utilities added in CL 507885 to instrument a cpu_seconds
benchmark metric, for now just associated with the DidChange benchmark.

This is achieved via new LSP commands that start and stop a profile. The
benchmark runner uses these commands to bracket the critical section of
the benchmark, then parses the resulting profile for its total sampled
CPU.

Additionally, the benchmark runner is updated to actually check for the
existence of the custom command before instrumenting the new metric.
This allows it to be compatible with testing older versions of gopls.
The same technique is adopted for memstats metrics.

I only instrumented BenchmarkDidChange, because the profile file schema
is getting truly out of hand. I'll try to simplify it before
instrumenting all the other benchmarks, but want to do that in a
separate CL.

For golang/go#60926

Change-Id: Ia082bad49e8d30c567a7c07e050511d49b93738b
Reviewed-on: https://go-review.googlesource.com/c/tools/+/508449
gopls-CI: kokoro <noreply+kokoro@google.com>
Reviewed-by: Alan Donovan <adonovan@google.com>
Run-TryBot: Robert Findley <rfindley@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>

Author: findleyr

gopls/doc/commands.md

@@ -364,14 +364,14 @@ Args:
 	// Optional: the address (including port) for the debug server to listen on.
 	// If not provided, the debug server will bind to "localhost:0", and the
 	// full debug URL will be contained in the result.
-	// 
+	//
 	// If there is more than one gopls instance along the serving path (i.e. you
 	// are using a daemon), each gopls instance will attempt to start debugging.
 	// If Addr specifies a port, only the daemon will be able to bind to that
 	// port, and each intermediate gopls instance will fail to start debugging.
 	// For this reason it is recommended not to specify a port (or equivalently,
 	// to specify ":0").
-	// 
+	//
 	// If the server was already debugging this field has no effect, and the
 	// result will contain the previously configured debug URL(s).
 	"Addr": string,
@@ -385,7 +385,7 @@ Result:
 	// The URLs to use to access the debug servers, for all gopls instances in
 	// the serving path. For the common case of a single gopls instance (i.e. no
 	// daemon), this will be exactly one address.
-	// 
+	//
 	// In the case of one or more gopls instances forwarding the LSP to a daemon,
 	// URLs will contain debug addresses for each server in the serving path, in
 	// serving order. The daemon debug address will be the last entry in the
@@ -396,6 +396,48 @@ Result:
 }
 ```
 
+### **start capturing a profile of gopls' execution.**
+Identifier: `gopls.start_profile`
+
+Start a new pprof profile. Before using the resulting file, profiling must
+be stopped with a corresponding call to StopProfile.
+
+This command is intended for internal use only, by the gopls benchmark
+runner.
+
+Args:
+
+```
+struct{}
+```
+
+Result:
+
+```
+struct{}
+```
+
+### **stop an ongoing profile.**
+Identifier: `gopls.stop_profile`
+
+This command is intended for internal use only, by the gopls benchmark
+runner.
+
+Args:
+
+```
+struct{}
+```
+
+Result:
+
+```
+{
+	// File is the profile file name.
+	"File": string,
+}
+```
+
 ### **Run test(s) (legacy)**
 Identifier: `gopls.test`
 

gopls/doc/generate.go

@@ -465,7 +465,11 @@ func structDoc(fields []*commandmeta.Field, level int) string {
 		if fld.Doc != "" && level == 0 {
 			doclines := strings.Split(fld.Doc, "\n")
 			for _, line := range doclines {
-				fmt.Fprintf(&b, "%s\t// %s\n", indent, line)
+				text := ""
+				if line != "" {
+					text = " " + line
+				}
+				fmt.Fprintf(&b, "%s\t//%s\n", indent, text)
 			}
 		}
 		tag := strings.Split(fld.JSONTag, ",")[0]

gopls/internal/lsp/command.go

@@ -16,6 +16,7 @@ import (
 	"os/exec"
 	"path/filepath"
 	"runtime"
+	"runtime/pprof"
 	"sort"
 	"strings"
 	"time"
@@ -843,6 +844,48 @@ func (c *commandHandler) StartDebugging(ctx context.Context, args command.Debugg
 	return result, nil
 }
 
+func (c *commandHandler) StartProfile(ctx context.Context, args command.StartProfileArgs) (result command.StartProfileResult, _ error) {
+	file, err := os.CreateTemp("", "gopls-profile-*")
+	if err != nil {
+		return result, fmt.Errorf("creating temp profile file: %v", err)
+	}
+
+	c.s.ongoingProfileMu.Lock()
+	defer c.s.ongoingProfileMu.Unlock()
+
+	if c.s.ongoingProfile != nil {
+		file.Close() // ignore error
+		return result, fmt.Errorf("profile already started (for %q)", c.s.ongoingProfile.Name())
+	}
+
+	if err := pprof.StartCPUProfile(file); err != nil {
+		file.Close() // ignore error
+		return result, fmt.Errorf("starting profile: %v", err)
+	}
+
+	c.s.ongoingProfile = file
+	return result, nil
+}
+
+func (c *commandHandler) StopProfile(ctx context.Context, args command.StopProfileArgs) (result command.StopProfileResult, _ error) {
+	c.s.ongoingProfileMu.Lock()
+	defer c.s.ongoingProfileMu.Unlock()
+
+	prof := c.s.ongoingProfile
+	c.s.ongoingProfile = nil
+
+	if prof == nil {
+		return result, fmt.Errorf("no ongoing profile")
+	}
+
+	pprof.StopCPUProfile()
+	if err := prof.Close(); err != nil {
+		return result, fmt.Errorf("closing profile file: %v", err)
+	}
+	result.File = prof.Name()
+	return result, nil
+}
+
 // Copy of pkgLoadConfig defined in internal/lsp/cmd/vulncheck.go
 // TODO(hyangah): decide where to define this.
 type pkgLoadConfig struct {

gopls/internal/lsp/command/command_gen.go

@@ -145,6 +145,21 @@ type Interface interface {
 	// address.
 	StartDebugging(context.Context, DebuggingArgs) (DebuggingResult, error)
 
+	// StartProfile: start capturing a profile of gopls' execution.
+	//
+	// Start a new pprof profile. Before using the resulting file, profiling must
+	// be stopped with a corresponding call to StopProfile.
+	//
+	// This command is intended for internal use only, by the gopls benchmark
+	// runner.
+	StartProfile(context.Context, StartProfileArgs) (StartProfileResult, error)
+
+	// StopProfile: stop an ongoing profile.
+	//
+	// This command is intended for internal use only, by the gopls benchmark
+	// runner.
+	StopProfile(context.Context, StopProfileArgs) (StopProfileResult, error)
+
 	// RunGovulncheck: Run govulncheck.
 	//
 	// Run vulnerability check (`govulncheck`).
@@ -327,6 +342,30 @@ type DebuggingResult struct {
 	URLs []string
 }
 
+// StartProfileArgs holds the arguments to the StartProfile command.
+//
+// It is a placeholder for future compatibility.
+type StartProfileArgs struct {
+}
+
+// StartProfileResult holds the result of the StartProfile command.
+//
+// It is a placeholder for future compatibility.
+type StartProfileResult struct {
+}
+
+// StopProfileArgs holds the arguments to the StopProfile command.
+//
+// It is a placeholder for future compatibility.
+type StopProfileArgs struct {
+}
+
+// StopProfileResult holds the result to the StopProfile command.
+type StopProfileResult struct {
+	// File is the profile file name.
+	File string
+}
+
 type ResetGoModDiagnosticsArgs struct {
 	URIArg
 

gopls/internal/lsp/command/interface.go

@@ -305,6 +305,16 @@ func (e *Editor) initialize(ctx context.Context) error {
 	return nil
 }
 
+// HasCommand reports whether the connected server supports the command with the given ID.
+func (e *Editor) HasCommand(id string) bool {
+	for _, command := range e.serverCapabilities.ExecuteCommandProvider.Commands {
+		if command == id {
+			return true
+		}
+	}
+	return false
+}
+
 // makeWorkspaceFolders creates a slice of workspace folders to use for
 // this editing session, based on the editor configuration.
 func makeWorkspaceFolders(sandbox *Sandbox, paths []string) (folders []protocol.WorkspaceFolder) {

gopls/internal/lsp/fake/editor.go

@@ -370,6 +370,41 @@ func (e *Env) ExecuteCommand(params *protocol.ExecuteCommandParams, result inter
 	}
 }
 
+// StartProfile starts a CPU profile with the given name, using the
+// gopls.start_profile custom command. It calls t.Fatal on any error.
+//
+// The resulting stop function must be called to stop profiling (using the
+// gopls.stop_profile custom command).
+func (e *Env) StartProfile() (stop func() string) {
+	// TODO(golang/go#61217): revisit the ergonomics of these command APIs.
+	//
+	// This would be a lot simpler if we generated params constructors.
+	args, err := command.MarshalArgs(command.StartProfileArgs{})
+	if err != nil {
+		e.T.Fatal(err)
+	}
+	params := &protocol.ExecuteCommandParams{
+		Command:   command.StartProfile.ID(),
+		Arguments: args,
+	}
+	var result command.StartProfileResult
+	e.ExecuteCommand(params, &result)
+
+	return func() string {
+		stopArgs, err := command.MarshalArgs(command.StopProfileArgs{})
+		if err != nil {
+			e.T.Fatal(err)
+		}
+		stopParams := &protocol.ExecuteCommandParams{
+			Command:   command.StopProfile.ID(),
+			Arguments: stopArgs,
+		}
+		var result command.StopProfileResult
+		e.ExecuteCommand(stopParams, &result)
+		return result.File
+	}
+}
+
 // InlayHints calls textDocument/inlayHints for the given path, calling t.Fatal on
 // any error.
 func (e *Env) InlayHints(path string) []protocol.InlayHint {

gopls/internal/lsp/regtest/wrappers.go

@@ -10,6 +10,7 @@ package lsp
 import (
 	"context"
 	"fmt"
+	"os"
 	"sync"
 
 	"golang.org/x/tools/gopls/internal/lsp/cache"
@@ -109,6 +110,11 @@ type Server struct {
 	// report with an error message.
 	criticalErrorStatusMu sync.Mutex
 	criticalErrorStatus   *progress.WorkDone
+
+	// Track an ongoing CPU profile created with the StartProfile command and
+	// terminated with the StopProfile command.
+	ongoingProfileMu sync.Mutex
+	ongoingProfile   *os.File // if non-nil, an ongoing profile is writing to this file
 }
 
 func (s *Server) workDoneProgressCancel(ctx context.Context, params *protocol.WorkDoneProgressCancelParams) error {