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  }