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