| // Copyright 2020 The Go Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style |
| // license that can be found in the LICENSE file. |
| |
| // Note: run 'go generate' (which will run 'go test -generate') to update the "Supported metrics" list. |
| //go:generate go test -run=Docs -generate |
| |
| /* |
| Package metrics provides a stable interface to access implementation-defined |
| metrics exported by the Go runtime. This package is similar to existing functions |
| like [runtime.ReadMemStats] and [debug.ReadGCStats], but significantly more general. |
| |
| The set of metrics defined by this package may evolve as the runtime itself |
| evolves, and also enables variation across Go implementations, whose relevant |
| metric sets may not intersect. |
| |
| # Interface |
| |
| Metrics are designated by a string key, rather than, for example, a field name in |
| a struct. The full list of supported metrics is always available in the slice of |
| Descriptions returned by All. Each Description also includes useful information |
| about the metric. |
| |
| Thus, users of this API are encouraged to sample supported metrics defined by the |
| slice returned by All to remain compatible across Go versions. Of course, situations |
| arise where reading specific metrics is critical. For these cases, users are |
| encouraged to use build tags, and although metrics may be deprecated and removed, |
| users should consider this to be an exceptional and rare event, coinciding with a |
| very large change in a particular Go implementation. |
| |
| Each metric key also has a "kind" that describes the format of the metric's value. |
| In the interest of not breaking users of this package, the "kind" for a given metric |
| is guaranteed not to change. If it must change, then a new metric will be introduced |
| with a new key and a new "kind." |
| |
| # Metric key format |
| |
| As mentioned earlier, metric keys are strings. Their format is simple and well-defined, |
| designed to be both human and machine readable. It is split into two components, |
| separated by a colon: a rooted path and a unit. The choice to include the unit in |
| the key is motivated by compatibility: if a metric's unit changes, its semantics likely |
| did also, and a new key should be introduced. |
| |
| For more details on the precise definition of the metric key's path and unit formats, see |
| the documentation of the Name field of the Description struct. |
| |
| # A note about floats |
| |
| This package supports metrics whose values have a floating-point representation. In |
| order to improve ease-of-use, this package promises to never produce the following |
| classes of floating-point values: NaN, infinity. |
| |
| # Supported metrics |
| |
| Below is the full list of supported metrics, ordered lexicographically. |
| |
| /cgo/go-to-c-calls:calls |
| Count of calls made from Go to C by the current process. |
| |
| /cpu/classes/gc/mark/assist:cpu-seconds |
| Estimated total CPU time goroutines spent performing GC |
| tasks to assist the GC and prevent it from falling behind the |
| application. This metric is an overestimate, and not directly |
| comparable to system CPU time measurements. Compare only with |
| other /cpu/classes metrics. |
| |
| /cpu/classes/gc/mark/dedicated:cpu-seconds |
| Estimated total CPU time spent performing GC tasks on processors |
| (as defined by GOMAXPROCS) dedicated to those tasks. This metric |
| is an overestimate, and not directly comparable to system CPU |
| time measurements. Compare only with other /cpu/classes metrics. |
| |
| /cpu/classes/gc/mark/idle:cpu-seconds |
| Estimated total CPU time spent performing GC tasks on spare CPU |
| resources that the Go scheduler could not otherwise find a use |
| for. This should be subtracted from the total GC CPU time to |
| obtain a measure of compulsory GC CPU time. This metric is an |
| overestimate, and not directly comparable to system CPU time |
| measurements. Compare only with other /cpu/classes metrics. |
| |
| /cpu/classes/gc/pause:cpu-seconds |
| Estimated total CPU time spent with the application paused by |
| the GC. Even if only one thread is running during the pause, |
| this is computed as GOMAXPROCS times the pause latency because |
| nothing else can be executing. This is the exact sum of samples |
| in /gc/pause:seconds if each sample is multiplied by GOMAXPROCS |
| at the time it is taken. This metric is an overestimate, |
| and not directly comparable to system CPU time measurements. |
| Compare only with other /cpu/classes metrics. |
| |
| /cpu/classes/gc/total:cpu-seconds |
| Estimated total CPU time spent performing GC tasks. This metric |
| is an overestimate, and not directly comparable to system CPU |
| time measurements. Compare only with other /cpu/classes metrics. |
| Sum of all metrics in /cpu/classes/gc. |
| |
| /cpu/classes/idle:cpu-seconds |
| Estimated total available CPU time not spent executing |
| any Go or Go runtime code. In other words, the part of |
| /cpu/classes/total:cpu-seconds that was unused. This metric is |
| an overestimate, and not directly comparable to system CPU time |
| measurements. Compare only with other /cpu/classes metrics. |
| |
| /cpu/classes/scavenge/assist:cpu-seconds |
| Estimated total CPU time spent returning unused memory to the |
| underlying platform in response eagerly in response to memory |
| pressure. This metric is an overestimate, and not directly |
| comparable to system CPU time measurements. Compare only with |
| other /cpu/classes metrics. |
| |
| /cpu/classes/scavenge/background:cpu-seconds |
| Estimated total CPU time spent performing background tasks to |
| return unused memory to the underlying platform. This metric is |
| an overestimate, and not directly comparable to system CPU time |
| measurements. Compare only with other /cpu/classes metrics. |
| |
| /cpu/classes/scavenge/total:cpu-seconds |
| Estimated total CPU time spent performing tasks that return |
| unused memory to the underlying platform. This metric is an |
| overestimate, and not directly comparable to system CPU time |
| measurements. Compare only with other /cpu/classes metrics. |
| Sum of all metrics in /cpu/classes/scavenge. |
| |
| /cpu/classes/total:cpu-seconds |
| Estimated total available CPU time for user Go code or the Go |
| runtime, as defined by GOMAXPROCS. In other words, GOMAXPROCS |
| integrated over the wall-clock duration this process has been |
| executing for. This metric is an overestimate, and not directly |
| comparable to system CPU time measurements. Compare only with |
| other /cpu/classes metrics. Sum of all metrics in /cpu/classes. |
| |
| /cpu/classes/user:cpu-seconds |
| Estimated total CPU time spent running user Go code. This may |
| also include some small amount of time spent in the Go runtime. |
| This metric is an overestimate, and not directly comparable |
| to system CPU time measurements. Compare only with other |
| /cpu/classes metrics. |
| |
| /gc/cycles/automatic:gc-cycles |
| Count of completed GC cycles generated by the Go runtime. |
| |
| /gc/cycles/forced:gc-cycles |
| Count of completed GC cycles forced by the application. |
| |
| /gc/cycles/total:gc-cycles |
| Count of all completed GC cycles. |
| |
| /gc/gogc:percent |
| Heap size target percentage configured by the user, otherwise |
| 100. This value is set by the GOGC environment variable, and the |
| runtime/debug.SetGCPercent function. |
| |
| /gc/gomemlimit:bytes |
| Go runtime memory limit configured by the user, otherwise |
| math.MaxInt64. This value is set by the GOMEMLIMIT environment |
| variable, and the runtime/debug.SetMemoryLimit function. |
| |
| /gc/heap/allocs-by-size:bytes |
| Distribution of heap allocations by approximate size. |
| Bucket counts increase monotonically. Note that this does not |
| include tiny objects as defined by /gc/heap/tiny/allocs:objects, |
| only tiny blocks. |
| |
| /gc/heap/allocs:bytes |
| Cumulative sum of memory allocated to the heap by the |
| application. |
| |
| /gc/heap/allocs:objects |
| Cumulative count of heap allocations triggered by the |
| application. Note that this does not include tiny objects as |
| defined by /gc/heap/tiny/allocs:objects, only tiny blocks. |
| |
| /gc/heap/frees-by-size:bytes |
| Distribution of freed heap allocations by approximate size. |
| Bucket counts increase monotonically. Note that this does not |
| include tiny objects as defined by /gc/heap/tiny/allocs:objects, |
| only tiny blocks. |
| |
| /gc/heap/frees:bytes |
| Cumulative sum of heap memory freed by the garbage collector. |
| |
| /gc/heap/frees:objects |
| Cumulative count of heap allocations whose storage was freed |
| by the garbage collector. Note that this does not include tiny |
| objects as defined by /gc/heap/tiny/allocs:objects, only tiny |
| blocks. |
| |
| /gc/heap/goal:bytes |
| Heap size target for the end of the GC cycle. |
| |
| /gc/heap/live:bytes |
| Heap memory occupied by live objects that were marked by the |
| previous GC. |
| |
| /gc/heap/objects:objects |
| Number of objects, live or unswept, occupying heap memory. |
| |
| /gc/heap/tiny/allocs:objects |
| Count of small allocations that are packed together into blocks. |
| These allocations are counted separately from other allocations |
| because each individual allocation is not tracked by the |
| runtime, only their block. Each block is already accounted for |
| in allocs-by-size and frees-by-size. |
| |
| /gc/limiter/last-enabled:gc-cycle |
| GC cycle the last time the GC CPU limiter was enabled. |
| This metric is useful for diagnosing the root cause of an |
| out-of-memory error, because the limiter trades memory for CPU |
| time when the GC's CPU time gets too high. This is most likely |
| to occur with use of SetMemoryLimit. The first GC cycle is cycle |
| 1, so a value of 0 indicates that it was never enabled. |
| |
| /gc/pauses:seconds |
| Distribution of individual GC-related stop-the-world pause |
| latencies. Bucket counts increase monotonically. |
| |
| /gc/scan/globals:bytes |
| The total amount of global variable space that is scannable. |
| |
| /gc/scan/heap:bytes |
| The total amount of heap space that is scannable. |
| |
| /gc/scan/stack:bytes |
| The number of bytes of stack that were scanned last GC cycle. |
| |
| /gc/scan/total:bytes |
| The total amount space that is scannable. Sum of all metrics in |
| /gc/scan. |
| |
| /gc/stack/starting-size:bytes |
| The stack size of new goroutines. |
| |
| /godebug/non-default-behavior/execerrdot:events |
| The number of non-default behaviors executed by the os/exec |
| package due to a non-default GODEBUG=execerrdot=... setting. |
| |
| /godebug/non-default-behavior/gocachehash:events |
| The number of non-default behaviors executed by the cmd/go |
| package due to a non-default GODEBUG=gocachehash=... setting. |
| |
| /godebug/non-default-behavior/gocachetest:events |
| The number of non-default behaviors executed by the cmd/go |
| package due to a non-default GODEBUG=gocachetest=... setting. |
| |
| /godebug/non-default-behavior/gocacheverify:events |
| The number of non-default behaviors executed by the cmd/go |
| package due to a non-default GODEBUG=gocacheverify=... setting. |
| |
| /godebug/non-default-behavior/http2client:events |
| The number of non-default behaviors executed by the net/http |
| package due to a non-default GODEBUG=http2client=... setting. |
| |
| /godebug/non-default-behavior/http2server:events |
| The number of non-default behaviors executed by the net/http |
| package due to a non-default GODEBUG=http2server=... setting. |
| |
| /godebug/non-default-behavior/installgoroot:events |
| The number of non-default behaviors executed by the go/build |
| package due to a non-default GODEBUG=installgoroot=... setting. |
| |
| /godebug/non-default-behavior/jstmpllitinterp:events |
| The number of non-default behaviors executed by |
| the html/template package due to a non-default |
| GODEBUG=jstmpllitinterp=... setting. |
| |
| /godebug/non-default-behavior/multipartmaxheaders:events |
| The number of non-default behaviors executed by |
| the mime/multipart package due to a non-default |
| GODEBUG=multipartmaxheaders=... setting. |
| |
| /godebug/non-default-behavior/multipartmaxparts:events |
| The number of non-default behaviors executed by |
| the mime/multipart package due to a non-default |
| GODEBUG=multipartmaxparts=... setting. |
| |
| /godebug/non-default-behavior/panicnil:events |
| The number of non-default behaviors executed by the runtime |
| package due to a non-default GODEBUG=panicnil=... setting. |
| |
| /godebug/non-default-behavior/randautoseed:events |
| The number of non-default behaviors executed by the math/rand |
| package due to a non-default GODEBUG=randautoseed=... setting. |
| |
| /godebug/non-default-behavior/tarinsecurepath:events |
| The number of non-default behaviors executed by the archive/tar |
| package due to a non-default GODEBUG=tarinsecurepath=... |
| setting. |
| |
| /godebug/non-default-behavior/x509sha1:events |
| The number of non-default behaviors executed by the crypto/x509 |
| package due to a non-default GODEBUG=x509sha1=... setting. |
| |
| /godebug/non-default-behavior/x509usefallbackroots:events |
| The number of non-default behaviors executed by the crypto/x509 |
| package due to a non-default GODEBUG=x509usefallbackroots=... |
| setting. |
| |
| /godebug/non-default-behavior/zipinsecurepath:events |
| The number of non-default behaviors executed by the archive/zip |
| package due to a non-default GODEBUG=zipinsecurepath=... |
| setting. |
| |
| /memory/classes/heap/free:bytes |
| Memory that is completely free and eligible to be returned to |
| the underlying system, but has not been. This metric is the |
| runtime's estimate of free address space that is backed by |
| physical memory. |
| |
| /memory/classes/heap/objects:bytes |
| Memory occupied by live objects and dead objects that have not |
| yet been marked free by the garbage collector. |
| |
| /memory/classes/heap/released:bytes |
| Memory that is completely free and has been returned to the |
| underlying system. This metric is the runtime's estimate of free |
| address space that is still mapped into the process, but is not |
| backed by physical memory. |
| |
| /memory/classes/heap/stacks:bytes |
| Memory allocated from the heap that is reserved for stack space, |
| whether or not it is currently in-use. Currently, this |
| represents all stack memory for goroutines. It also includes all |
| OS thread stacks in non-cgo programs. Note that stacks may be |
| allocated differently in the future, and this may change. |
| |
| /memory/classes/heap/unused:bytes |
| Memory that is reserved for heap objects but is not currently |
| used to hold heap objects. |
| |
| /memory/classes/metadata/mcache/free:bytes |
| Memory that is reserved for runtime mcache structures, but not |
| in-use. |
| |
| /memory/classes/metadata/mcache/inuse:bytes |
| Memory that is occupied by runtime mcache structures that are |
| currently being used. |
| |
| /memory/classes/metadata/mspan/free:bytes |
| Memory that is reserved for runtime mspan structures, but not |
| in-use. |
| |
| /memory/classes/metadata/mspan/inuse:bytes |
| Memory that is occupied by runtime mspan structures that are |
| currently being used. |
| |
| /memory/classes/metadata/other:bytes |
| Memory that is reserved for or used to hold runtime metadata. |
| |
| /memory/classes/os-stacks:bytes |
| Stack memory allocated by the underlying operating system. |
| In non-cgo programs this metric is currently zero. This may |
| change in the future.In cgo programs this metric includes |
| OS thread stacks allocated directly from the OS. Currently, |
| this only accounts for one stack in c-shared and c-archive build |
| modes, and other sources of stacks from the OS are not measured. |
| This too may change in the future. |
| |
| /memory/classes/other:bytes |
| Memory used by execution trace buffers, structures for debugging |
| the runtime, finalizer and profiler specials, and more. |
| |
| /memory/classes/profiling/buckets:bytes |
| Memory that is used by the stack trace hash map used for |
| profiling. |
| |
| /memory/classes/total:bytes |
| All memory mapped by the Go runtime into the current process |
| as read-write. Note that this does not include memory mapped |
| by code called via cgo or via the syscall package. Sum of all |
| metrics in /memory/classes. |
| |
| /sched/gomaxprocs:threads |
| The current runtime.GOMAXPROCS setting, or the number of |
| operating system threads that can execute user-level Go code |
| simultaneously. |
| |
| /sched/goroutines:goroutines |
| Count of live goroutines. |
| |
| /sched/latencies:seconds |
| Distribution of the time goroutines have spent in the scheduler |
| in a runnable state before actually running. Bucket counts |
| increase monotonically. |
| |
| /sync/mutex/wait/total:seconds |
| Approximate cumulative time goroutines have spent blocked |
| on a sync.Mutex or sync.RWMutex. This metric is useful for |
| identifying global changes in lock contention. Collect a mutex |
| or block profile using the runtime/pprof package for more |
| detailed contention data. |
| */ |
| package metrics |