flight_trace

README

flight_trace

The flight_trace package provides a lightweight wrapper around the Go runtime Flight Recorder (Go 1.25+),
allowing you to programmatically control and dump runtime traces.

🧩 Features

• Initializes runtime/trace.FlightRecorder with graceful shutdown via context.Context
• Configuration through Viper (FLIGHT_RECORDER_* environment variables)
• On-demand dump creation (DumpSnapshot, DumpSnapshotAsync)
• Framework-agnostic — works in HTTP, gRPC, CLI, or background workers

🔌 Middleware

• HTTP: http/middleware/flight_trace
• gRPC: grpc/middleware/flight_trace

⚙️ Configuration

Variable	Type	Description	Default
FLIGHT_RECORDER_ENABLED	bool	Enable Flight Recorder	true
FLIGHT_RECORDER_MIN_AGE	duration	Minimum age of samples to retain	1s
FLIGHT_RECORDER_MAX_BYTES	uint64	Maximum buffer size in bytes	20971520 (20 MB)
FLIGHT_RECORDER_DUMP_PATH	string	Directory for dump files	/tmp/flight_dumps

📚 References

• Go Blog: Flight Recorder
• Last9: Trace Go Apps using runtime tracing & OpenTelemetry
• Habr: Profiling Go applications with Flight Recorder (RU)
• Habr: Go runtime tracing under the hood (RU)

---

Minimal dependencies. Maximum observability.
Use flight_trace as a standalone utility or integrate it into your SDK.

Documentation

Index

• Variables
• type Recorder
  • func New(ctx context.Context, cfg *config.Config) (*Recorder, error)
  • func (wr *Recorder) DumpToFile(fileName string) error
  • func (wr *Recorder) DumpToFileAsync(fileName string)

Variables

var (
	ErrRecorderNotInitialized = errors.New("flight recorder not initialized")
	ErrRecorderNotStarted     = errors.New("flight recorder not started")
	ErrCreateDumpPath         = errors.New("failed to create dump path")
	ErrCreateDumpFile         = errors.New("failed to create dump file")
	ErrWriteDump              = errors.New("failed to write flight dump")
	ErrStartRecorder          = errors.New("failed to start flight recorder")
)

Types

type Recorder

type Recorder struct {
	// contains filtered or unexported fields
}

Recorder manages Go's Flight Recorder lifecycle and dump rotation.

func New

func New(ctx context.Context, cfg *config.Config) (*Recorder, error)

New initializes the Flight Recorder and starts background cleanup.

func (*Recorder) DumpToFile

func (wr *Recorder) DumpToFile(fileName string) error

DumpToFile writes the flight recorder buffer into a file under dumpPath.

func (*Recorder) DumpToFileAsync

func (wr *Recorder) DumpToFileAsync(fileName string)

DumpToFileAsync runs DumpToFile asynchronously.