README
¶
Profiling helpers
profiling provides two standard-library-only ways to inspect a Go process.
For live profiling, mount the pprof endpoints on an existing internal HTTP listener:
mux := http.NewServeMux()
profiling.Mount(mux)
Or run a dedicated diagnostics listener until a context is canceled:
go func() {
if err := profiling.Serve(ctx, "127.0.0.1:6060"); err != nil {
log.Printf("profiling server: %v", err)
}
}()
Then collect a 30-second CPU profile or inspect the current heap:
go tool pprof http://127.0.0.1:6060/debug/pprof/profile?seconds=30
go tool pprof http://127.0.0.1:6060/debug/pprof/heap
For a bounded file-based session, the default captures CPU samples and a heap snapshot:
session, err := profiling.Start(profiling.DefaultConfig("./profiles"))
if err != nil {
return err
}
defer func() {
if err := session.Stop(); err != nil {
log.Printf("stop profiling: %v", err)
}
}()
Select additional runtime profiles through Config.Profiles:
cfg := profiling.DefaultConfig("./profiles")
cfg.Profiles = append(cfg.Profiles,
profiling.AllocsProfile,
profiling.GoroutineProfile,
profiling.BlockProfile,
profiling.MutexProfile,
profiling.TraceProfile,
)
session, err := profiling.Start(cfg)
Open captured files in a browser
Use the pprof web UI for CPU, heap, allocations, goroutine, block, mutex, and thread-creation profiles:
go tool pprof -http=:0 ./profiles/20260806T120000.000000000Z-cpu.pprof
go tool pprof -http=:0 ./profiles/20260806T120000.000000000Z-heap.pprof
Replace the example path with the file written by your session. :0 selects an
available local port; pprof prints the address and normally opens it in your
default browser. Keep the command running while using the web interface, and
press Ctrl-C when finished.
If symbol or source information is missing, provide the exact executable that created the capture as well:
go tool pprof -http=:0 ./bin/filament/worker ./profiles/my-run-cpu.pprof
Runtime traces use Go's separate trace web viewer:
go tool trace ./profiles/20260806T120000.000000000Z-trace.out
This also starts a local web server and normally opens the trace interface in
your browser. Press Ctrl-C when finished.
Existing files are never overwritten; use a new prefix or remove an old capture
before reusing an explicit Config.Prefix.
Profiling output and live endpoints can contain sensitive process details;
store files securely and expose the HTTP listener only on a trusted network.
The standard net/http/pprof package registers its routes on
http.DefaultServeMux when imported, so do not serve the default mux on a
public listener.
Documentation
¶
Overview ¶
Package profiling provides drop-in helpers for live and file-based Go profiling.
Mount adds the standard /debug/pprof endpoints to an existing HTTP mux. Start records a bounded profiling session to disk. The default session records CPU activity while it is running and writes a heap snapshot when it stops:
session, err := profiling.Start(profiling.DefaultConfig("./profiles"))
if err != nil {
return err
}
defer session.Stop()
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrActive is returned when another file-based profiling session is active. // The Go runtime supports only one process-wide CPU profile and trace at a time. ErrActive = errors.New("profiling: another session is active") )
Functions ¶
func Handler ¶
Handler returns an isolated handler containing only the pprof endpoints. It is useful for a dedicated diagnostics listener.
Types ¶
type Config ¶
type Config struct {
// Directory receives the profile files and is created when necessary.
Directory string
// Prefix is prepended to each filename. When empty, Start uses a UTC timestamp.
Prefix string
// Profiles selects what to capture. At least one profile is required.
Profiles []Profile
// BlockRate is the average nanoseconds between sampled blocking events.
// Zero uses 1 millisecond. It applies only when BlockProfile is selected.
// Stop disables the process-wide block profiler because the runtime does not
// expose its previous rate.
BlockRate int
// MutexFraction samples one in this many contended mutex events.
// Zero uses 5. It applies only when MutexProfile is selected.
MutexFraction int
// GCBeforeHeap runs garbage collection before writing HeapProfile.
GCBeforeHeap bool
}
Config controls a file-based profiling session.
func DefaultConfig ¶
DefaultConfig returns a CPU and heap profiling configuration. Stop the returned Session to flush both profiles.
type Profile ¶
type Profile string
Profile identifies a profile captured by a Session.
const ( // CPUProfile samples CPU activity for the lifetime of the session. CPUProfile Profile = "cpu" // TraceProfile records a runtime execution trace for the lifetime of the session. TraceProfile Profile = "trace" // HeapProfile records sampled in-use memory when the session stops. HeapProfile Profile = "heap" // AllocsProfile records sampled historical allocations when the session stops. AllocsProfile Profile = "allocs" // GoroutineProfile records all current goroutine stacks when the session stops. GoroutineProfile Profile = "goroutine" // BlockProfile records blocking events over the lifetime of the session. BlockProfile Profile = "block" // MutexProfile records contended mutex events over the lifetime of the session. MutexProfile Profile = "mutex" // ThreadCreateProfile records stacks that created OS threads when the session stops. ThreadCreateProfile Profile = "threadcreate" )
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session is an active file-based profiling session. A process may have only one Session at a time. Stop is safe to call more than once.
func Start ¶
Start begins a file-based profiling session. CPU, trace, block, and mutex profiles collect until Stop; the other selected profiles are snapshots taken by Stop.
Source Files