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