Source file src/runtime/pprof/pprof.go

     1  // Copyright 2010 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package pprof writes runtime profiling data in the format expected
     6  // by the pprof visualization tool.
     7  //
     8  // # Profiling a Go program
     9  //
    10  // The first step to profiling a Go program is to enable profiling.
    11  // Support for profiling benchmarks built with the standard testing
    12  // package is built into go test. For example, the following command
    13  // runs benchmarks in the current directory and writes the CPU and
    14  // memory profiles to cpu.prof and mem.prof:
    15  //
    16  //	go test -cpuprofile cpu.prof -memprofile mem.prof -bench .
    17  //
    18  // To add equivalent profiling support to a standalone program, add
    19  // code like the following to your main function:
    20  //
    21  //	var cpuprofile = flag.String("cpuprofile", "", "write cpu profile to `file`")
    22  //	var memprofile = flag.String("memprofile", "", "write memory profile to `file`")
    23  //
    24  //	func main() {
    25  //	    flag.Parse()
    26  //	    if *cpuprofile != "" {
    27  //	        f, err := os.Create(*cpuprofile)
    28  //	        if err != nil {
    29  //	            log.Fatal("could not create CPU profile: ", err)
    30  //	        }
    31  //	        defer f.Close() // error handling omitted for example
    32  //	        if err := pprof.StartCPUProfile(f); err != nil {
    33  //	            log.Fatal("could not start CPU profile: ", err)
    34  //	        }
    35  //	        defer pprof.StopCPUProfile()
    36  //	    }
    37  //
    38  //	    // ... rest of the program ...
    39  //
    40  //	    if *memprofile != "" {
    41  //	        f, err := os.Create(*memprofile)
    42  //	        if err != nil {
    43  //	            log.Fatal("could not create memory profile: ", err)
    44  //	        }
    45  //	        defer f.Close() // error handling omitted for example
    46  //	        runtime.GC() // get up-to-date statistics
    47  //	        // Lookup("allocs") creates a profile similar to go test -memprofile.
    48  //	        // Alternatively, use Lookup("heap") for a profile
    49  //	        // that has inuse_space as the default index.
    50  //	        if err := pprof.Lookup("allocs").WriteTo(f, 0); err != nil {
    51  //	            log.Fatal("could not write memory profile: ", err)
    52  //	        }
    53  //	    }
    54  //	}
    55  //
    56  // There is also a standard HTTP interface to profiling data. Adding
    57  // the following line will install handlers under the /debug/pprof/
    58  // URL to download live profiles:
    59  //
    60  //	import _ "net/http/pprof"
    61  //
    62  // See the net/http/pprof package for more details.
    63  //
    64  // Profiles can then be visualized with the pprof tool:
    65  //
    66  //	go tool pprof cpu.prof
    67  //
    68  // There are many commands available from the pprof command line.
    69  // Commonly used commands include "top", which prints a summary of the
    70  // top program hot-spots, and "web", which opens an interactive graph
    71  // of hot-spots and their call graphs. Use "help" for information on
    72  // all pprof commands.
    73  //
    74  // For more information about pprof, see
    75  // https://github.com/google/pprof/blob/main/doc/README.md.
    76  package pprof
    77  
    78  import (
    79  	"bufio"
    80  	"cmp"
    81  	"fmt"
    82  	"internal/abi"
    83  	"internal/goexperiment"
    84  	"internal/profilerecord"
    85  	"io"
    86  	"runtime"
    87  	"slices"
    88  	"sort"
    89  	"strings"
    90  	"sync"
    91  	"text/tabwriter"
    92  	"time"
    93  	"unsafe"
    94  )
    95  
    96  // BUG(rsc): Profiles are only as good as the kernel support used to generate them.
    97  // See https://golang.org/issue/13841 for details about known problems.
    98  
    99  // A Profile is a collection of stack traces showing the call sequences
   100  // that led to instances of a particular event, such as allocation.
   101  // Packages can create and maintain their own profiles; the most common
   102  // use is for tracking resources that must be explicitly closed, such as files
   103  // or network connections.
   104  //
   105  // A Profile's methods can be called from multiple goroutines simultaneously.
   106  //
   107  // Each Profile has a unique name. A few profiles are predefined:
   108  //
   109  //	goroutine      - stack traces of all current goroutines
   110  //	goroutineleak  - stack traces of all leaked goroutines
   111  //	allocs         - a sampling of all past memory allocations
   112  //	heap           - a sampling of memory allocations of live objects
   113  //	threadcreate   - stack traces that led to the creation of new OS threads
   114  //	block          - stack traces that led to blocking on synchronization primitives
   115  //	mutex          - stack traces of holders of contended mutexes
   116  //
   117  // These predefined profiles maintain themselves and panic on an explicit
   118  // [Profile.Add] or [Profile.Remove] method call.
   119  //
   120  // The CPU profile is not available as a Profile. It has a special API,
   121  // the [StartCPUProfile] and [StopCPUProfile] functions, because it streams
   122  // output to a writer during profiling.
   123  //
   124  // # Heap profile
   125  //
   126  // The heap profile reports statistics as of the most recently completed
   127  // garbage collection; it elides more recent allocation to avoid skewing
   128  // the profile away from live data and toward garbage.
   129  // If there has been no garbage collection at all, the heap profile reports
   130  // all known allocations. This exception helps mainly in programs running
   131  // without garbage collection enabled, usually for debugging purposes.
   132  //
   133  // The heap profile tracks both the allocation sites for all live objects in
   134  // the application memory and for all objects allocated since the program start.
   135  // Pprof's -inuse_space, -inuse_objects, -alloc_space, and -alloc_objects
   136  // flags select which to display, defaulting to -inuse_space (live objects,
   137  // scaled by size).
   138  //
   139  // # Allocs profile
   140  //
   141  // The allocs profile is the same as the heap profile but changes the default
   142  // pprof display to -alloc_space, the total number of bytes allocated since
   143  // the program began (including garbage-collected bytes).
   144  //
   145  // # Block profile
   146  //
   147  // The block profile tracks time spent blocked on synchronization primitives,
   148  // such as [sync.Mutex], [sync.RWMutex], [sync.WaitGroup], [sync.Cond], and
   149  // channel send/receive/select.
   150  //
   151  // Stack traces correspond to the location that blocked (for example,
   152  // [sync.Mutex.Lock]).
   153  //
   154  // Sample values correspond to cumulative time spent blocked at that stack
   155  // trace, subject to time-based sampling specified by
   156  // [runtime.SetBlockProfileRate].
   157  //
   158  // # Mutex profile
   159  //
   160  // The mutex profile tracks contention on mutexes, such as [sync.Mutex],
   161  // [sync.RWMutex], and runtime-internal locks.
   162  //
   163  // Stack traces correspond to the end of the critical section causing
   164  // contention. For example, a lock held for a long time while other goroutines
   165  // are waiting to acquire the lock will report contention when the lock is
   166  // finally unlocked (that is, at [sync.Mutex.Unlock]).
   167  //
   168  // Sample values correspond to the approximate cumulative time other goroutines
   169  // spent blocked waiting for the lock, subject to event-based sampling
   170  // specified by [runtime.SetMutexProfileFraction]. For example, if a caller
   171  // holds a lock for 1s while 5 other goroutines are waiting for the entire
   172  // second to acquire the lock, its unlock call stack will report 5s of
   173  // contention.
   174  type Profile struct {
   175  	name  string
   176  	mu    sync.Mutex
   177  	m     map[any][]uintptr
   178  	count func() int
   179  	write func(io.Writer, int) error
   180  }
   181  
   182  // profiles records all registered profiles.
   183  var profiles struct {
   184  	mu sync.Mutex
   185  	m  map[string]*Profile
   186  }
   187  
   188  var goroutineProfile = &Profile{
   189  	name:  "goroutine",
   190  	count: countGoroutine,
   191  	write: writeGoroutine,
   192  }
   193  
   194  var goroutineLeakProfile = &Profile{
   195  	name:  "goroutineleak",
   196  	count: runtime_goroutineleakcount,
   197  	write: writeGoroutineLeak,
   198  }
   199  
   200  var threadcreateProfile = &Profile{
   201  	name:  "threadcreate",
   202  	count: countThreadCreate,
   203  	write: writeThreadCreate,
   204  }
   205  
   206  var heapProfile = &Profile{
   207  	name:  "heap",
   208  	count: countHeap,
   209  	write: writeHeap,
   210  }
   211  
   212  var allocsProfile = &Profile{
   213  	name:  "allocs",
   214  	count: countHeap, // identical to heap profile
   215  	write: writeAlloc,
   216  }
   217  
   218  var blockProfile = &Profile{
   219  	name:  "block",
   220  	count: countBlock,
   221  	write: writeBlock,
   222  }
   223  
   224  var mutexProfile = &Profile{
   225  	name:  "mutex",
   226  	count: countMutex,
   227  	write: writeMutex,
   228  }
   229  
   230  // goroutineLeakProfileLock ensures that the goroutine leak profile writer observes the
   231  // leaked goroutines discovered during the goroutine leak detection GC cycle
   232  // that was triggered by the profile request.
   233  // This prevents a race condition between the garbage collector and the profile writer
   234  // when multiple profile requests are issued concurrently: the status of leaked goroutines
   235  // is reset to _Gwaiting at the beginning of a leak detection cycle, which may lead the
   236  // profile writer of another concurrent request to produce an incomplete profile.
   237  //
   238  // Example trace:
   239  //
   240  //	G1                    | GC                          | G2
   241  //	----------------------+-----------------------------+---------------------
   242  //	Request profile       | .                           | .
   243  //	.                     | .                           | Request profile
   244  //	.                     | [G1] Resets leaked g status | .
   245  //	.                     | [G1] Leaks detected         | .
   246  //	.                     | <New cycle>                 | .
   247  //	.                     | [G2] Resets leaked g status | .
   248  //	Write profile         | .                           | .
   249  //	.                     | [G2] Leaks detected         | .
   250  //	.                     | .                           | Write profile
   251  //	----------------------+-----------------------------+---------------------
   252  //	Incomplete profile    |+++++++++++++++++++++++++++++| Complete profile
   253  var goroutineLeakProfileLock sync.Mutex
   254  
   255  func lockProfiles() {
   256  	profiles.mu.Lock()
   257  	if profiles.m == nil {
   258  		// Initial built-in profiles.
   259  		profiles.m = map[string]*Profile{
   260  			"goroutine":    goroutineProfile,
   261  			"threadcreate": threadcreateProfile,
   262  			"heap":         heapProfile,
   263  			"allocs":       allocsProfile,
   264  			"block":        blockProfile,
   265  			"mutex":        mutexProfile,
   266  		}
   267  		if goexperiment.GoroutineLeakProfile {
   268  			profiles.m["goroutineleak"] = goroutineLeakProfile
   269  		}
   270  	}
   271  }
   272  
   273  func unlockProfiles() {
   274  	profiles.mu.Unlock()
   275  }
   276  
   277  // NewProfile creates a new profile with the given name.
   278  // If a profile with that name already exists, NewProfile panics.
   279  // The convention is to use a 'import/path.' prefix to create
   280  // separate name spaces for each package.
   281  // For compatibility with various tools that read pprof data,
   282  // profile names should not contain spaces.
   283  func NewProfile(name string) *Profile {
   284  	lockProfiles()
   285  	defer unlockProfiles()
   286  	if name == "" {
   287  		panic("pprof: NewProfile with empty name")
   288  	}
   289  	if profiles.m[name] != nil {
   290  		panic("pprof: NewProfile name already in use: " + name)
   291  	}
   292  	p := &Profile{
   293  		name: name,
   294  		m:    map[any][]uintptr{},
   295  	}
   296  	profiles.m[name] = p
   297  	return p
   298  }
   299  
   300  // Lookup returns the profile with the given name, or nil if no such profile exists.
   301  func Lookup(name string) *Profile {
   302  	lockProfiles()
   303  	defer unlockProfiles()
   304  	return profiles.m[name]
   305  }
   306  
   307  // Profiles returns a slice of all the known profiles, sorted by name.
   308  func Profiles() []*Profile {
   309  	lockProfiles()
   310  	defer unlockProfiles()
   311  
   312  	all := make([]*Profile, 0, len(profiles.m))
   313  	for _, p := range profiles.m {
   314  
   315  		all = append(all, p)
   316  	}
   317  
   318  	slices.SortFunc(all, func(a, b *Profile) int {
   319  		return strings.Compare(a.name, b.name)
   320  	})
   321  	return all
   322  }
   323  
   324  // Name returns this profile's name, which can be passed to [Lookup] to reobtain the profile.
   325  func (p *Profile) Name() string {
   326  	return p.name
   327  }
   328  
   329  // Count returns the number of execution stacks currently in the profile.
   330  func (p *Profile) Count() int {
   331  	p.mu.Lock()
   332  	defer p.mu.Unlock()
   333  	if p.count != nil {
   334  		return p.count()
   335  	}
   336  	return len(p.m)
   337  }
   338  
   339  // Add adds the current execution stack to the profile, associated with value.
   340  // Add stores value in an internal map, so value must be suitable for use as
   341  // a map key and will not be garbage collected until the corresponding
   342  // call to [Profile.Remove]. Add panics if the profile already contains a stack for value.
   343  //
   344  // The skip parameter has the same meaning as [runtime.Caller]'s skip
   345  // and controls where the stack trace begins. Passing skip=0 begins the
   346  // trace in the function calling Add. For example, given this
   347  // execution stack:
   348  //
   349  //	Add
   350  //	called from rpc.NewClient
   351  //	called from mypkg.Run
   352  //	called from main.main
   353  //
   354  // Passing skip=0 begins the stack trace at the call to Add inside rpc.NewClient.
   355  // Passing skip=1 begins the stack trace at the call to NewClient inside mypkg.Run.
   356  func (p *Profile) Add(value any, skip int) {
   357  	if p.name == "" {
   358  		panic("pprof: use of uninitialized Profile")
   359  	}
   360  	if p.write != nil {
   361  		panic("pprof: Add called on built-in Profile " + p.name)
   362  	}
   363  
   364  	stk := make([]uintptr, 32)
   365  	n := runtime.Callers(skip+1, stk[:])
   366  	stk = stk[:n]
   367  	if len(stk) == 0 {
   368  		// The value for skip is too large, and there's no stack trace to record.
   369  		stk = []uintptr{abi.FuncPCABIInternal(lostProfileEvent)}
   370  	}
   371  
   372  	p.mu.Lock()
   373  	defer p.mu.Unlock()
   374  	if p.m[value] != nil {
   375  		panic("pprof: Profile.Add of duplicate value")
   376  	}
   377  	p.m[value] = stk
   378  }
   379  
   380  // Remove removes the execution stack associated with value from the profile.
   381  // It is a no-op if the value is not in the profile.
   382  func (p *Profile) Remove(value any) {
   383  	p.mu.Lock()
   384  	defer p.mu.Unlock()
   385  	delete(p.m, value)
   386  }
   387  
   388  // WriteTo writes a pprof-formatted snapshot of the profile to w.
   389  // If a write to w returns an error, WriteTo returns that error.
   390  // Otherwise, WriteTo returns nil.
   391  //
   392  // The debug parameter enables additional output.
   393  // Passing debug=0 writes the gzip-compressed protocol buffer described
   394  // in https://github.com/google/pprof/tree/main/proto#overview.
   395  // Passing debug=1 writes the legacy text format with comments
   396  // translating addresses to function names and line numbers, so that a
   397  // programmer can read the profile without tools.
   398  //
   399  // The predefined profiles may assign meaning to other debug values;
   400  // for example, when printing the "goroutine" profile, debug=2 means to
   401  // print the goroutine stacks in the same form that a Go program uses
   402  // when dying due to an unrecovered panic.
   403  func (p *Profile) WriteTo(w io.Writer, debug int) error {
   404  	if p.name == "" {
   405  		panic("pprof: use of zero Profile")
   406  	}
   407  	if p.write != nil {
   408  		return p.write(w, debug)
   409  	}
   410  
   411  	// Obtain consistent snapshot under lock; then process without lock.
   412  	p.mu.Lock()
   413  	all := make([][]uintptr, 0, len(p.m))
   414  	for _, stk := range p.m {
   415  		all = append(all, stk)
   416  	}
   417  	p.mu.Unlock()
   418  
   419  	// Map order is non-deterministic; make output deterministic.
   420  	slices.SortFunc(all, slices.Compare)
   421  
   422  	return printCountProfile(w, debug, p.name, stackProfile(all))
   423  }
   424  
   425  type stackProfile [][]uintptr
   426  
   427  func (x stackProfile) Len() int              { return len(x) }
   428  func (x stackProfile) Stack(i int) []uintptr { return x[i] }
   429  func (x stackProfile) Label(i int) *labelMap { return nil }
   430  
   431  // A countProfile is a set of stack traces to be printed as counts
   432  // grouped by stack trace. There are multiple implementations:
   433  // all that matters is that we can find out how many traces there are
   434  // and obtain each trace in turn.
   435  type countProfile interface {
   436  	Len() int
   437  	Stack(i int) []uintptr
   438  	Label(i int) *labelMap
   439  }
   440  
   441  // expandInlinedFrames copies the call stack from pcs into dst, expanding any
   442  // PCs corresponding to inlined calls into the corresponding PCs for the inlined
   443  // functions. Returns the number of frames copied to dst.
   444  func expandInlinedFrames(dst, pcs []uintptr) int {
   445  	cf := runtime.CallersFrames(pcs)
   446  	var n int
   447  	for n < len(dst) {
   448  		f, more := cf.Next()
   449  		// f.PC is a "call PC", but later consumers will expect
   450  		// "return PCs"
   451  		dst[n] = f.PC + 1
   452  		n++
   453  		if !more {
   454  			break
   455  		}
   456  	}
   457  	return n
   458  }
   459  
   460  // printCountCycleProfile outputs block profile records (for block or mutex profiles)
   461  // as the pprof-proto format output. Translations from cycle count to time duration
   462  // are done because The proto expects count and time (nanoseconds) instead of count
   463  // and the number of cycles for block, contention profiles.
   464  func printCountCycleProfile(w io.Writer, countName, cycleName string, records []profilerecord.BlockProfileRecord) error {
   465  	// Output profile in protobuf form.
   466  	b := newProfileBuilder(w)
   467  	b.pbValueType(tagProfile_PeriodType, countName, "count")
   468  	b.pb.int64Opt(tagProfile_Period, 1)
   469  	b.pbValueType(tagProfile_SampleType, countName, "count")
   470  	b.pbValueType(tagProfile_SampleType, cycleName, "nanoseconds")
   471  
   472  	cpuGHz := float64(pprof_cyclesPerSecond()) / 1e9
   473  
   474  	values := []int64{0, 0}
   475  	var locs []uint64
   476  	expandedStack := pprof_makeProfStack()
   477  	for _, r := range records {
   478  		values[0] = r.Count
   479  		values[1] = int64(float64(r.Cycles) / cpuGHz)
   480  		// For count profiles, all stack addresses are
   481  		// return PCs, which is what appendLocsForStack expects.
   482  		n := expandInlinedFrames(expandedStack, r.Stack)
   483  		locs = b.appendLocsForStack(locs[:0], expandedStack[:n])
   484  		b.pbSample(values, locs, nil)
   485  	}
   486  	return b.build()
   487  }
   488  
   489  // printCountProfile prints a countProfile at the specified debug level.
   490  // The profile will be in compressed proto format unless debug is nonzero.
   491  func printCountProfile(w io.Writer, debug int, name string, p countProfile) error {
   492  	// Build count of each stack.
   493  	var buf strings.Builder
   494  	key := func(stk []uintptr, lbls *labelMap) string {
   495  		buf.Reset()
   496  		fmt.Fprintf(&buf, "@")
   497  		for _, pc := range stk {
   498  			fmt.Fprintf(&buf, " %#x", pc)
   499  		}
   500  		if lbls != nil {
   501  			buf.WriteString("\n# labels: ")
   502  			buf.WriteString(lbls.String())
   503  		}
   504  		return buf.String()
   505  	}
   506  	count := map[string]int{}
   507  	index := map[string]int{}
   508  	var keys []string
   509  	n := p.Len()
   510  	for i := 0; i < n; i++ {
   511  		k := key(p.Stack(i), p.Label(i))
   512  		if count[k] == 0 {
   513  			index[k] = i
   514  			keys = append(keys, k)
   515  		}
   516  		count[k]++
   517  	}
   518  
   519  	sort.Sort(&keysByCount{keys, count})
   520  
   521  	if debug > 0 {
   522  		// Print debug profile in legacy format
   523  		tw := tabwriter.NewWriter(w, 1, 8, 1, '\t', 0)
   524  		fmt.Fprintf(tw, "%s profile: total %d\n", name, p.Len())
   525  		for _, k := range keys {
   526  			fmt.Fprintf(tw, "%d %s\n", count[k], k)
   527  			printStackRecord(tw, p.Stack(index[k]), false)
   528  		}
   529  		return tw.Flush()
   530  	}
   531  
   532  	// Output profile in protobuf form.
   533  	b := newProfileBuilder(w)
   534  	b.pbValueType(tagProfile_PeriodType, name, "count")
   535  	b.pb.int64Opt(tagProfile_Period, 1)
   536  	b.pbValueType(tagProfile_SampleType, name, "count")
   537  
   538  	values := []int64{0}
   539  	var locs []uint64
   540  	for _, k := range keys {
   541  		values[0] = int64(count[k])
   542  		// For count profiles, all stack addresses are
   543  		// return PCs, which is what appendLocsForStack expects.
   544  		locs = b.appendLocsForStack(locs[:0], p.Stack(index[k]))
   545  		idx := index[k]
   546  		var labels func()
   547  		if p.Label(idx) != nil {
   548  			labels = func() {
   549  				for _, lbl := range p.Label(idx).Set.List {
   550  					b.pbLabel(tagSample_Label, lbl.Key, lbl.Value, 0)
   551  				}
   552  			}
   553  		}
   554  		b.pbSample(values, locs, labels)
   555  	}
   556  	return b.build()
   557  }
   558  
   559  // keysByCount sorts keys with higher counts first, breaking ties by key string order.
   560  type keysByCount struct {
   561  	keys  []string
   562  	count map[string]int
   563  }
   564  
   565  func (x *keysByCount) Len() int      { return len(x.keys) }
   566  func (x *keysByCount) Swap(i, j int) { x.keys[i], x.keys[j] = x.keys[j], x.keys[i] }
   567  func (x *keysByCount) Less(i, j int) bool {
   568  	ki, kj := x.keys[i], x.keys[j]
   569  	ci, cj := x.count[ki], x.count[kj]
   570  	if ci != cj {
   571  		return ci > cj
   572  	}
   573  	return ki < kj
   574  }
   575  
   576  // printStackRecord prints the function + source line information
   577  // for a single stack trace.
   578  func printStackRecord(w io.Writer, stk []uintptr, allFrames bool) {
   579  	show := allFrames
   580  	frames := runtime.CallersFrames(stk)
   581  	for {
   582  		frame, more := frames.Next()
   583  		name := frame.Function
   584  		if name == "" {
   585  			show = true
   586  			fmt.Fprintf(w, "#\t%#x\n", frame.PC)
   587  		} else if name != "runtime.goexit" && (show || !(strings.HasPrefix(name, "runtime.") || strings.HasPrefix(name, "internal/runtime/"))) {
   588  			// Hide runtime.goexit and any runtime functions at the beginning.
   589  			// This is useful mainly for allocation traces.
   590  			show = true
   591  			fmt.Fprintf(w, "#\t%#x\t%s+%#x\t%s:%d\n", frame.PC, name, frame.PC-frame.Entry, frame.File, frame.Line)
   592  		}
   593  		if !more {
   594  			break
   595  		}
   596  	}
   597  	if !show {
   598  		// We didn't print anything; do it again,
   599  		// and this time include runtime functions.
   600  		printStackRecord(w, stk, true)
   601  		return
   602  	}
   603  	fmt.Fprintf(w, "\n")
   604  }
   605  
   606  // Interface to system profiles.
   607  
   608  // WriteHeapProfile is shorthand for [Lookup]("heap").WriteTo(w, 0).
   609  // It is preserved for backwards compatibility.
   610  func WriteHeapProfile(w io.Writer) error {
   611  	return writeHeap(w, 0)
   612  }
   613  
   614  // countHeap returns the number of records in the heap profile.
   615  func countHeap() int {
   616  	n, _ := runtime.MemProfile(nil, true)
   617  	return n
   618  }
   619  
   620  // writeHeap writes the current runtime heap profile to w.
   621  func writeHeap(w io.Writer, debug int) error {
   622  	return writeHeapInternal(w, debug, "")
   623  }
   624  
   625  // writeAlloc writes the current runtime heap profile to w
   626  // with the total allocation space as the default sample type.
   627  func writeAlloc(w io.Writer, debug int) error {
   628  	return writeHeapInternal(w, debug, "alloc_space")
   629  }
   630  
   631  func writeHeapInternal(w io.Writer, debug int, defaultSampleType string) error {
   632  	var memStats *runtime.MemStats
   633  	if debug != 0 {
   634  		// Read mem stats first, so that our other allocations
   635  		// do not appear in the statistics.
   636  		memStats = new(runtime.MemStats)
   637  		runtime.ReadMemStats(memStats)
   638  	}
   639  
   640  	// Find out how many records there are (the call
   641  	// pprof_memProfileInternal(nil, true) below),
   642  	// allocate that many records, and get the data.
   643  	// There's a race—more records might be added between
   644  	// the two calls—so allocate a few extra records for safety
   645  	// and also try again if we're very unlucky.
   646  	// The loop should only execute one iteration in the common case.
   647  	var p []profilerecord.MemProfileRecord
   648  	n, ok := pprof_memProfileInternal(nil, true)
   649  	for {
   650  		// Allocate room for a slightly bigger profile,
   651  		// in case a few more entries have been added
   652  		// since the call to MemProfile.
   653  		p = make([]profilerecord.MemProfileRecord, n+50)
   654  		n, ok = pprof_memProfileInternal(p, true)
   655  		if ok {
   656  			p = p[0:n]
   657  			break
   658  		}
   659  		// Profile grew; try again.
   660  	}
   661  
   662  	if debug == 0 {
   663  		return writeHeapProto(w, p, int64(runtime.MemProfileRate), defaultSampleType)
   664  	}
   665  
   666  	slices.SortFunc(p, func(a, b profilerecord.MemProfileRecord) int {
   667  		return cmp.Compare(a.InUseBytes(), b.InUseBytes())
   668  	})
   669  
   670  	b := bufio.NewWriter(w)
   671  	tw := tabwriter.NewWriter(b, 1, 8, 1, '\t', 0)
   672  	w = tw
   673  
   674  	var total runtime.MemProfileRecord
   675  	for i := range p {
   676  		r := &p[i]
   677  		total.AllocBytes += r.AllocBytes
   678  		total.AllocObjects += r.AllocObjects
   679  		total.FreeBytes += r.FreeBytes
   680  		total.FreeObjects += r.FreeObjects
   681  	}
   682  
   683  	// Technically the rate is MemProfileRate not 2*MemProfileRate,
   684  	// but early versions of the C++ heap profiler reported 2*MemProfileRate,
   685  	// so that's what pprof has come to expect.
   686  	rate := 2 * runtime.MemProfileRate
   687  
   688  	// pprof reads a profile with alloc == inuse as being a "2-column" profile
   689  	// (objects and bytes, not distinguishing alloc from inuse),
   690  	// but then such a profile can't be merged using pprof *.prof with
   691  	// other 4-column profiles where alloc != inuse.
   692  	// The easiest way to avoid this bug is to adjust allocBytes so it's never == inuseBytes.
   693  	// pprof doesn't use these header values anymore except for checking equality.
   694  	inUseBytes := total.InUseBytes()
   695  	allocBytes := total.AllocBytes
   696  	if inUseBytes == allocBytes {
   697  		allocBytes++
   698  	}
   699  
   700  	fmt.Fprintf(w, "heap profile: %d: %d [%d: %d] @ heap/%d\n",
   701  		total.InUseObjects(), inUseBytes,
   702  		total.AllocObjects, allocBytes,
   703  		rate)
   704  
   705  	for i := range p {
   706  		r := &p[i]
   707  		fmt.Fprintf(w, "%d: %d [%d: %d] @",
   708  			r.InUseObjects(), r.InUseBytes(),
   709  			r.AllocObjects, r.AllocBytes)
   710  		for _, pc := range r.Stack {
   711  			fmt.Fprintf(w, " %#x", pc)
   712  		}
   713  		fmt.Fprintf(w, "\n")
   714  		printStackRecord(w, r.Stack, false)
   715  	}
   716  
   717  	// Print memstats information too.
   718  	// Pprof will ignore, but useful for people
   719  	s := memStats
   720  	fmt.Fprintf(w, "\n# runtime.MemStats\n")
   721  	fmt.Fprintf(w, "# Alloc = %d\n", s.Alloc)
   722  	fmt.Fprintf(w, "# TotalAlloc = %d\n", s.TotalAlloc)
   723  	fmt.Fprintf(w, "# Sys = %d\n", s.Sys)
   724  	fmt.Fprintf(w, "# Lookups = %d\n", s.Lookups)
   725  	fmt.Fprintf(w, "# Mallocs = %d\n", s.Mallocs)
   726  	fmt.Fprintf(w, "# Frees = %d\n", s.Frees)
   727  
   728  	fmt.Fprintf(w, "# HeapAlloc = %d\n", s.HeapAlloc)
   729  	fmt.Fprintf(w, "# HeapSys = %d\n", s.HeapSys)
   730  	fmt.Fprintf(w, "# HeapIdle = %d\n", s.HeapIdle)
   731  	fmt.Fprintf(w, "# HeapInuse = %d\n", s.HeapInuse)
   732  	fmt.Fprintf(w, "# HeapReleased = %d\n", s.HeapReleased)
   733  	fmt.Fprintf(w, "# HeapObjects = %d\n", s.HeapObjects)
   734  
   735  	fmt.Fprintf(w, "# Stack = %d / %d\n", s.StackInuse, s.StackSys)
   736  	fmt.Fprintf(w, "# MSpan = %d / %d\n", s.MSpanInuse, s.MSpanSys)
   737  	fmt.Fprintf(w, "# MCache = %d / %d\n", s.MCacheInuse, s.MCacheSys)
   738  	fmt.Fprintf(w, "# BuckHashSys = %d\n", s.BuckHashSys)
   739  	fmt.Fprintf(w, "# GCSys = %d\n", s.GCSys)
   740  	fmt.Fprintf(w, "# OtherSys = %d\n", s.OtherSys)
   741  
   742  	fmt.Fprintf(w, "# NextGC = %d\n", s.NextGC)
   743  	fmt.Fprintf(w, "# LastGC = %d\n", s.LastGC)
   744  	fmt.Fprintf(w, "# PauseNs = %d\n", s.PauseNs)
   745  	fmt.Fprintf(w, "# PauseEnd = %d\n", s.PauseEnd)
   746  	fmt.Fprintf(w, "# NumGC = %d\n", s.NumGC)
   747  	fmt.Fprintf(w, "# NumForcedGC = %d\n", s.NumForcedGC)
   748  	fmt.Fprintf(w, "# GCCPUFraction = %v\n", s.GCCPUFraction)
   749  	fmt.Fprintf(w, "# DebugGC = %v\n", s.DebugGC)
   750  
   751  	// Also flush out MaxRSS on supported platforms.
   752  	addMaxRSS(w)
   753  
   754  	tw.Flush()
   755  	return b.Flush()
   756  }
   757  
   758  // countThreadCreate returns the size of the current ThreadCreateProfile.
   759  func countThreadCreate() int {
   760  	n, _ := runtime.ThreadCreateProfile(nil)
   761  	return n
   762  }
   763  
   764  // writeThreadCreate writes the current runtime ThreadCreateProfile to w.
   765  func writeThreadCreate(w io.Writer, debug int) error {
   766  	// Until https://golang.org/issues/6104 is addressed, wrap
   767  	// ThreadCreateProfile because there's no point in tracking labels when we
   768  	// don't get any stack-traces.
   769  	return writeRuntimeProfile(w, debug, "threadcreate", func(p []profilerecord.StackRecord, _ []unsafe.Pointer) (n int, ok bool) {
   770  		return pprof_threadCreateInternal(p)
   771  	})
   772  }
   773  
   774  // countGoroutine returns the number of goroutines.
   775  func countGoroutine() int {
   776  	return runtime.NumGoroutine()
   777  }
   778  
   779  // writeGoroutine writes the current runtime GoroutineProfile to w.
   780  func writeGoroutine(w io.Writer, debug int) error {
   781  	if debug >= 2 {
   782  		return writeGoroutineStacks(w)
   783  	}
   784  	return writeRuntimeProfile(w, debug, "goroutine", pprof_goroutineProfileWithLabels)
   785  }
   786  
   787  // writeGoroutineLeak first invokes a GC cycle that performs goroutine leak detection.
   788  // It then writes the goroutine profile, filtering for leaked goroutines.
   789  func writeGoroutineLeak(w io.Writer, debug int) error {
   790  	// Acquire the goroutine leak detection lock and release
   791  	// it after the goroutine leak profile is written.
   792  	//
   793  	// While the critical section is long, this is needed to prevent
   794  	// a race condition between the garbage collector and the goroutine
   795  	// leak profile writer when multiple profile requests are issued concurrently.
   796  	goroutineLeakProfileLock.Lock()
   797  	defer goroutineLeakProfileLock.Unlock()
   798  
   799  	// Run the GC with leak detection first so that leaked goroutines
   800  	// may transition to the leaked state.
   801  	runtime_goroutineLeakGC()
   802  
   803  	// If the debug flag is set sufficiently high, just defer to writing goroutine stacks
   804  	// like in a regular goroutine profile. Include non-leaked goroutines, too.
   805  	if debug >= 2 {
   806  		return writeGoroutineStacks(w)
   807  	}
   808  
   809  	// Otherwise, write the goroutine leak profile.
   810  	return writeRuntimeProfile(w, debug, "goroutineleak", pprof_goroutineLeakProfileWithLabels)
   811  }
   812  
   813  func writeGoroutineStacks(w io.Writer) error {
   814  	// We don't know how big the buffer needs to be to collect
   815  	// all the goroutines. Start with 1 MB and try a few times, doubling each time.
   816  	// Give up and use a truncated trace if 64 MB is not enough.
   817  	buf := make([]byte, 1<<20)
   818  	for i := 0; ; i++ {
   819  		n := runtime.Stack(buf, true)
   820  		if n < len(buf) {
   821  			buf = buf[:n]
   822  			break
   823  		}
   824  		if len(buf) >= 64<<20 {
   825  			// Filled 64 MB - stop there.
   826  			break
   827  		}
   828  		buf = make([]byte, 2*len(buf))
   829  	}
   830  	_, err := w.Write(buf)
   831  	return err
   832  }
   833  
   834  func writeRuntimeProfile(w io.Writer, debug int, name string, fetch func([]profilerecord.StackRecord, []unsafe.Pointer) (int, bool)) error {
   835  	// Find out how many records there are (fetch(nil)),
   836  	// allocate that many records, and get the data.
   837  	// There's a race—more records might be added between
   838  	// the two calls—so allocate a few extra records for safety
   839  	// and also try again if we're very unlucky.
   840  	// The loop should only execute one iteration in the common case.
   841  	var p []profilerecord.StackRecord
   842  	var labels []unsafe.Pointer
   843  	n, ok := fetch(nil, nil)
   844  
   845  	for {
   846  		// Allocate room for a slightly bigger profile,
   847  		// in case a few more entries have been added
   848  		// since the call to ThreadProfile.
   849  		p = make([]profilerecord.StackRecord, n+10)
   850  		labels = make([]unsafe.Pointer, n+10)
   851  		n, ok = fetch(p, labels)
   852  		if ok {
   853  			p = p[0:n]
   854  			break
   855  		}
   856  		// Profile grew; try again.
   857  	}
   858  
   859  	return printCountProfile(w, debug, name, &runtimeProfile{p, labels})
   860  }
   861  
   862  type runtimeProfile struct {
   863  	stk    []profilerecord.StackRecord
   864  	labels []unsafe.Pointer
   865  }
   866  
   867  func (p *runtimeProfile) Len() int              { return len(p.stk) }
   868  func (p *runtimeProfile) Stack(i int) []uintptr { return p.stk[i].Stack }
   869  func (p *runtimeProfile) Label(i int) *labelMap { return (*labelMap)(p.labels[i]) }
   870  
   871  var cpu struct {
   872  	sync.Mutex
   873  	profiling bool
   874  	done      chan bool
   875  }
   876  
   877  // StartCPUProfile enables CPU profiling for the current process.
   878  // While profiling, the profile will be buffered and written to w.
   879  // StartCPUProfile returns an error if profiling is already enabled.
   880  //
   881  // On Unix-like systems, StartCPUProfile does not work by default for
   882  // Go code built with -buildmode=c-archive or -buildmode=c-shared.
   883  // StartCPUProfile relies on the SIGPROF signal, but that signal will
   884  // be delivered to the main program's SIGPROF signal handler (if any)
   885  // not to the one used by Go. To make it work, call [os/signal.Notify]
   886  // for [syscall.SIGPROF], but note that doing so may break any profiling
   887  // being done by the main program.
   888  func StartCPUProfile(w io.Writer) error {
   889  	// The runtime routines allow a variable profiling rate,
   890  	// but in practice operating systems cannot trigger signals
   891  	// at more than about 500 Hz, and our processing of the
   892  	// signal is not cheap (mostly getting the stack trace).
   893  	// 100 Hz is a reasonable choice: it is frequent enough to
   894  	// produce useful data, rare enough not to bog down the
   895  	// system, and a nice round number to make it easy to
   896  	// convert sample counts to seconds. Instead of requiring
   897  	// each client to specify the frequency, we hard code it.
   898  	const hz = 100
   899  
   900  	cpu.Lock()
   901  	defer cpu.Unlock()
   902  	if cpu.done == nil {
   903  		cpu.done = make(chan bool)
   904  	}
   905  	// Double-check.
   906  	if cpu.profiling {
   907  		return fmt.Errorf("cpu profiling already in use")
   908  	}
   909  	cpu.profiling = true
   910  	runtime.SetCPUProfileRate(hz)
   911  	go profileWriter(w)
   912  	return nil
   913  }
   914  
   915  // readProfile, provided by the runtime, returns the next chunk of
   916  // binary CPU profiling stack trace data, blocking until data is available.
   917  // If profiling is turned off and all the profile data accumulated while it was
   918  // on has been returned, readProfile returns eof=true.
   919  // The caller must save the returned data and tags before calling readProfile again.
   920  func readProfile() (data []uint64, tags []unsafe.Pointer, eof bool)
   921  
   922  func profileWriter(w io.Writer) {
   923  	b := newProfileBuilder(w)
   924  	var err error
   925  	for {
   926  		if runtime.GOOS == "darwin" || runtime.GOOS == "ios" {
   927  			// see runtime_pprof_readProfile
   928  			time.Sleep(100 * time.Millisecond)
   929  		}
   930  		data, tags, eof := readProfile()
   931  		if e := b.addCPUData(data, tags); e != nil && err == nil {
   932  			err = e
   933  		}
   934  		if eof {
   935  			break
   936  		}
   937  	}
   938  	if err != nil {
   939  		// The runtime should never produce an invalid or truncated profile.
   940  		// It drops records that can't fit into its log buffers.
   941  		panic("runtime/pprof: converting profile: " + err.Error())
   942  	}
   943  	b.build()
   944  	cpu.done <- true
   945  }
   946  
   947  // StopCPUProfile stops the current CPU profile, if any.
   948  // StopCPUProfile only returns after all the writes for the
   949  // profile have completed.
   950  func StopCPUProfile() {
   951  	cpu.Lock()
   952  	defer cpu.Unlock()
   953  
   954  	if !cpu.profiling {
   955  		return
   956  	}
   957  	cpu.profiling = false
   958  	runtime.SetCPUProfileRate(0)
   959  	<-cpu.done
   960  }
   961  
   962  // countBlock returns the number of records in the blocking profile.
   963  func countBlock() int {
   964  	n, _ := runtime.BlockProfile(nil)
   965  	return n
   966  }
   967  
   968  // countMutex returns the number of records in the mutex profile.
   969  func countMutex() int {
   970  	n, _ := runtime.MutexProfile(nil)
   971  	return n
   972  }
   973  
   974  // writeBlock writes the current blocking profile to w.
   975  func writeBlock(w io.Writer, debug int) error {
   976  	return writeProfileInternal(w, debug, "contention", pprof_blockProfileInternal)
   977  }
   978  
   979  // writeMutex writes the current mutex profile to w.
   980  func writeMutex(w io.Writer, debug int) error {
   981  	return writeProfileInternal(w, debug, "mutex", pprof_mutexProfileInternal)
   982  }
   983  
   984  // writeProfileInternal writes the current blocking or mutex profile depending on the passed parameters.
   985  func writeProfileInternal(w io.Writer, debug int, name string, runtimeProfile func([]profilerecord.BlockProfileRecord) (int, bool)) error {
   986  	var p []profilerecord.BlockProfileRecord
   987  	n, ok := runtimeProfile(nil)
   988  	for {
   989  		p = make([]profilerecord.BlockProfileRecord, n+50)
   990  		n, ok = runtimeProfile(p)
   991  		if ok {
   992  			p = p[:n]
   993  			break
   994  		}
   995  	}
   996  
   997  	slices.SortFunc(p, func(a, b profilerecord.BlockProfileRecord) int {
   998  		return cmp.Compare(b.Cycles, a.Cycles)
   999  	})
  1000  
  1001  	if debug <= 0 {
  1002  		return printCountCycleProfile(w, "contentions", "delay", p)
  1003  	}
  1004  
  1005  	b := bufio.NewWriter(w)
  1006  	tw := tabwriter.NewWriter(w, 1, 8, 1, '\t', 0)
  1007  	w = tw
  1008  
  1009  	fmt.Fprintf(w, "--- %v:\n", name)
  1010  	fmt.Fprintf(w, "cycles/second=%v\n", pprof_cyclesPerSecond())
  1011  	if name == "mutex" {
  1012  		fmt.Fprintf(w, "sampling period=%d\n", runtime.SetMutexProfileFraction(-1))
  1013  	}
  1014  	expandedStack := pprof_makeProfStack()
  1015  	for i := range p {
  1016  		r := &p[i]
  1017  		fmt.Fprintf(w, "%v %v @", r.Cycles, r.Count)
  1018  		n := expandInlinedFrames(expandedStack, r.Stack)
  1019  		stack := expandedStack[:n]
  1020  		for _, pc := range stack {
  1021  			fmt.Fprintf(w, " %#x", pc)
  1022  		}
  1023  		fmt.Fprint(w, "\n")
  1024  		if debug > 0 {
  1025  			printStackRecord(w, stack, true)
  1026  		}
  1027  	}
  1028  
  1029  	if tw != nil {
  1030  		tw.Flush()
  1031  	}
  1032  	return b.Flush()
  1033  }
  1034  
  1035  //go:linkname pprof_goroutineProfileWithLabels runtime.pprof_goroutineProfileWithLabels
  1036  func pprof_goroutineProfileWithLabels(p []profilerecord.StackRecord, labels []unsafe.Pointer) (n int, ok bool)
  1037  
  1038  //go:linkname pprof_goroutineLeakProfileWithLabels runtime.pprof_goroutineLeakProfileWithLabels
  1039  func pprof_goroutineLeakProfileWithLabels(p []profilerecord.StackRecord, labels []unsafe.Pointer) (n int, ok bool)
  1040  
  1041  //go:linkname pprof_cyclesPerSecond runtime/pprof.runtime_cyclesPerSecond
  1042  func pprof_cyclesPerSecond() int64
  1043  
  1044  //go:linkname pprof_memProfileInternal runtime.pprof_memProfileInternal
  1045  func pprof_memProfileInternal(p []profilerecord.MemProfileRecord, inuseZero bool) (n int, ok bool)
  1046  
  1047  //go:linkname pprof_blockProfileInternal runtime.pprof_blockProfileInternal
  1048  func pprof_blockProfileInternal(p []profilerecord.BlockProfileRecord) (n int, ok bool)
  1049  
  1050  //go:linkname pprof_mutexProfileInternal runtime.pprof_mutexProfileInternal
  1051  func pprof_mutexProfileInternal(p []profilerecord.BlockProfileRecord) (n int, ok bool)
  1052  
  1053  //go:linkname pprof_threadCreateInternal runtime.pprof_threadCreateInternal
  1054  func pprof_threadCreateInternal(p []profilerecord.StackRecord) (n int, ok bool)
  1055  
  1056  //go:linkname pprof_fpunwindExpand runtime.pprof_fpunwindExpand
  1057  func pprof_fpunwindExpand(dst, src []uintptr) int
  1058  
  1059  //go:linkname pprof_makeProfStack runtime.pprof_makeProfStack
  1060  func pprof_makeProfStack() []uintptr
  1061  

View as plain text