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 // Note: run 'go generate' (which will run 'go test -generate') to update the "Supported metrics" list. 6 //go:generate go test -run=Docs -generate 7 8 /* 9 Package metrics provides a stable interface to access implementation-defined 10 metrics exported by the Go runtime. This package is similar to existing functions 11 like [runtime.ReadMemStats] and [runtime/debug.ReadGCStats], but significantly more general. 12 13 The set of metrics defined by this package may evolve as the runtime itself 14 evolves, and also enables variation across Go implementations, whose relevant 15 metric sets may not intersect. 16 17 # Interface 18 19 Metrics are designated by a string key, rather than, for example, a field name in 20 a struct. The full list of supported metrics is always available in the slice of 21 Descriptions returned by [All]. Each [Description] also includes useful information 22 about the metric. 23 24 Thus, users of this API are encouraged to sample supported metrics defined by the 25 slice returned by All to remain compatible across Go versions. Of course, situations 26 arise where reading specific metrics is critical. For these cases, users are 27 encouraged to use build tags, and although metrics may be deprecated and removed, 28 users should consider this to be an exceptional and rare event, coinciding with a 29 very large change in a particular Go implementation. 30 31 Each metric key also has a "kind" (see [ValueKind]) that describes the format of the 32 metric's value. 33 In the interest of not breaking users of this package, the "kind" for a given metric 34 is guaranteed not to change. If it must change, then a new metric will be introduced 35 with a new key and a new "kind." 36 37 # Metric key format 38 39 As mentioned earlier, metric keys are strings. Their format is simple and well-defined, 40 designed to be both human and machine readable. It is split into two components, 41 separated by a colon: a rooted path and a unit. The choice to include the unit in 42 the key is motivated by compatibility: if a metric's unit changes, its semantics likely 43 did also, and a new key should be introduced. 44 45 For more details on the precise definition of the metric key's path and unit formats, see 46 the documentation of the Name field of the Description struct. 47 48 # A note about floats 49 50 This package supports metrics whose values have a floating-point representation. In 51 order to improve ease-of-use, this package promises to never produce the following 52 classes of floating-point values: NaN, infinity. 53 54 # Supported metrics 55 56 Below is the full list of supported metrics, ordered lexicographically. 57 58 /cgo/go-to-c-calls:calls 59 Count of calls made from Go to C by the current process. 60 61 /cpu/classes/gc/mark/assist:cpu-seconds 62 Estimated total CPU time goroutines spent performing GC 63 tasks to assist the GC and prevent it from falling behind the 64 application. This metric is an overestimate, and not directly 65 comparable to system CPU time measurements. Compare only with 66 other /cpu/classes metrics. 67 68 /cpu/classes/gc/mark/dedicated:cpu-seconds 69 Estimated total CPU time spent performing GC tasks on processors 70 (as defined by GOMAXPROCS) dedicated to those tasks. This metric 71 is an overestimate, and not directly comparable to system CPU 72 time measurements. Compare only with other /cpu/classes metrics. 73 74 /cpu/classes/gc/mark/idle:cpu-seconds 75 Estimated total CPU time spent performing GC tasks on spare CPU 76 resources that the Go scheduler could not otherwise find a use 77 for. This should be subtracted from the total GC CPU time to 78 obtain a measure of compulsory GC CPU time. This metric is an 79 overestimate, and not directly comparable to system CPU time 80 measurements. Compare only with other /cpu/classes metrics. 81 82 /cpu/classes/gc/pause:cpu-seconds 83 Estimated total CPU time spent with the application paused by 84 the GC. Even if only one thread is running during the pause, 85 this is computed as GOMAXPROCS times the pause latency because 86 nothing else can be executing. This is the exact sum of samples 87 in /sched/pauses/total/gc:seconds if each sample is multiplied 88 by GOMAXPROCS at the time it is taken. This metric is an 89 overestimate, and not directly comparable to system CPU time 90 measurements. Compare only with other /cpu/classes metrics. 91 92 /cpu/classes/gc/total:cpu-seconds 93 Estimated total CPU time spent performing GC tasks. This metric 94 is an overestimate, and not directly comparable to system CPU 95 time measurements. Compare only with other /cpu/classes metrics. 96 Sum of all metrics in /cpu/classes/gc. 97 98 /cpu/classes/idle:cpu-seconds 99 Estimated total available CPU time not spent executing 100 any Go or Go runtime code. In other words, the part of 101 /cpu/classes/total:cpu-seconds that was unused. This metric is 102 an overestimate, and not directly comparable to system CPU time 103 measurements. Compare only with other /cpu/classes 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 108 pressure. This metric is an overestimate, and not directly 109 comparable to system CPU time measurements. Compare only with 110 other /cpu/classes metrics. 111 112 /cpu/classes/scavenge/background:cpu-seconds 113 Estimated total CPU time spent performing background tasks to 114 return unused memory to the underlying platform. This metric is 115 an overestimate, and not directly comparable to system CPU time 116 measurements. Compare only with other /cpu/classes metrics. 117 118 /cpu/classes/scavenge/total:cpu-seconds 119 Estimated total CPU time spent performing tasks that return 120 unused memory to the underlying platform. This metric is an 121 overestimate, and not directly comparable to system CPU time 122 measurements. Compare only with other /cpu/classes metrics. 123 Sum of all metrics in /cpu/classes/scavenge. 124 125 /cpu/classes/total:cpu-seconds 126 Estimated total available CPU time for user Go code or the Go 127 runtime, as defined by GOMAXPROCS. In other words, GOMAXPROCS 128 integrated over the wall-clock duration this process has been 129 executing for. This metric is an overestimate, and not directly 130 comparable to system CPU time measurements. Compare only with 131 other /cpu/classes metrics. Sum of all metrics in /cpu/classes. 132 133 /cpu/classes/user:cpu-seconds 134 Estimated total CPU time spent running user Go code. This may 135 also include some small amount of time spent in the Go runtime. 136 This metric is an overestimate, and not directly comparable 137 to system CPU time measurements. Compare only with other 138 /cpu/classes metrics. 139 140 /gc/cycles/automatic:gc-cycles 141 Count of completed GC cycles generated by the Go runtime. 142 143 /gc/cycles/forced:gc-cycles 144 Count of completed GC cycles forced by the application. 145 146 /gc/cycles/total:gc-cycles 147 Count of all completed GC cycles. 148 149 /gc/gogc:percent 150 Heap size target percentage configured by the user, otherwise 151 100. This value is set by the GOGC environment variable, and the 152 runtime/debug.SetGCPercent function. 153 154 /gc/gomemlimit:bytes 155 Go runtime memory limit configured by the user, otherwise 156 math.MaxInt64. This value is set by the GOMEMLIMIT environment 157 variable, and the runtime/debug.SetMemoryLimit function. 158 159 /gc/heap/allocs-by-size:bytes 160 Distribution of heap allocations by approximate size. 161 Bucket counts increase monotonically. Note that this does not 162 include tiny objects as defined by /gc/heap/tiny/allocs:objects, 163 only tiny blocks. 164 165 /gc/heap/allocs:bytes 166 Cumulative sum of memory allocated to the heap by the 167 application. 168 169 /gc/heap/allocs:objects 170 Cumulative count of heap allocations triggered by the 171 application. Note that this does not include tiny objects as 172 defined by /gc/heap/tiny/allocs:objects, only tiny blocks. 173 174 /gc/heap/frees-by-size:bytes 175 Distribution of freed heap allocations by approximate size. 176 Bucket counts increase monotonically. Note that this does not 177 include tiny objects as defined by /gc/heap/tiny/allocs:objects, 178 only tiny blocks. 179 180 /gc/heap/frees:bytes 181 Cumulative sum of heap memory freed by the garbage collector. 182 183 /gc/heap/frees:objects 184 Cumulative count of heap allocations whose storage was freed 185 by the garbage collector. Note that this does not include tiny 186 objects as defined by /gc/heap/tiny/allocs:objects, only tiny 187 blocks. 188 189 /gc/heap/goal:bytes 190 Heap size target for the end of the GC cycle. 191 192 /gc/heap/live:bytes 193 Heap memory occupied by live objects that were marked by the 194 previous GC. 195 196 /gc/heap/objects:objects 197 Number of objects, live or unswept, occupying heap memory. 198 199 /gc/heap/tiny/allocs:objects 200 Count of small allocations that are packed together into blocks. 201 These allocations are counted separately from other allocations 202 because each individual allocation is not tracked by the 203 runtime, only their block. Each block is already accounted for 204 in allocs-by-size and frees-by-size. 205 206 /gc/limiter/last-enabled:gc-cycle 207 GC cycle the last time the GC CPU limiter was enabled. 208 This metric is useful for diagnosing the root cause of an 209 out-of-memory error, because the limiter trades memory for CPU 210 time when the GC's CPU time gets too high. This is most likely 211 to occur with use of SetMemoryLimit. The first GC cycle is cycle 212 1, so a value of 0 indicates that it was never enabled. 213 214 /gc/pauses:seconds 215 Deprecated. Prefer the identical /sched/pauses/total/gc:seconds. 216 217 /gc/scan/globals:bytes 218 The total amount of global variable space that is scannable. 219 220 /gc/scan/heap:bytes 221 The total amount of heap space that is scannable. 222 223 /gc/scan/stack:bytes 224 The number of bytes of stack that were scanned last GC cycle. 225 226 /gc/scan/total:bytes 227 The total amount space that is scannable. Sum of all metrics in 228 /gc/scan. 229 230 /gc/stack/starting-size:bytes 231 The stack size of new goroutines. 232 233 /godebug/non-default-behavior/allowmultiplevcs:events 234 The number of non-default behaviors executed by the cmd/go 235 package due to a non-default GODEBUG=allowmultiplevcs=... 236 setting. 237 238 /godebug/non-default-behavior/asynctimerchan:events 239 The number of non-default behaviors executed by the time package 240 due to a non-default GODEBUG=asynctimerchan=... setting. 241 242 /godebug/non-default-behavior/containermaxprocs:events 243 The number of non-default behaviors executed by the runtime 244 package due to a non-default GODEBUG=containermaxprocs=... 245 setting. 246 247 /godebug/non-default-behavior/embedfollowsymlinks:events 248 The number of non-default behaviors executed by the cmd/go 249 package due to a non-default GODEBUG=embedfollowsymlinks=... 250 setting. 251 252 /godebug/non-default-behavior/execerrdot:events 253 The number of non-default behaviors executed by the os/exec 254 package due to a non-default GODEBUG=execerrdot=... setting. 255 256 /godebug/non-default-behavior/gocachehash:events 257 The number of non-default behaviors executed by the cmd/go 258 package due to a non-default GODEBUG=gocachehash=... setting. 259 260 /godebug/non-default-behavior/gocachetest:events 261 The number of non-default behaviors executed by the cmd/go 262 package due to a non-default GODEBUG=gocachetest=... setting. 263 264 /godebug/non-default-behavior/gocacheverify:events 265 The number of non-default behaviors executed by the cmd/go 266 package due to a non-default GODEBUG=gocacheverify=... setting. 267 268 /godebug/non-default-behavior/gotestjsonbuildtext:events 269 The number of non-default behaviors executed by the cmd/go 270 package due to a non-default GODEBUG=gotestjsonbuildtext=... 271 setting. 272 273 /godebug/non-default-behavior/gotypesalias:events 274 The number of non-default behaviors executed by the go/types 275 package due to a non-default GODEBUG=gotypesalias=... setting. 276 277 /godebug/non-default-behavior/http2client:events 278 The number of non-default behaviors executed by the net/http 279 package due to a non-default GODEBUG=http2client=... setting. 280 281 /godebug/non-default-behavior/http2server:events 282 The number of non-default behaviors executed by the net/http 283 package due to a non-default GODEBUG=http2server=... setting. 284 285 /godebug/non-default-behavior/httpcookiemaxnum:events 286 The number of non-default behaviors executed by the net/http 287 package due to a non-default GODEBUG=httpcookiemaxnum=... 288 setting. 289 290 /godebug/non-default-behavior/httplaxcontentlength:events 291 The number of non-default behaviors executed by the net/http 292 package due to a non-default GODEBUG=httplaxcontentlength=... 293 setting. 294 295 /godebug/non-default-behavior/httpmuxgo121:events 296 The number of non-default behaviors executed by the net/http 297 package due to a non-default GODEBUG=httpmuxgo121=... setting. 298 299 /godebug/non-default-behavior/httpservecontentkeepheaders:events 300 The number of non-default behaviors executed 301 by the net/http package due to a non-default 302 GODEBUG=httpservecontentkeepheaders=... setting. 303 304 /godebug/non-default-behavior/installgoroot:events 305 The number of non-default behaviors executed by the go/build 306 package due to a non-default GODEBUG=installgoroot=... setting. 307 308 /godebug/non-default-behavior/multipartmaxheaders:events 309 The number of non-default behaviors executed by 310 the mime/multipart package due to a non-default 311 GODEBUG=multipartmaxheaders=... setting. 312 313 /godebug/non-default-behavior/multipartmaxparts:events 314 The number of non-default behaviors executed by 315 the mime/multipart package due to a non-default 316 GODEBUG=multipartmaxparts=... setting. 317 318 /godebug/non-default-behavior/multipathtcp:events 319 The number of non-default behaviors executed by the net package 320 due to a non-default GODEBUG=multipathtcp=... setting. 321 322 /godebug/non-default-behavior/netedns0:events 323 The number of non-default behaviors executed by the net package 324 due to a non-default GODEBUG=netedns0=... setting. 325 326 /godebug/non-default-behavior/panicnil:events 327 The number of non-default behaviors executed by the runtime 328 package due to a non-default GODEBUG=panicnil=... setting. 329 330 /godebug/non-default-behavior/randautoseed:events 331 The number of non-default behaviors executed by the math/rand 332 package due to a non-default GODEBUG=randautoseed=... setting. 333 334 /godebug/non-default-behavior/randseednop:events 335 The number of non-default behaviors executed by the math/rand 336 package due to a non-default GODEBUG=randseednop=... setting. 337 338 /godebug/non-default-behavior/rsa1024min:events 339 The number of non-default behaviors executed by the crypto/rsa 340 package due to a non-default GODEBUG=rsa1024min=... setting. 341 342 /godebug/non-default-behavior/tarinsecurepath:events 343 The number of non-default behaviors executed by the archive/tar 344 package due to a non-default GODEBUG=tarinsecurepath=... 345 setting. 346 347 /godebug/non-default-behavior/tls10server:events 348 The number of non-default behaviors executed by the crypto/tls 349 package due to a non-default GODEBUG=tls10server=... setting. 350 351 /godebug/non-default-behavior/tls3des:events 352 The number of non-default behaviors executed by the crypto/tls 353 package due to a non-default GODEBUG=tls3des=... setting. 354 355 /godebug/non-default-behavior/tlsmaxrsasize:events 356 The number of non-default behaviors executed by the crypto/tls 357 package due to a non-default GODEBUG=tlsmaxrsasize=... setting. 358 359 /godebug/non-default-behavior/tlsrsakex:events 360 The number of non-default behaviors executed by the crypto/tls 361 package due to a non-default GODEBUG=tlsrsakex=... setting. 362 363 /godebug/non-default-behavior/tlssha1:events 364 The number of non-default behaviors executed by the crypto/tls 365 package due to a non-default GODEBUG=tlssha1=... setting. 366 367 /godebug/non-default-behavior/tlsunsafeekm:events 368 The number of non-default behaviors executed by the crypto/tls 369 package due to a non-default GODEBUG=tlsunsafeekm=... setting. 370 371 /godebug/non-default-behavior/updatemaxprocs:events 372 The number of non-default behaviors executed by the runtime 373 package due to a non-default GODEBUG=updatemaxprocs=... setting. 374 375 /godebug/non-default-behavior/winreadlinkvolume:events 376 The number of non-default behaviors executed by the os package 377 due to a non-default GODEBUG=winreadlinkvolume=... setting. 378 379 /godebug/non-default-behavior/winsymlink:events 380 The number of non-default behaviors executed by the os package 381 due to a non-default GODEBUG=winsymlink=... setting. 382 383 /godebug/non-default-behavior/x509keypairleaf:events 384 The number of non-default behaviors executed by the crypto/tls 385 package due to a non-default GODEBUG=x509keypairleaf=... 386 setting. 387 388 /godebug/non-default-behavior/x509negativeserial:events 389 The number of non-default behaviors executed by the crypto/x509 390 package due to a non-default GODEBUG=x509negativeserial=... 391 setting. 392 393 /godebug/non-default-behavior/x509rsacrt:events 394 The number of non-default behaviors executed by the crypto/x509 395 package due to a non-default GODEBUG=x509rsacrt=... setting. 396 397 /godebug/non-default-behavior/x509sha256skid:events 398 The number of non-default behaviors executed by the crypto/x509 399 package due to a non-default GODEBUG=x509sha256skid=... setting. 400 401 /godebug/non-default-behavior/x509usefallbackroots:events 402 The number of non-default behaviors executed by the crypto/x509 403 package due to a non-default GODEBUG=x509usefallbackroots=... 404 setting. 405 406 /godebug/non-default-behavior/x509usepolicies:events 407 The number of non-default behaviors executed by the crypto/x509 408 package due to a non-default GODEBUG=x509usepolicies=... 409 setting. 410 411 /godebug/non-default-behavior/zipinsecurepath:events 412 The number of non-default behaviors executed by the archive/zip 413 package due to a non-default GODEBUG=zipinsecurepath=... 414 setting. 415 416 /memory/classes/heap/free:bytes 417 Memory that is completely free and eligible to be returned to 418 the underlying system, but has not been. This metric is the 419 runtime's estimate of free address space that is backed by 420 physical memory. 421 422 /memory/classes/heap/objects:bytes 423 Memory occupied by live objects and dead objects that have not 424 yet been marked free by the garbage collector. 425 426 /memory/classes/heap/released:bytes 427 Memory that is completely free and has been returned to the 428 underlying system. This metric is the runtime's estimate of free 429 address space that is still mapped into the process, but is not 430 backed by physical memory. 431 432 /memory/classes/heap/stacks:bytes 433 Memory allocated from the heap that is reserved for stack space, 434 whether or not it is currently in-use. Currently, this 435 represents all stack memory for goroutines. It also includes all 436 OS thread stacks in non-cgo programs. Note that stacks may be 437 allocated differently in the future, and this may change. 438 439 /memory/classes/heap/unused:bytes 440 Memory that is reserved for heap objects but is not currently 441 used to hold heap objects. 442 443 /memory/classes/metadata/mcache/free:bytes 444 Memory that is reserved for runtime mcache structures, but not 445 in-use. 446 447 /memory/classes/metadata/mcache/inuse:bytes 448 Memory that is occupied by runtime mcache structures that are 449 currently being used. 450 451 /memory/classes/metadata/mspan/free:bytes 452 Memory that is reserved for runtime mspan structures, but not 453 in-use. 454 455 /memory/classes/metadata/mspan/inuse:bytes 456 Memory that is occupied by runtime mspan structures that are 457 currently being used. 458 459 /memory/classes/metadata/other:bytes 460 Memory that is reserved for or used to hold runtime metadata. 461 462 /memory/classes/os-stacks:bytes 463 Stack memory allocated by the underlying operating system. 464 In non-cgo programs this metric is currently zero. This may 465 change in the future.In cgo programs this metric includes 466 OS thread stacks allocated directly from the OS. Currently, 467 this only accounts for one stack in c-shared and c-archive build 468 modes, and other sources of stacks from the OS are not measured. 469 This too may change in the future. 470 471 /memory/classes/other:bytes 472 Memory used by execution trace buffers, structures for debugging 473 the runtime, finalizer and profiler specials, and more. 474 475 /memory/classes/profiling/buckets:bytes 476 Memory that is used by the stack trace hash map used for 477 profiling. 478 479 /memory/classes/total:bytes 480 All memory mapped by the Go runtime into the current process 481 as read-write. Note that this does not include memory mapped 482 by code called via cgo or via the syscall package. Sum of all 483 metrics in /memory/classes. 484 485 /sched/gomaxprocs:threads 486 The current runtime.GOMAXPROCS setting, or the number of 487 operating system threads that can execute user-level Go code 488 simultaneously. 489 490 /sched/goroutines:goroutines 491 Count of live goroutines. 492 493 /sched/latencies:seconds 494 Distribution of the time goroutines have spent in the scheduler 495 in a runnable state before actually running. Bucket counts 496 increase monotonically. 497 498 /sched/pauses/stopping/gc:seconds 499 Distribution of individual GC-related stop-the-world stopping 500 latencies. This is the time it takes from deciding to stop the 501 world until all Ps are stopped. This is a subset of the total 502 GC-related stop-the-world time (/sched/pauses/total/gc:seconds). 503 During this time, some threads may be executing. Bucket counts 504 increase monotonically. 505 506 /sched/pauses/stopping/other:seconds 507 Distribution of individual non-GC-related stop-the-world 508 stopping latencies. This is the time it takes from deciding 509 to stop the world until all Ps are stopped. This is a 510 subset of the total non-GC-related stop-the-world time 511 (/sched/pauses/total/other:seconds). During this time, some 512 threads may be executing. Bucket counts increase monotonically. 513 514 /sched/pauses/total/gc:seconds 515 Distribution of individual GC-related stop-the-world pause 516 latencies. This is the time from deciding to stop the world 517 until the world is started again. Some of this time is spent 518 getting all threads to stop (this is measured directly in 519 /sched/pauses/stopping/gc:seconds), during which some threads 520 may still be running. Bucket counts increase monotonically. 521 522 /sched/pauses/total/other:seconds 523 Distribution of individual non-GC-related stop-the-world 524 pause latencies. This is the time from deciding to stop the 525 world until the world is started again. Some of this time 526 is spent getting all threads to stop (measured directly in 527 /sched/pauses/stopping/other:seconds). Bucket counts increase 528 monotonically. 529 530 /sync/mutex/wait/total:seconds 531 Approximate cumulative time goroutines have spent blocked on a 532 sync.Mutex, sync.RWMutex, or runtime-internal lock. This metric 533 is useful for identifying global changes in lock contention. 534 Collect a mutex or block profile using the runtime/pprof package 535 for more detailed contention data. 536 */ 537 package metrics 538