qbit/go
1
0
Fork 0
mirror of https://github.com/golang/go synced 2024-11-23 07:20:06 -07:00
Code Releases Activity

runtime/pprof: add section headers to Profile doc

Browse Source 
Adding explicit section headers makes it cleaner to split the profile
descriptions into multiple paragraphs, as there is now an explicit
transition from discussion of one profile type to the next.

For #14689.

Change-Id: Ifcff918367e91a165ee5f74423be3935b421972b
Reviewed-on: https://go-review.googlesource.com/c/go/+/547955
Reviewed-by: Rhys Hiltner <rhys@justin.tv>
Reviewed-by: Michael Knyszek <mknyszek@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Auto-Submit: Michael Pratt <mpratt@google.com>
This commit is contained in:
Michael Pratt 2023-12-06 12:34:02 -05:00 committed by Gopher Robot
parent 6ee2719854
commit e914671f5d
1 changed files with 35 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
src/runtime/pprof/pprof.go
View File

@ -109,6 +109,12 @@ import (
// These predefined profiles maintain themselves and panic on an explicit
// [Profile.Add] or [Profile.Remove] method call.
//
// The CPU profile is not available as a Profile. It has a special API,
// the [StartCPUProfile] and [StopCPUProfile] functions, because it streams
// output to a writer during profiling.
//
// # Heap profile
//
// The heap profile reports statistics as of the most recently completed
// garbage collection; it elides more recent allocation to avoid skewing
// the profile away from live data and toward garbage.
@ -122,38 +128,47 @@ import (
// flags select which to display, defaulting to -inuse_space (live objects,
// scaled by size).
//
// # Allocs profile
//
// The allocs profile is the same as the heap profile but changes the default
// pprof display to -alloc_space, the total number of bytes allocated since
// the program began (including garbage-collected bytes).
//
// # Block profile
//
// The block profile tracks time spent blocked on synchronization primitives,
// such as [sync.Mutex], [sync.RWMutex], [sync.WaitGroup], [sync.Cond], and
// channel send/receive/select. Stack traces correspond to the location that
// blocked (for example, [sync.Mutex.Lock]). Sample values correspond to
// cumulative time spent blocked at that stack trace, subject to time-based
// sampling specified by [runtime.SetBlockProfileRate].
// channel send/receive/select.
//
// Stack traces correspond to the location that blocked (for example,
// [sync.Mutex.Lock]).
//
// Sample values correspond to cumulative time spent blocked at that stack
// trace, subject to time-based sampling specified by
// [runtime.SetBlockProfileRate].
//
// # Mutex profile
//
// The mutex profile tracks contention on mutexes, such as [sync.Mutex],
// [sync.RWMutex], and runtime-internal locks. Stack traces correspond to the
// end of the critical section causing contention. For example, a lock held for
// a long time while other goroutines are waiting to acquire the lock will
// report contention when the lock is finally unlocked (that is, at
// [sync.Mutex.Unlock]). Sample values correspond to the approximate cumulative
// time other goroutines spent blocked waiting for the lock, subject to
// event-based sampling specified by [runtime.SetMutexProfileFraction]. For
// example, if a caller holds a lock for 1s while 5 other goroutines are
// waiting for the entire second to acquire the lock, its unlock call stack
// will report 5s of contention.
// [sync.RWMutex], and runtime-internal locks.
//
// In the mutex profile, runtime-internal locks are always reported at the
// location "runtime._LostContendedRuntimeLock". More detailed stack traces for
// Stack traces correspond to the end of the critical section causing
// contention. For example, a lock held for a long time while other goroutines
// are waiting to acquire the lock will report contention when the lock is
// finally unlocked (that is, at [sync.Mutex.Unlock]).
//
// Sample values correspond to the approximate cumulative time other goroutines
// spent blocked waiting for the lock, subject to event-based sampling
// specified by [runtime.SetMutexProfileFraction]. For example, if a caller
// holds a lock for 1s while 5 other goroutines are waiting for the entire
// second to acquire the lock, its unlock call stack will report 5s of
// contention.
//
// Runtime-internal locks are always reported at the location
// "runtime._LostContendedRuntimeLock". More detailed stack traces for
// runtime-internal locks can be obtained by setting
// `GODEBUG=runtimecontentionstacks=1` (see package [runtime] docs for
// caveats).
//
// The CPU profile is not available as a Profile. It has a special API,
// the [StartCPUProfile] and [StopCPUProfile] functions, because it streams
// output to a writer during profiling.
type Profile struct {
name string
mu sync.Mutex