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:        "/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