gopls/internal/debug: integrate flight recorder

This change adds support to gopls for Flight Recorder, the
new always-on version of the Go 1.25's runtime's event tracing.

Simply visit the gopls debug page and hit Flight Recorder,
and you'll immediately see the event trace for the past 30
seconds.

Also, a test of basic functionality.

Updates golang/go#66843 - in process http.Handler for trace
Updates golang/go#63185 - flight recorder runtime API

Change-Id: I6335e986990445014a51ed923b5ee7093c723fe9
Reviewed-on: https://go-review.googlesource.com/c/tools/+/555716
Reviewed-by: Robert Findley <rfindley@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Auto-Submit: Alan Donovan <adonovan@google.com>

Author: adonovan

gopls/internal/debug/flight.go

@@ -0,0 +1,129 @@
+// Copyright 2024 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+//go:build go1.25
+
+package debug
+
+import (
+	"bufio"
+	"fmt"
+	"log"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime/trace"
+	"strings"
+	"sync"
+	"time"
+)
+
+// The FlightRecorder is a global resource, so create at most one per process.
+var getRecorder = sync.OnceValues(func() (*trace.FlightRecorder, error) {
+	fr := trace.NewFlightRecorder(trace.FlightRecorderConfig{
+		// half a minute is usually enough to know "what just happened?"
+		MinAge: 30 * time.Second,
+	})
+	if err := fr.Start(); err != nil {
+		return nil, err
+	}
+	return fr, nil
+})
+
+func startFlightRecorder() (http.HandlerFunc, error) {
+	fr, err := getRecorder()
+	if err != nil {
+		return nil, err
+	}
+
+	// Return a handler that writes the most recent flight record,
+	// starts a trace viewer server, and redirects to it.
+	return func(w http.ResponseWriter, r *http.Request) {
+		errorf := func(format string, args ...any) {
+			msg := fmt.Sprintf(format, args...)
+			http.Error(w, msg, http.StatusInternalServerError)
+		}
+
+		// Write the most recent flight record into a temp file.
+		f, err := os.CreateTemp("", "flightrecord")
+		if err != nil {
+			errorf("can't create temp file for flight record: %v", err)
+			return
+		}
+		if _, err := fr.WriteTo(f); err != nil {
+			f.Close()
+			errorf("failed to write flight record: %s", err)
+			return
+		}
+		if err := f.Close(); err != nil {
+			errorf("failed to close flight record: %s", err)
+			return
+		}
+		tracefile, err := filepath.Abs(f.Name())
+		if err != nil {
+			errorf("can't absolutize name of trace file: %v", err)
+			return
+		}
+
+		// Run 'go tool trace' to start a new trace-viewer
+		// web server process. It will run until gopls terminates.
+		// (It would be nicer if we could just link it in; see #66843.)
+		cmd := exec.Command("go", "tool", "trace", tracefile)
+
+		// Don't connect trace's std{out,err} to our os.Stderr directly,
+		// otherwise the child may outlive the parent in tests,
+		// and 'go test' will complain about unclosed pipes.
+		// Instead, interpose a pipe that will close when gopls exits.
+		// See CL 677262 for a better solution (a cmd/trace flag).
+		// (#66843 is of course better still.)
+		// Also, this notifies us of the server's readiness and URL.
+		urlC := make(chan string)
+		{
+			r, w, err := os.Pipe()
+			if err != nil {
+				errorf("can't create pipe: %v", err)
+				return
+			}
+			go func() {
+				// Copy from the pipe to stderr,
+				// keeping an eye out for the "listening on URL" string.
+				scan := bufio.NewScanner(r)
+				for scan.Scan() {
+					line := scan.Text()
+					if _, url, ok := strings.Cut(line, "Trace viewer is listening on "); ok {
+						urlC <- url
+					}
+					fmt.Fprintln(os.Stderr, line)
+				}
+				if err := scan.Err(); err != nil {
+					log.Printf("reading from pipe to cmd/trace: %v", err)
+				}
+			}()
+			cmd.Stderr = w
+			cmd.Stdout = w
+		}
+
+		// Suppress the usual cmd/trace behavior of opening a new
+		// browser tab by setting BROWSER to /usr/bin/true (a no-op).
+		cmd.Env = append(os.Environ(), "BROWSER=true")
+		if err := cmd.Start(); err != nil {
+			errorf("failed to start trace server: %s", err)
+			return
+		}
+
+		select {
+		case addr := <-urlC:
+			// Success! Send a redirect to the new location.
+			// (This URL bypasses the help screen at /.)
+			http.Redirect(w, r, addr+"/trace?view=proc", 302)
+
+		case <-r.Context().Done():
+			errorf("canceled")
+
+		case <-time.After(10 * time.Second):
+			errorf("trace viewer failed to start", err)
+		}
+	}, nil
+}

gopls/internal/debug/flight_go124.go

@@ -0,0 +1,16 @@
+// Copyright 2025 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+//go:build !go1.25
+
+package debug
+
+import (
+	"errors"
+	"net/http"
+)
+
+func startFlightRecorder() (http.HandlerFunc, error) {
+	return nil, errors.ErrUnsupported
+}

gopls/internal/debug/serve.go

@@ -438,6 +438,13 @@ func (i *Instance) Serve(ctx context.Context, addr string) (string, error) {
 		mux.HandleFunc("/debug/pprof/profile", pprof.Profile)
 		mux.HandleFunc("/debug/pprof/symbol", pprof.Symbol)
 		mux.HandleFunc("/debug/pprof/trace", pprof.Trace)
+
+		if h, err := startFlightRecorder(); err != nil {
+			stdlog.Printf("failed to start flight recorder: %v", err) // e.g. go1.24
+		} else {
+			mux.HandleFunc("/flightrecorder", h)
+		}
+
 		if i.prometheus != nil {
 			mux.HandleFunc("/metrics/", i.prometheus.Serve)
 		}
@@ -468,11 +475,8 @@ func (i *Instance) Serve(ctx context.Context, addr string) (string, error) {
 			http.Error(w, "made a bug", http.StatusOK)
 		})
 
-		if err := http.Serve(listener, mux); err != nil {
-			event.Error(ctx, "Debug server failed", err)
-			return
-		}
-		event.Log(ctx, "Debug server finished")
+		err := http.Serve(listener, mux) // always non-nil
+		event.Error(ctx, "Debug server failed", err)
 	}()
 	return i.listenedDebugAddress, nil
 }
@@ -650,6 +654,7 @@ body {
 <a href="/metrics">Metrics</a>
 <a href="/rpc">RPC</a>
 <a href="/trace">Trace</a>
+<a href="/flightrecorder">Flight recorder</a>
 <a href="/analysis">Analysis</a>
 <hr>
 <h1>{{template "title" .}}</h1>

gopls/internal/test/integration/web/flight_test.go

@@ -0,0 +1,66 @@
+// Copyright 2025 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package web_test
+
+import (
+	"encoding/json"
+	"runtime"
+	"testing"
+
+	"golang.org/x/tools/gopls/internal/protocol"
+	"golang.org/x/tools/gopls/internal/protocol/command"
+	. "golang.org/x/tools/gopls/internal/test/integration"
+	"golang.org/x/tools/internal/testenv"
+)
+
+// TestFlightRecorder checks that the flight recorder is minimally functional.
+func TestFlightRecorder(t *testing.T) {
+	// The usual UNIX mechanisms cause timely termination of the
+	// cmd/trace process, but this doesn't happen on Windows,
+	// leading to CI failures because of process->file locking.
+	// Rather than invent a complex mechanism, skip the test:
+	// this feature is only for gopls developers anyway.
+	// Better long term solutions are CL 677262 and issue #66843.
+	if runtime.GOOS == "windows" {
+		t.Skip("not reliable on windows")
+	}
+	testenv.NeedsGo1Point(t, 25)
+
+	const files = `
+-- go.mod --
+module example.com
+
+-- a/a.go --
+package a
+
+const A = 1
+`
+
+	Run(t, files, func(t *testing.T, env *Env) {
+		env.OpenFile("a/a.go")
+
+		// Start the debug server.
+		var result command.DebuggingResult
+		env.ExecuteCommand(&protocol.ExecuteCommandParams{
+			Command:   command.StartDebugging.String(),
+			Arguments: []json.RawMessage{json.RawMessage("{}")}, // no args -> pick port
+		}, &result)
+		uri := result.URLs[0]
+		t.Logf("StartDebugging: URLs[0] = %s", uri)
+
+		// Check the debug server page is sensible.
+		doc1 := get(t, uri)
+		checkMatch(t, true, doc1, "Gopls server information")
+		checkMatch(t, true, doc1, `<a href="/flightrecorder">Flight recorder</a>`)
+
+		// "Click" the Flight Recorder link.
+		// It should redirect to the web server
+		// of a "go tool trace" process.
+		// The resulting web page is entirely programmatic,
+		// so we check for an arbitrary expected symbol.
+		doc2 := get(t, uri+"/flightrecorder")
+		checkMatch(t, true, doc2, `onTraceViewerImportFail`)
+	})
+}