Source file src/runtime/metrics/doc.go
1 // Copyright 2020 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 /* 6 Package metrics provides a stable interface to access implementation-defined 7 metrics exported by the Go runtime. This package is similar to existing functions 8 like runtime.ReadMemStats and debug.ReadGCStats, but significantly more general. 9 10 The set of metrics defined by this package may evolve as the runtime itself 11 evolves, and also enables variation across Go implementations, whose relevant 12 metric sets may not intersect. 13 14 # Interface 15 16 Metrics are designated by a string key, rather than, for example, a field name in 17 a struct. The full list of supported metrics is always available in the slice of 18 Descriptions returned by All. Each Description also includes useful information 19 about the metric. 20 21 Thus, users of this API are encouraged to sample supported metrics defined by the 22 slice returned by All to remain compatible across Go versions. Of course, situations 23 arise where reading specific metrics is critical. For these cases, users are 24 encouraged to use build tags, and although metrics may be deprecated and removed, 25 users should consider this to be an exceptional and rare event, coinciding with a 26 very large change in a particular Go implementation. 27 28 Each metric key also has a "kind" that describes the format of the metric's value. 29 In the interest of not breaking users of this package, the "kind" for a given metric 30 is guaranteed not to change. If it must change, then a new metric will be introduced 31 with a new key and a new "kind." 32 33 # Metric key format 34 35 As mentioned earlier, metric keys are strings. Their format is simple and well-defined, 36 designed to be both human and machine readable. It is split into two components, 37 separated by a colon: a rooted path and a unit. The choice to include the unit in 38 the key is motivated by compatibility: if a metric's unit changes, its semantics likely 39 did also, and a new key should be introduced. 40 41 For more details on the precise definition of the metric key's path and unit formats, see 42 the documentation of the Name field of the Description struct. 43 44 # A note about floats 45 46 This package supports metrics whose values have a floating-point representation. In 47 order to improve ease-of-use, this package promises to never produce the following 48 classes of floating-point values: NaN, infinity. 49 50 # Supported metrics 51 52 Below is the full list of supported metrics, ordered lexicographically. 53 54 /cgo/go-to-c-calls:calls 55 Count of calls made from Go to C by the current process. 56 57 /cpu/classes/gc/mark/assist:cpu-seconds 58 Estimated total CPU time goroutines spent performing GC tasks 59 to assist the GC and prevent it from falling behind the application. 60 This metric is an overestimate, and not directly comparable to 61 system CPU time measurements. Compare only with other /cpu/classes 62 metrics. 63 64 /cpu/classes/gc/mark/dedicated:cpu-seconds 65 Estimated total CPU time spent performing GC tasks on 66 processors (as defined by GOMAXPROCS) dedicated to those tasks. 67 This includes time spent with the world stopped due to the GC. 68 This metric is an overestimate, and not directly comparable to 69 system CPU time measurements. Compare only with other /cpu/classes 70 metrics. 71 72 /cpu/classes/gc/mark/idle:cpu-seconds 73 Estimated total CPU time spent performing GC tasks on 74 spare CPU resources that the Go scheduler could not otherwise find 75 a use for. This should be subtracted from the total GC CPU time to 76 obtain a measure of compulsory GC CPU time. 77 This metric is an overestimate, and not directly comparable to 78 system CPU time measurements. Compare only with other /cpu/classes 79 metrics. 80 81 /cpu/classes/gc/pause:cpu-seconds 82 Estimated total CPU time spent with the application paused by 83 the GC. Even if only one thread is running during the pause, this is 84 computed as GOMAXPROCS times the pause latency because nothing else 85 can be executing. This is the exact sum of samples in /gc/pause:seconds 86 if each sample is multiplied by GOMAXPROCS at the time it is taken. 87 This metric is an overestimate, and not directly comparable to 88 system CPU time measurements. Compare only with other /cpu/classes 89 metrics. 90 91 /cpu/classes/gc/total:cpu-seconds 92 Estimated total CPU time spent performing GC tasks. 93 This metric is an overestimate, and not directly comparable to 94 system CPU time measurements. Compare only with other /cpu/classes 95 metrics. Sum of all metrics in /cpu/classes/gc. 96 97 /cpu/classes/idle:cpu-seconds 98 Estimated total available CPU time not spent executing any Go or Go 99 runtime code. In other words, the part of /cpu/classes/total:cpu-seconds 100 that was unused. 101 This metric is an overestimate, and not directly comparable to 102 system CPU time measurements. Compare only with other /cpu/classes 103 metrics. 104 105 /cpu/classes/scavenge/assist:cpu-seconds 106 Estimated total CPU time spent returning unused memory to the 107 underlying platform in response eagerly in response to memory pressure. 108 This metric is an overestimate, and not directly comparable to 109 system CPU time measurements. Compare only with other /cpu/classes 110 metrics. 111 112 /cpu/classes/scavenge/background:cpu-seconds 113 Estimated total CPU time spent performing background tasks 114 to return unused memory to the underlying platform. 115 This metric is an overestimate, and not directly comparable to 116 system CPU time measurements. Compare only with other /cpu/classes 117 metrics. 118 119 /cpu/classes/scavenge/total:cpu-seconds 120 Estimated total CPU time spent performing tasks that return 121 unused memory to the underlying platform. 122 This metric is an overestimate, and not directly comparable to 123 system CPU time measurements. Compare only with other /cpu/classes 124 metrics. Sum of all metrics in /cpu/classes/scavenge. 125 126 /cpu/classes/total:cpu-seconds 127 Estimated total available CPU time for user Go code or the Go runtime, as 128 defined by GOMAXPROCS. In other words, GOMAXPROCS integrated over the 129 wall-clock duration this process has been executing for. 130 This metric is an overestimate, and not directly comparable to 131 system CPU time measurements. Compare only with other /cpu/classes 132 metrics. Sum of all metrics in /cpu/classes. 133 134 /cpu/classes/user:cpu-seconds 135 Estimated total CPU time spent running user Go code. This may 136 also include some small amount of time spent in the Go runtime. 137 This metric is an overestimate, and not directly comparable to 138 system CPU time measurements. Compare only with other /cpu/classes 139 metrics. 140 141 /gc/cycles/automatic:gc-cycles 142 Count of completed GC cycles generated by the Go runtime. 143 144 /gc/cycles/forced:gc-cycles 145 Count of completed GC cycles forced by the application. 146 147 /gc/cycles/total:gc-cycles 148 Count of all completed GC cycles. 149 150 /gc/heap/allocs-by-size:bytes 151 Distribution of heap allocations by approximate size. 152 Note that this does not include tiny objects as defined by /gc/heap/tiny/allocs:objects, 153 only tiny blocks. 154 155 /gc/heap/allocs:bytes 156 Cumulative sum of memory allocated to the heap by the application. 157 158 /gc/heap/allocs:objects 159 Cumulative count of heap allocations triggered by the application. 160 Note that this does not include tiny objects as defined by /gc/heap/tiny/allocs:objects, 161 only tiny blocks. 162 163 /gc/heap/frees-by-size:bytes 164 Distribution of freed heap allocations by approximate size. 165 Note that this does not include tiny objects as defined by /gc/heap/tiny/allocs:objects, 166 only tiny blocks. 167 168 /gc/heap/frees:bytes 169 Cumulative sum of heap memory freed by the garbage collector. 170 171 /gc/heap/frees:objects 172 Cumulative count of heap allocations whose storage was freed by the garbage collector. 173 Note that this does not include tiny objects as defined by /gc/heap/tiny/allocs:objects, 174 only tiny blocks. 175 176 /gc/heap/goal:bytes 177 Heap size target for the end of the GC cycle. 178 179 /gc/heap/objects:objects 180 Number of objects, live or unswept, occupying heap memory. 181 182 /gc/heap/tiny/allocs:objects 183 Count of small allocations that are packed together into blocks. 184 These allocations are counted separately from other allocations 185 because each individual allocation is not tracked by the runtime, 186 only their block. Each block is already accounted for in 187 allocs-by-size and frees-by-size. 188 189 /gc/limiter/last-enabled:gc-cycle 190 GC cycle the last time the GC CPU limiter was enabled. 191 This metric is useful for diagnosing the root cause of an out-of-memory 192 error, because the limiter trades memory for CPU time when the GC's CPU 193 time gets too high. This is most likely to occur with use of SetMemoryLimit. 194 The first GC cycle is cycle 1, so a value of 0 indicates that it was never enabled. 195 196 /gc/pauses:seconds 197 Distribution individual GC-related stop-the-world pause latencies. 198 199 /gc/stack/starting-size:bytes 200 The stack size of new goroutines. 201 202 /memory/classes/heap/free:bytes 203 Memory that is completely free and eligible to be returned to 204 the underlying system, but has not been. This metric is the 205 runtime's estimate of free address space that is backed by 206 physical memory. 207 208 /memory/classes/heap/objects:bytes 209 Memory occupied by live objects and dead objects that have 210 not yet been marked free by the garbage collector. 211 212 /memory/classes/heap/released:bytes 213 Memory that is completely free and has been returned to 214 the underlying system. This metric is the runtime's estimate of 215 free address space that is still mapped into the process, but 216 is not backed by physical memory. 217 218 /memory/classes/heap/stacks:bytes 219 Memory allocated from the heap that is reserved for stack 220 space, whether or not it is currently in-use. 221 222 /memory/classes/heap/unused:bytes 223 Memory that is reserved for heap objects but is not currently 224 used to hold heap objects. 225 226 /memory/classes/metadata/mcache/free:bytes 227 Memory that is reserved for runtime mcache structures, but 228 not in-use. 229 230 /memory/classes/metadata/mcache/inuse:bytes 231 Memory that is occupied by runtime mcache structures that 232 are currently being used. 233 234 /memory/classes/metadata/mspan/free:bytes 235 Memory that is reserved for runtime mspan structures, but 236 not in-use. 237 238 /memory/classes/metadata/mspan/inuse:bytes 239 Memory that is occupied by runtime mspan structures that are 240 currently being used. 241 242 /memory/classes/metadata/other:bytes 243 Memory that is reserved for or used to hold runtime 244 metadata. 245 246 /memory/classes/os-stacks:bytes 247 Stack memory allocated by the underlying operating system. 248 249 /memory/classes/other:bytes 250 Memory used by execution trace buffers, structures for 251 debugging the runtime, finalizer and profiler specials, and 252 more. 253 254 /memory/classes/profiling/buckets:bytes 255 Memory that is used by the stack trace hash map used for 256 profiling. 257 258 /memory/classes/total:bytes 259 All memory mapped by the Go runtime into the current process 260 as read-write. Note that this does not include memory mapped 261 by code called via cgo or via the syscall package. 262 Sum of all metrics in /memory/classes. 263 264 /sched/gomaxprocs:threads 265 The current runtime.GOMAXPROCS setting, or the number of 266 operating system threads that can execute user-level Go code 267 simultaneously. 268 269 /sched/goroutines:goroutines 270 Count of live goroutines. 271 272 /sched/latencies:seconds 273 Distribution of the time goroutines have spent in the scheduler 274 in a runnable state before actually running. 275 276 /sync/mutex/wait/total:seconds 277 Approximate cumulative time goroutines have spent blocked on a 278 sync.Mutex or sync.RWMutex. This metric is useful for identifying 279 global changes in lock contention. Collect a mutex or block 280 profile using the runtime/pprof package for more detailed 281 contention data. 282 */ 283 package metrics 284