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 ¶
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.
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 ¶
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).
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.