description.go

Documentation: runtime/metrics

		 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:				"/gc/cycles/automatic:gc-cycles",
		56  		Description: "Count of completed GC cycles generated by the Go runtime.",
		57  		Kind:				KindUint64,
		58  		Cumulative:	true,
		59  	},
		60  	{
		61  		Name:				"/gc/cycles/forced:gc-cycles",
		62  		Description: "Count of completed GC cycles forced by the application.",
		63  		Kind:				KindUint64,
		64  		Cumulative:	true,
		65  	},
		66  	{
		67  		Name:				"/gc/cycles/total:gc-cycles",
		68  		Description: "Count of all completed GC cycles.",
		69  		Kind:				KindUint64,
		70  		Cumulative:	true,
		71  	},
		72  	{
		73  		Name: "/gc/heap/allocs-by-size:bytes",
		74  		Description: "Distribution of heap allocations by approximate size. " +
		75  			"Note that this does not include tiny objects as defined by " +
		76  			"/gc/heap/tiny/allocs:objects, only tiny blocks.",
		77  		Kind:			 KindFloat64Histogram,
		78  		Cumulative: true,
		79  	},
		80  	{
		81  		Name:				"/gc/heap/allocs:bytes",
		82  		Description: "Cumulative sum of memory allocated to the heap by the application.",
		83  		Kind:				KindUint64,
		84  		Cumulative:	true,
		85  	},
		86  	{
		87  		Name: "/gc/heap/allocs:objects",
		88  		Description: "Cumulative count of heap allocations triggered by the application. " +
		89  			"Note that this does not include tiny objects as defined by " +
		90  			"/gc/heap/tiny/allocs:objects, only tiny blocks.",
		91  		Kind:			 KindUint64,
		92  		Cumulative: true,
		93  	},
		94  	{
		95  		Name: "/gc/heap/frees-by-size:bytes",
		96  		Description: "Distribution of freed heap allocations by approximate size. " +
		97  			"Note that this does not include tiny objects as defined by " +
		98  			"/gc/heap/tiny/allocs:objects, only tiny blocks.",
		99  		Kind:			 KindFloat64Histogram,
	 100  		Cumulative: true,
	 101  	},
	 102  	{
	 103  		Name:				"/gc/heap/frees:bytes",
	 104  		Description: "Cumulative sum of heap memory freed by the garbage collector.",
	 105  		Kind:				KindUint64,
	 106  		Cumulative:	true,
	 107  	},
	 108  	{
	 109  		Name: "/gc/heap/frees:objects",
	 110  		Description: "Cumulative count of heap allocations whose storage was freed " +
	 111  			"by the garbage collector. " +
	 112  			"Note that this does not include tiny objects as defined by " +
	 113  			"/gc/heap/tiny/allocs:objects, only tiny blocks.",
	 114  		Kind:			 KindUint64,
	 115  		Cumulative: true,
	 116  	},
	 117  	{
	 118  		Name:				"/gc/heap/goal:bytes",
	 119  		Description: "Heap size target for the end of the GC cycle.",
	 120  		Kind:				KindUint64,
	 121  	},
	 122  	{
	 123  		Name:				"/gc/heap/objects:objects",
	 124  		Description: "Number of objects, live or unswept, occupying heap memory.",
	 125  		Kind:				KindUint64,
	 126  	},
	 127  	{
	 128  		Name: "/gc/heap/tiny/allocs:objects",
	 129  		Description: "Count of small allocations that are packed together into blocks. " +
	 130  			"These allocations are counted separately from other allocations " +
	 131  			"because each individual allocation is not tracked by the runtime, " +
	 132  			"only their block. Each block is already accounted for in " +
	 133  			"allocs-by-size and frees-by-size.",
	 134  		Kind:			 KindUint64,
	 135  		Cumulative: true,
	 136  	},
	 137  	{
	 138  		Name:				"/gc/pauses:seconds",
	 139  		Description: "Distribution individual GC-related stop-the-world pause latencies.",
	 140  		Kind:				KindFloat64Histogram,
	 141  		Cumulative:	true,
	 142  	},
	 143  	{
	 144  		Name: "/memory/classes/heap/free:bytes",
	 145  		Description: "Memory that is completely free and eligible to be returned to the underlying system, " +
	 146  			"but has not been. This metric is the runtime's estimate of free address space that is backed by " +
	 147  			"physical memory.",
	 148  		Kind: KindUint64,
	 149  	},
	 150  	{
	 151  		Name:				"/memory/classes/heap/objects:bytes",
	 152  		Description: "Memory occupied by live objects and dead objects that have not yet been marked free by the garbage collector.",
	 153  		Kind:				KindUint64,
	 154  	},
	 155  	{
	 156  		Name: "/memory/classes/heap/released:bytes",
	 157  		Description: "Memory that is completely free and has been returned to the underlying system. This " +
	 158  			"metric is the runtime's estimate of free address space that is still mapped into the process, " +
	 159  			"but is not backed by physical memory.",
	 160  		Kind: KindUint64,
	 161  	},
	 162  	{
	 163  		Name:				"/memory/classes/heap/stacks:bytes",
	 164  		Description: "Memory allocated from the heap that is reserved for stack space, whether or not it is currently in-use.",
	 165  		Kind:				KindUint64,
	 166  	},
	 167  	{
	 168  		Name:				"/memory/classes/heap/unused:bytes",
	 169  		Description: "Memory that is reserved for heap objects but is not currently used to hold heap objects.",
	 170  		Kind:				KindUint64,
	 171  	},
	 172  	{
	 173  		Name:				"/memory/classes/metadata/mcache/free:bytes",
	 174  		Description: "Memory that is reserved for runtime mcache structures, but not in-use.",
	 175  		Kind:				KindUint64,
	 176  	},
	 177  	{
	 178  		Name:				"/memory/classes/metadata/mcache/inuse:bytes",
	 179  		Description: "Memory that is occupied by runtime mcache structures that are currently being used.",
	 180  		Kind:				KindUint64,
	 181  	},
	 182  	{
	 183  		Name:				"/memory/classes/metadata/mspan/free:bytes",
	 184  		Description: "Memory that is reserved for runtime mspan structures, but not in-use.",
	 185  		Kind:				KindUint64,
	 186  	},
	 187  	{
	 188  		Name:				"/memory/classes/metadata/mspan/inuse:bytes",
	 189  		Description: "Memory that is occupied by runtime mspan structures that are currently being used.",
	 190  		Kind:				KindUint64,
	 191  	},
	 192  	{
	 193  		Name:				"/memory/classes/metadata/other:bytes",
	 194  		Description: "Memory that is reserved for or used to hold runtime metadata.",
	 195  		Kind:				KindUint64,
	 196  	},
	 197  	{
	 198  		Name:				"/memory/classes/os-stacks:bytes",
	 199  		Description: "Stack memory allocated by the underlying operating system.",
	 200  		Kind:				KindUint64,
	 201  	},
	 202  	{
	 203  		Name:				"/memory/classes/other:bytes",
	 204  		Description: "Memory used by execution trace buffers, structures for debugging the runtime, finalizer and profiler specials, and more.",
	 205  		Kind:				KindUint64,
	 206  	},
	 207  	{
	 208  		Name:				"/memory/classes/profiling/buckets:bytes",
	 209  		Description: "Memory that is used by the stack trace hash map used for profiling.",
	 210  		Kind:				KindUint64,
	 211  	},
	 212  	{
	 213  		Name:				"/memory/classes/total:bytes",
	 214  		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.",
	 215  		Kind:				KindUint64,
	 216  	},
	 217  	{
	 218  		Name:				"/sched/goroutines:goroutines",
	 219  		Description: "Count of live goroutines.",
	 220  		Kind:				KindUint64,
	 221  	},
	 222  	{
	 223  		Name:				"/sched/latencies:seconds",
	 224  		Description: "Distribution of the time goroutines have spent in the scheduler in a runnable state before actually running.",
	 225  		Kind:				KindFloat64Histogram,
	 226  	},
	 227  }
	 228  
	 229  // All returns a slice of containing metric descriptions for all supported metrics.
	 230  func All() []Description {
	 231  	return allDesc
	 232  }
	 233
View as plain text