profiling

package
v0.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 19, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package profiling writes Go runtime profiles when PIG_PROFILE names them.

With PIG_PROFILE unset, Start performs one environment lookup and returns a no-op, so release binaries pay nothing for the capability. With it set, pig profiles the whole process and writes the files on exit:

PIG_PROFILE=cpu,heap pig -p "hello"
PIG_PROFILE=trace PIG_PROFILE_DIR=/tmp/pig-profile pig

Kinds are cpu, heap, allocs, block, mutex, goroutine, trace, metrics, and flight. Files go to PIG_PROFILE_DIR (default: the current directory) as pig-<pid>-<kind>.pprof, pig-<pid>.trace for the execution trace, or pig-<pid>-metrics.json for the whole-process resource counts of ProcessMetrics. Read the profiles with `go tool pprof` and `go tool trace`, or run `make profile` from a source checkout.

flight keeps the last seconds of the execution trace in memory (a trace.FlightRecorder) and writes nothing at exit: DumpFlight writes the window when something goes wrong, which the exit record does beside the crash output file when the process ends without a user request. It costs the trace's steady overhead while it runs, so it is off unless named.

Index

Constants

This section is empty.

Variables

View Source
var FileRevisionStats, ModelsFileStats atomic.Uint64

FileRevisionStats counts the file-revision stats of auth.json and models.json (ai.authFileRevision, one per call) and ModelsFileStats the ones of models.json among them (counted at the models store's calls), so a process's auth.json stats are the difference. ProcessMetrics reports both. An increment is one atomic add, so the counters stay in every build.

View Source
var Kinds = []string{"cpu", "heap", "allocs", "block", "mutex", "goroutine", "trace", "metrics", "flight"}

Kinds lists the accepted PIG_PROFILE values in the order they are written.

Functions

func DumpFlight

func DumpFlight(path string) error

DumpFlight writes the flight recorder's window to path. It does nothing, and returns nil, when the recorder is not running. The file is created with mode 0600: a trace carries goroutine activity of the whole process.

func FlightActive

func FlightActive() bool

FlightActive reports whether PIG_PROFILE started the flight recorder.

func PeakRSSBytes

func PeakRSSBytes() int64

PeakRSSBytes is the process's peak resident set in bytes, or -1. It reads VmHWM from /proc/self/status, the high-water mark of the process's own address space. getrusage's ru_maxrss reads the same high-water counter without folding in the current RSS, which the kernel syncs into it only at intervals, so a running process can see a peak below its current RSS; it also carries the peak of the address space the process was exec'd from, which is the parent's when the parent spawned it with vfork (Go's os/exec, Python's subprocess, Node's child_process).

func Start

func Start() (stop func())

Start begins the profiles named by PIG_PROFILE and returns the function that stops them and writes every file. The returned function is safe to call more than once; only the first call writes.

func StartWith

func StartWith(spec, dir string, diag io.Writer) (stop func())

StartWith is Start with explicit inputs. Problems are reported to diag and never stop pig: a profile that cannot be written is skipped.

Types

type ProcessMetrics

type ProcessMetrics struct {
	GoVersion string `json:"go_version"`
	GOOS      string `json:"goos"`
	GOARCH    string `json:"goarch"`
	// AllocObjects and AllocBytes are the cumulative heap allocations (/gc/heap/allocs:objects and :bytes).
	AllocObjects uint64 `json:"alloc_objects"`
	AllocBytes   uint64 `json:"alloc_bytes"`
	// GCCycles counts completed GC cycles before the record's own collection.
	GCCycles uint64 `json:"gc_cycles"`
	// GCPercent is the GC percent at exit (/gc/gogc:percent), and HeapGoalBytes the heap size the last completed cycle set as the next goal (/gc/heap/goal:bytes), both read before the record's own collection: a policy that changes the percent (D175) shows here.
	GCPercent     uint64 `json:"gc_percent"`
	HeapGoalBytes uint64 `json:"heap_goal_bytes"`
	// GOMAXPROCS is the width when the record is read: the D174 cap, or the runtime default while a parallel section is open.
	GOMAXPROCS int `json:"gomaxprocs"`
	// GCPauses counts stop-the-world GC pauses; GCPauseSeconds approximates their total from the runtime's histogram buckets. It is a time, so gates do not compare it.
	GCPauses       uint64  `json:"gc_pauses"`
	GCPauseSeconds float64 `json:"gc_pause_seconds"`
	// HeapLiveBytes is the live heap after the forced collections at exit (collectRetained), so it excludes sync.Pool contents.
	HeapLiveBytes uint64 `json:"heap_live_bytes"`
	// MappedBytes is all memory the Go runtime has mapped (/memory/classes/total:bytes).
	MappedBytes uint64 `json:"mapped_bytes"`
	// MaxRSSBytes is the peak resident set size of the process.
	MaxRSSBytes int64 `json:"max_rss_bytes"`
	// Goroutines, OpenFDs, Threads and ChildProcesses are the exit state. A child that has exited but was not waited for still counts.
	Goroutines uint64 `json:"goroutines"` // runtime.NumGoroutine, which excludes the runtime's own goroutines
	OpenFDs    int64  `json:"open_fds"`
	// OpenFDsAtStart is the descriptor count when profiling started, which includes descriptors the parent let the process inherit; OpenFDs minus it is what the process opened and did not close. CollectMetrics leaves it -1.
	OpenFDsAtStart int64 `json:"open_fds_at_start"`
	Threads        int64 `json:"threads"`
	ChildProcesses int64 `json:"child_processes"`
	// GoroutinesCreated counts the goroutines the process started over its lifetime (/sched/goroutines-created:goroutines), the runtime's own included.
	GoroutinesCreated uint64 `json:"goroutines_created"`
	// AuthFileStats and ModelsFileStats count the revision stats of auth.json and of models.json (FileRevisionStats, ModelsFileStats).
	AuthFileStats   uint64 `json:"auth_file_stats"`
	ModelsFileStats uint64 `json:"models_file_stats"`
}

ProcessMetrics is the PIG_PROFILE=metrics record: whole-process resource counts taken when pig exits, after it has stopped its extensions and model services.

The allocation and GC-cycle counters cover the whole process lifetime. Allocation counts do not depend on machine speed, so count gates compare them with ceilings; RSS, the pause total and the counts of goroutines, descriptors and children describe the exit state. A field that the platform cannot report is -1.

func CollectMetrics

func CollectMetrics() ProcessMetrics

CollectMetrics reads the process counters now. It forces two garbage collections (collectRetained) to measure the retained live heap after reading the cumulative counters.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL