github.com/dorkamotorka/go/src@v0.0.0-20230614113921-187095f0e316/runtime/metrics/description.go (about) 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 package metrics 6 7 import "internal/godebugs" 8 9 // Description describes a runtime metric. 10 type Description struct { 11 // Name is the full name of the metric which includes the unit. 12 // 13 // The format of the metric may be described by the following regular expression. 14 // 15 // ^(?P<name>/[^:]+):(?P<unit>[^:*/]+(?:[*/][^:*/]+)*)$ 16 // 17 // The format splits the name into two components, separated by a colon: a path which always 18 // starts with a /, and a machine-parseable unit. The name may contain any valid Unicode 19 // codepoint in between / characters, but by convention will try to stick to lowercase 20 // characters and hyphens. An example of such a path might be "/memory/heap/free". 21 // 22 // The unit is by convention a series of lowercase English unit names (singular or plural) 23 // without prefixes delimited by '*' or '/'. The unit names may contain any valid Unicode 24 // codepoint that is not a delimiter. 25 // Examples of units might be "seconds", "bytes", "bytes/second", "cpu-seconds", 26 // "byte*cpu-seconds", and "bytes/second/second". 27 // 28 // For histograms, multiple units may apply. For instance, the units of the buckets and 29 // the count. By convention, for histograms, the units of the count are always "samples" 30 // with the type of sample evident by the metric's name, while the unit in the name 31 // specifies the buckets' unit. 32 // 33 // A complete name might look like "/memory/heap/free:bytes". 34 Name string 35 36 // Description is an English language sentence describing the metric. 37 Description string 38 39 // Kind is the kind of value for this metric. 40 // 41 // The purpose of this field is to allow users to filter out metrics whose values are 42 // types which their application may not understand. 43 Kind ValueKind 44 45 // Cumulative is whether or not the metric is cumulative. If a cumulative metric is just 46 // a single number, then it increases monotonically. If the metric is a distribution, 47 // then each bucket count increases monotonically. 48 // 49 // This flag thus indicates whether or not it's useful to compute a rate from this value. 50 Cumulative bool 51 } 52 53 // The English language descriptions below must be kept in sync with the 54 // descriptions of each metric in doc.go by running 'go generate'. 55 var allDesc = []Description{ 56 { 57 Name: "/cgo/go-to-c-calls:calls", 58 Description: "Count of calls made from Go to C by the current process.", 59 Kind: KindUint64, 60 Cumulative: true, 61 }, 62 { 63 Name: "/cpu/classes/gc/mark/assist:cpu-seconds", 64 Description: "Estimated total CPU time goroutines spent performing GC tasks " + 65 "to assist the GC and prevent it from falling behind the application. " + 66 "This metric is an overestimate, and not directly comparable to " + 67 "system CPU time measurements. Compare only with other /cpu/classes " + 68 "metrics.", 69 Kind: KindFloat64, 70 Cumulative: true, 71 }, 72 { 73 Name: "/cpu/classes/gc/mark/dedicated:cpu-seconds", 74 Description: "Estimated total CPU time spent performing GC tasks on " + 75 "processors (as defined by GOMAXPROCS) dedicated to those tasks. " + 76 "This metric is an overestimate, and not directly comparable to " + 77 "system CPU time measurements. Compare only with other /cpu/classes " + 78 "metrics.", 79 Kind: KindFloat64, 80 Cumulative: true, 81 }, 82 { 83 Name: "/cpu/classes/gc/mark/idle:cpu-seconds", 84 Description: "Estimated total CPU time spent performing GC tasks on " + 85 "spare CPU resources that the Go scheduler could not otherwise find " + 86 "a use for. This should be subtracted from the total GC CPU time to " + 87 "obtain a measure of compulsory GC CPU time. " + 88 "This metric is an overestimate, and not directly comparable to " + 89 "system CPU time measurements. Compare only with other /cpu/classes " + 90 "metrics.", 91 Kind: KindFloat64, 92 Cumulative: true, 93 }, 94 { 95 Name: "/cpu/classes/gc/pause:cpu-seconds", 96 Description: "Estimated total CPU time spent with the application paused by " + 97 "the GC. Even if only one thread is running during the pause, this is " + 98 "computed as GOMAXPROCS times the pause latency because nothing else " + 99 "can be executing. This is the exact sum of samples in /gc/pause:seconds " + 100 "if each sample is multiplied by GOMAXPROCS at the time it is taken. " + 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 Kind: KindFloat64, 105 Cumulative: true, 106 }, 107 { 108 Name: "/cpu/classes/gc/total:cpu-seconds", 109 Description: "Estimated total CPU time spent performing GC tasks. " + 110 "This metric is an overestimate, and not directly comparable to " + 111 "system CPU time measurements. Compare only with other /cpu/classes " + 112 "metrics. Sum of all metrics in /cpu/classes/gc.", 113 Kind: KindFloat64, 114 Cumulative: true, 115 }, 116 { 117 Name: "/cpu/classes/idle:cpu-seconds", 118 Description: "Estimated total available CPU time not spent executing any Go or Go runtime code. " + 119 "In other words, the part of /cpu/classes/total:cpu-seconds that was unused. " + 120 "This metric is an overestimate, and not directly comparable to " + 121 "system CPU time measurements. Compare only with other /cpu/classes " + 122 "metrics.", 123 Kind: KindFloat64, 124 Cumulative: true, 125 }, 126 { 127 Name: "/cpu/classes/scavenge/assist:cpu-seconds", 128 Description: "Estimated total CPU time spent returning unused memory to the " + 129 "underlying platform in response eagerly in response to memory pressure. " + 130 "This metric is an overestimate, and not directly comparable to " + 131 "system CPU time measurements. Compare only with other /cpu/classes " + 132 "metrics.", 133 Kind: KindFloat64, 134 Cumulative: true, 135 }, 136 { 137 Name: "/cpu/classes/scavenge/background:cpu-seconds", 138 Description: "Estimated total CPU time spent performing background tasks " + 139 "to return unused memory to the underlying platform. " + 140 "This metric is an overestimate, and not directly comparable to " + 141 "system CPU time measurements. Compare only with other /cpu/classes " + 142 "metrics.", 143 Kind: KindFloat64, 144 Cumulative: true, 145 }, 146 { 147 Name: "/cpu/classes/scavenge/total:cpu-seconds", 148 Description: "Estimated total CPU time spent performing tasks that return " + 149 "unused memory to the underlying platform. " + 150 "This metric is an overestimate, and not directly comparable to " + 151 "system CPU time measurements. Compare only with other /cpu/classes " + 152 "metrics. Sum of all metrics in /cpu/classes/scavenge.", 153 Kind: KindFloat64, 154 Cumulative: true, 155 }, 156 { 157 Name: "/cpu/classes/total:cpu-seconds", 158 Description: "Estimated total available CPU time for user Go code " + 159 "or the Go runtime, as defined by GOMAXPROCS. In other words, GOMAXPROCS " + 160 "integrated over the wall-clock duration this process has been executing for. " + 161 "This metric is an overestimate, and not directly comparable to " + 162 "system CPU time measurements. Compare only with other /cpu/classes " + 163 "metrics. Sum of all metrics in /cpu/classes.", 164 Kind: KindFloat64, 165 Cumulative: true, 166 }, 167 { 168 Name: "/cpu/classes/user:cpu-seconds", 169 Description: "Estimated total CPU time spent running user Go code. This may " + 170 "also include some small amount of time spent in the Go runtime. " + 171 "This metric is an overestimate, and not directly comparable to " + 172 "system CPU time measurements. Compare only with other /cpu/classes " + 173 "metrics.", 174 Kind: KindFloat64, 175 Cumulative: true, 176 }, 177 { 178 Name: "/gc/cycles/automatic:gc-cycles", 179 Description: "Count of completed GC cycles generated by the Go runtime.", 180 Kind: KindUint64, 181 Cumulative: true, 182 }, 183 { 184 Name: "/gc/cycles/forced:gc-cycles", 185 Description: "Count of completed GC cycles forced by the application.", 186 Kind: KindUint64, 187 Cumulative: true, 188 }, 189 { 190 Name: "/gc/cycles/total:gc-cycles", 191 Description: "Count of all completed GC cycles.", 192 Kind: KindUint64, 193 Cumulative: true, 194 }, 195 { 196 Name: "/gc/gogc:percent", 197 Description: "Heap size target percentage configured by the user, otherwise 100. This " + 198 "value is set by the GOGC environment variable, and the runtime/debug.SetGCPercent " + 199 "function.", 200 Kind: KindUint64, 201 }, 202 { 203 Name: "/gc/gomemlimit:bytes", 204 Description: "Go runtime memory limit configured by the user, otherwise " + 205 "math.MaxInt64. This value is set by the GOMEMLIMIT environment variable, and " + 206 "the runtime/debug.SetMemoryLimit function.", 207 Kind: KindUint64, 208 }, 209 { 210 Name: "/gc/heap/allocs-by-size:bytes", 211 Description: "Distribution of heap allocations by approximate size. " + 212 "Bucket counts increase monotonically. " + 213 "Note that this does not include tiny objects as defined by " + 214 "/gc/heap/tiny/allocs:objects, only tiny blocks.", 215 Kind: KindFloat64Histogram, 216 Cumulative: true, 217 }, 218 { 219 Name: "/gc/heap/allocs:bytes", 220 Description: "Cumulative sum of memory allocated to the heap by the application.", 221 Kind: KindUint64, 222 Cumulative: true, 223 }, 224 { 225 Name: "/gc/heap/allocs:objects", 226 Description: "Cumulative count of heap allocations triggered by the application. " + 227 "Note that this does not include tiny objects as defined by " + 228 "/gc/heap/tiny/allocs:objects, only tiny blocks.", 229 Kind: KindUint64, 230 Cumulative: true, 231 }, 232 { 233 Name: "/gc/heap/frees-by-size:bytes", 234 Description: "Distribution of freed heap allocations by approximate size. " + 235 "Bucket counts increase monotonically. " + 236 "Note that this does not include tiny objects as defined by " + 237 "/gc/heap/tiny/allocs:objects, only tiny blocks.", 238 Kind: KindFloat64Histogram, 239 Cumulative: true, 240 }, 241 { 242 Name: "/gc/heap/frees:bytes", 243 Description: "Cumulative sum of heap memory freed by the garbage collector.", 244 Kind: KindUint64, 245 Cumulative: true, 246 }, 247 { 248 Name: "/gc/heap/frees:objects", 249 Description: "Cumulative count of heap allocations whose storage was freed " + 250 "by the garbage collector. " + 251 "Note that this does not include tiny objects as defined by " + 252 "/gc/heap/tiny/allocs:objects, only tiny blocks.", 253 Kind: KindUint64, 254 Cumulative: true, 255 }, 256 { 257 Name: "/gc/heap/goal:bytes", 258 Description: "Heap size target for the end of the GC cycle.", 259 Kind: KindUint64, 260 }, 261 { 262 Name: "/gc/heap/live:bytes", 263 Description: "Heap memory occupied by live objects that were marked by the previous GC.", 264 Kind: KindUint64, 265 }, 266 { 267 Name: "/gc/heap/objects:objects", 268 Description: "Number of objects, live or unswept, occupying heap memory.", 269 Kind: KindUint64, 270 }, 271 { 272 Name: "/gc/heap/tiny/allocs:objects", 273 Description: "Count of small allocations that are packed together into blocks. " + 274 "These allocations are counted separately from other allocations " + 275 "because each individual allocation is not tracked by the runtime, " + 276 "only their block. Each block is already accounted for in " + 277 "allocs-by-size and frees-by-size.", 278 Kind: KindUint64, 279 Cumulative: true, 280 }, 281 { 282 Name: "/gc/limiter/last-enabled:gc-cycle", 283 Description: "GC cycle the last time the GC CPU limiter was enabled. " + 284 "This metric is useful for diagnosing the root cause of an out-of-memory " + 285 "error, because the limiter trades memory for CPU time when the GC's CPU " + 286 "time gets too high. This is most likely to occur with use of SetMemoryLimit. " + 287 "The first GC cycle is cycle 1, so a value of 0 indicates that it was never enabled.", 288 Kind: KindUint64, 289 }, 290 { 291 Name: "/gc/pauses:seconds", 292 Description: "Distribution of individual GC-related stop-the-world pause latencies. Bucket counts increase monotonically.", 293 Kind: KindFloat64Histogram, 294 Cumulative: true, 295 }, 296 { 297 Name: "/gc/scan/globals:bytes", 298 Description: "The total amount of global variable space that is scannable.", 299 Kind: KindUint64, 300 }, 301 { 302 Name: "/gc/scan/heap:bytes", 303 Description: "The total amount of heap space that is scannable.", 304 Kind: KindUint64, 305 }, 306 { 307 Name: "/gc/scan/stack:bytes", 308 Description: "The number of bytes of stack that were scanned last GC cycle.", 309 Kind: KindUint64, 310 }, 311 { 312 Name: "/gc/scan/total:bytes", 313 Description: "The total amount space that is scannable. Sum of all metrics in /gc/scan.", 314 Kind: KindUint64, 315 }, 316 { 317 Name: "/gc/stack/starting-size:bytes", 318 Description: "The stack size of new goroutines.", 319 Kind: KindUint64, 320 Cumulative: false, 321 }, 322 { 323 Name: "/memory/classes/heap/free:bytes", 324 Description: "Memory that is completely free and eligible to be returned to the underlying system, " + 325 "but has not been. This metric is the runtime's estimate of free address space that is backed by " + 326 "physical memory.", 327 Kind: KindUint64, 328 }, 329 { 330 Name: "/memory/classes/heap/objects:bytes", 331 Description: "Memory occupied by live objects and dead objects that have not yet been marked free by the garbage collector.", 332 Kind: KindUint64, 333 }, 334 { 335 Name: "/memory/classes/heap/released:bytes", 336 Description: "Memory that is completely free and has been returned to the underlying system. This " + 337 "metric is the runtime's estimate of free address space that is still mapped into the process, " + 338 "but is not backed by physical memory.", 339 Kind: KindUint64, 340 }, 341 { 342 Name: "/memory/classes/heap/stacks:bytes", 343 Description: "Memory allocated from the heap that is reserved for stack space, whether or not it is currently in-use.", 344 Kind: KindUint64, 345 }, 346 { 347 Name: "/memory/classes/heap/unused:bytes", 348 Description: "Memory that is reserved for heap objects but is not currently used to hold heap objects.", 349 Kind: KindUint64, 350 }, 351 { 352 Name: "/memory/classes/metadata/mcache/free:bytes", 353 Description: "Memory that is reserved for runtime mcache structures, but not in-use.", 354 Kind: KindUint64, 355 }, 356 { 357 Name: "/memory/classes/metadata/mcache/inuse:bytes", 358 Description: "Memory that is occupied by runtime mcache structures that are currently being used.", 359 Kind: KindUint64, 360 }, 361 { 362 Name: "/memory/classes/metadata/mspan/free:bytes", 363 Description: "Memory that is reserved for runtime mspan structures, but not in-use.", 364 Kind: KindUint64, 365 }, 366 { 367 Name: "/memory/classes/metadata/mspan/inuse:bytes", 368 Description: "Memory that is occupied by runtime mspan structures that are currently being used.", 369 Kind: KindUint64, 370 }, 371 { 372 Name: "/memory/classes/metadata/other:bytes", 373 Description: "Memory that is reserved for or used to hold runtime metadata.", 374 Kind: KindUint64, 375 }, 376 { 377 Name: "/memory/classes/os-stacks:bytes", 378 Description: "Stack memory allocated by the underlying operating system.", 379 Kind: KindUint64, 380 }, 381 { 382 Name: "/memory/classes/other:bytes", 383 Description: "Memory used by execution trace buffers, structures for debugging the runtime, finalizer and profiler specials, and more.", 384 Kind: KindUint64, 385 }, 386 { 387 Name: "/memory/classes/profiling/buckets:bytes", 388 Description: "Memory that is used by the stack trace hash map used for profiling.", 389 Kind: KindUint64, 390 }, 391 { 392 Name: "/memory/classes/total:bytes", 393 Description: "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.", 394 Kind: KindUint64, 395 }, 396 { 397 Name: "/sched/gomaxprocs:threads", 398 Description: "The current runtime.GOMAXPROCS setting, or the number of operating system threads that can execute user-level Go code simultaneously.", 399 Kind: KindUint64, 400 }, 401 { 402 Name: "/sched/goroutines:goroutines", 403 Description: "Count of live goroutines.", 404 Kind: KindUint64, 405 }, 406 { 407 Name: "/sched/latencies:seconds", 408 Description: "Distribution of the time goroutines have spent in the scheduler in a runnable state before actually running. Bucket counts increase monotonically.", 409 Kind: KindFloat64Histogram, 410 Cumulative: true, 411 }, 412 { 413 Name: "/sync/mutex/wait/total:seconds", 414 Description: "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.", 415 Kind: KindFloat64, 416 Cumulative: true, 417 }, 418 } 419 420 func init() { 421 // Insert all the non-default-reporting GODEBUGs into the table, 422 // preserving the overall sort order. 423 i := 0 424 for i < len(allDesc) && allDesc[i].Name < "/godebug/" { 425 i++ 426 } 427 more := make([]Description, i, len(allDesc)+len(godebugs.All)) 428 copy(more, allDesc) 429 for _, info := range godebugs.All { 430 if !info.Opaque { 431 more = append(more, Description{ 432 Name: "/godebug/non-default-behavior/" + info.Name + ":events", 433 Description: "The number of non-default behaviors executed by the " + 434 info.Package + " package " + "due to a non-default " + 435 "GODEBUG=" + info.Name + "=... setting.", 436 Kind: KindUint64, 437 Cumulative: true, 438 }) 439 } 440 } 441 allDesc = append(more, allDesc[i:]...) 442 } 443 444 // All returns a slice of containing metric descriptions for all supported metrics. 445 func All() []Description { 446 return allDesc 447 }