Source file src/runtime/metrics/doc.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  // Note: run 'go generate' (which will run 'go test -generate') to update the "Supported metrics" list.
     6  //go:generate go test -run=Docs -generate
     7  
     8  /*
     9  Package metrics provides a stable interface to access implementation-defined
    10  metrics exported by the Go runtime. This package is similar to existing functions
    11  like [runtime.ReadMemStats] and [runtime/debug.ReadGCStats], but significantly more general.
    12  
    13  The set of metrics defined by this package may evolve as the runtime itself
    14  evolves, and also enables variation across Go implementations, whose relevant
    15  metric sets may not intersect.
    16  
    17  # Interface
    18  
    19  Metrics are designated by a string key, rather than, for example, a field name in
    20  a struct. The full list of supported metrics is always available in the slice of
    21  Descriptions returned by [All]. Each [Description] also includes useful information
    22  about the metric.
    23  
    24  Thus, users of this API are encouraged to sample supported metrics defined by the
    25  slice returned by All to remain compatible across Go versions. Of course, situations
    26  arise where reading specific metrics is critical. For these cases, users are
    27  encouraged to use build tags, and although metrics may be deprecated and removed,
    28  users should consider this to be an exceptional and rare event, coinciding with a
    29  very large change in a particular Go implementation.
    30  
    31  Each metric key also has a "kind" (see [ValueKind]) that describes the format of the
    32  metric's value.
    33  In the interest of not breaking users of this package, the "kind" for a given metric
    34  is guaranteed not to change. If it must change, then a new metric will be introduced
    35  with a new key and a new "kind."
    36  
    37  # Metric key format
    38  
    39  As mentioned earlier, metric keys are strings. Their format is simple and well-defined,
    40  designed to be both human and machine readable. It is split into two components,
    41  separated by a colon: a rooted path and a unit. The choice to include the unit in
    42  the key is motivated by compatibility: if a metric's unit changes, its semantics likely
    43  did also, and a new key should be introduced.
    44  
    45  For more details on the precise definition of the metric key's path and unit formats, see
    46  the documentation of the Name field of the Description struct.
    47  
    48  # A note about floats
    49  
    50  This package supports metrics whose values have a floating-point representation. In
    51  order to improve ease-of-use, this package promises to never produce the following
    52  classes of floating-point values: NaN, infinity.
    53  
    54  # Supported metrics
    55  
    56  Below is the full list of supported metrics, ordered lexicographically.
    57  
    58  	/cgo/go-to-c-calls:calls
    59  		Count of calls made from Go to C by the current process.
    60  
    61  	/cpu/classes/gc/mark/assist:cpu-seconds
    62  		Estimated total CPU time goroutines spent performing GC
    63  		tasks to assist the GC and prevent it from falling behind the
    64  		application. This metric is an overestimate, and not directly
    65  		comparable to system CPU time measurements. Compare only with
    66  		other /cpu/classes metrics.
    67  
    68  	/cpu/classes/gc/mark/dedicated:cpu-seconds
    69  		Estimated total CPU time spent performing GC tasks on processors
    70  		(as defined by GOMAXPROCS) dedicated to those tasks. This metric
    71  		is an overestimate, and not directly comparable to system CPU
    72  		time measurements. Compare only with other /cpu/classes metrics.
    73  
    74  	/cpu/classes/gc/mark/idle:cpu-seconds
    75  		Estimated total CPU time spent performing GC tasks on spare CPU
    76  		resources that the Go scheduler could not otherwise find a use
    77  		for. This should be subtracted from the total GC CPU time to
    78  		obtain a measure of compulsory GC CPU time. This metric is an
    79  		overestimate, and not directly comparable to system CPU time
    80  		measurements. Compare only with other /cpu/classes metrics.
    81  
    82  	/cpu/classes/gc/pause:cpu-seconds
    83  		Estimated total CPU time spent with the application paused by
    84  		the GC. Even if only one thread is running during the pause,
    85  		this is computed as GOMAXPROCS times the pause latency because
    86  		nothing else can be executing. This is the exact sum of samples
    87  		in /sched/pauses/total/gc:seconds if each sample is multiplied
    88  		by GOMAXPROCS at the time it is taken. This metric is an
    89  		overestimate, and not directly comparable to system CPU time
    90  		measurements. Compare only with other /cpu/classes metrics.
    91  
    92  	/cpu/classes/gc/total:cpu-seconds
    93  		Estimated total CPU time spent performing GC tasks. This metric
    94  		is an overestimate, and not directly comparable to system CPU
    95  		time measurements. Compare only with other /cpu/classes metrics.
    96  		Sum of all metrics in /cpu/classes/gc.
    97  
    98  	/cpu/classes/idle:cpu-seconds
    99  		Estimated total available CPU time not spent executing
   100  		any Go or Go runtime code. In other words, the part of
   101  		/cpu/classes/total:cpu-seconds that was unused. This metric is
   102  		an overestimate, and not directly comparable to system CPU time
   103  		measurements. Compare only with other /cpu/classes metrics.
   104  
   105  	/cpu/classes/scavenge/assist:cpu-seconds
   106  		Estimated total CPU time spent returning unused memory to the
   107  		underlying platform in response eagerly in response to memory
   108  		pressure. This metric is an overestimate, and not directly
   109  		comparable to system CPU time measurements. Compare only with
   110  		other /cpu/classes metrics.
   111  
   112  	/cpu/classes/scavenge/background:cpu-seconds
   113  		Estimated total CPU time spent performing background tasks to
   114  		return unused memory to the underlying platform. This metric is
   115  		an overestimate, and not directly comparable to system CPU time
   116  		measurements. Compare only with other /cpu/classes metrics.
   117  
   118  	/cpu/classes/scavenge/total:cpu-seconds
   119  		Estimated total CPU time spent performing tasks that return
   120  		unused memory to the underlying platform. This metric is an
   121  		overestimate, and not directly comparable to system CPU time
   122  		measurements. Compare only with other /cpu/classes metrics.
   123  		Sum of all metrics in /cpu/classes/scavenge.
   124  
   125  	/cpu/classes/total:cpu-seconds
   126  		Estimated total available CPU time for user Go code or the Go
   127  		runtime, as defined by GOMAXPROCS. In other words, GOMAXPROCS
   128  		integrated over the wall-clock duration this process has been
   129  		executing for. This metric is an overestimate, and not directly
   130  		comparable to system CPU time measurements. Compare only with
   131  		other /cpu/classes metrics. Sum of all metrics in /cpu/classes.
   132  
   133  	/cpu/classes/user:cpu-seconds
   134  		Estimated total CPU time spent running user Go code. This may
   135  		also include some small amount of time spent in the Go runtime.
   136  		This metric is an overestimate, and not directly comparable
   137  		to system CPU time measurements. Compare only with other
   138  		/cpu/classes metrics.
   139  
   140  	/gc/cycles/automatic:gc-cycles
   141  		Count of completed GC cycles generated by the Go runtime.
   142  
   143  	/gc/cycles/forced:gc-cycles
   144  		Count of completed GC cycles forced by the application.
   145  
   146  	/gc/cycles/total:gc-cycles
   147  		Count of all completed GC cycles.
   148  
   149  	/gc/gogc:percent
   150  		Heap size target percentage configured by the user, otherwise
   151  		100. This value is set by the GOGC environment variable, and the
   152  		runtime/debug.SetGCPercent function.
   153  
   154  	/gc/gomemlimit:bytes
   155  		Go runtime memory limit configured by the user, otherwise
   156  		math.MaxInt64. This value is set by the GOMEMLIMIT environment
   157  		variable, and the runtime/debug.SetMemoryLimit function.
   158  
   159  	/gc/heap/allocs-by-size:bytes
   160  		Distribution of heap allocations by approximate size.
   161  		Bucket counts increase monotonically. Note that this does not
   162  		include tiny objects as defined by /gc/heap/tiny/allocs:objects,
   163  		only tiny blocks.
   164  
   165  	/gc/heap/allocs:bytes
   166  		Cumulative sum of memory allocated to the heap by the
   167  		application.
   168  
   169  	/gc/heap/allocs:objects
   170  		Cumulative count of heap allocations triggered by the
   171  		application. Note that this does not include tiny objects as
   172  		defined by /gc/heap/tiny/allocs:objects, only tiny blocks.
   173  
   174  	/gc/heap/frees-by-size:bytes
   175  		Distribution of freed heap allocations by approximate size.
   176  		Bucket counts increase monotonically. Note that this does not
   177  		include tiny objects as defined by /gc/heap/tiny/allocs:objects,
   178  		only tiny blocks.
   179  
   180  	/gc/heap/frees:bytes
   181  		Cumulative sum of heap memory freed by the garbage collector.
   182  
   183  	/gc/heap/frees:objects
   184  		Cumulative count of heap allocations whose storage was freed
   185  		by the garbage collector. Note that this does not include tiny
   186  		objects as defined by /gc/heap/tiny/allocs:objects, only tiny
   187  		blocks.
   188  
   189  	/gc/heap/goal:bytes
   190  		Heap size target for the end of the GC cycle.
   191  
   192  	/gc/heap/live:bytes
   193  		Heap memory occupied by live objects that were marked by the
   194  		previous GC.
   195  
   196  	/gc/heap/objects:objects
   197  		Number of objects, live or unswept, occupying heap memory.
   198  
   199  	/gc/heap/tiny/allocs:objects
   200  		Count of small allocations that are packed together into blocks.
   201  		These allocations are counted separately from other allocations
   202  		because each individual allocation is not tracked by the
   203  		runtime, only their block. Each block is already accounted for
   204  		in allocs-by-size and frees-by-size.
   205  
   206  	/gc/limiter/last-enabled:gc-cycle
   207  		GC cycle the last time the GC CPU limiter was enabled.
   208  		This metric is useful for diagnosing the root cause of an
   209  		out-of-memory error, because the limiter trades memory for CPU
   210  		time when the GC's CPU time gets too high. This is most likely
   211  		to occur with use of SetMemoryLimit. The first GC cycle is cycle
   212  		1, so a value of 0 indicates that it was never enabled.
   213  
   214  	/gc/pauses:seconds
   215  		Deprecated. Prefer the identical /sched/pauses/total/gc:seconds.
   216  
   217  	/gc/scan/globals:bytes
   218  		The total amount of global variable space that is scannable.
   219  
   220  	/gc/scan/heap:bytes
   221  		The total amount of heap space that is scannable.
   222  
   223  	/gc/scan/stack:bytes
   224  		The number of bytes of stack that were scanned last GC cycle.
   225  
   226  	/gc/scan/total:bytes
   227  		The total amount space that is scannable. Sum of all metrics in
   228  		/gc/scan.
   229  
   230  	/gc/stack/starting-size:bytes
   231  		The stack size of new goroutines.
   232  
   233  	/godebug/non-default-behavior/execerrdot:events
   234  		The number of non-default behaviors executed by the os/exec
   235  		package due to a non-default GODEBUG=execerrdot=... setting.
   236  
   237  	/godebug/non-default-behavior/gocachehash:events
   238  		The number of non-default behaviors executed by the cmd/go
   239  		package due to a non-default GODEBUG=gocachehash=... setting.
   240  
   241  	/godebug/non-default-behavior/gocachetest:events
   242  		The number of non-default behaviors executed by the cmd/go
   243  		package due to a non-default GODEBUG=gocachetest=... setting.
   244  
   245  	/godebug/non-default-behavior/gocacheverify:events
   246  		The number of non-default behaviors executed by the cmd/go
   247  		package due to a non-default GODEBUG=gocacheverify=... setting.
   248  
   249  	/godebug/non-default-behavior/gotypesalias:events
   250  		The number of non-default behaviors executed by the go/types
   251  		package due to a non-default GODEBUG=gotypesalias=... setting.
   252  
   253  	/godebug/non-default-behavior/http2client:events
   254  		The number of non-default behaviors executed by the net/http
   255  		package due to a non-default GODEBUG=http2client=... setting.
   256  
   257  	/godebug/non-default-behavior/http2server:events
   258  		The number of non-default behaviors executed by the net/http
   259  		package due to a non-default GODEBUG=http2server=... setting.
   260  
   261  	/godebug/non-default-behavior/httplaxcontentlength:events
   262  		The number of non-default behaviors executed by the net/http
   263  		package due to a non-default GODEBUG=httplaxcontentlength=...
   264  		setting.
   265  
   266  	/godebug/non-default-behavior/httpmuxgo121:events
   267  		The number of non-default behaviors executed by the net/http
   268  		package due to a non-default GODEBUG=httpmuxgo121=... setting.
   269  
   270  	/godebug/non-default-behavior/installgoroot:events
   271  		The number of non-default behaviors executed by the go/build
   272  		package due to a non-default GODEBUG=installgoroot=... setting.
   273  
   274  	/godebug/non-default-behavior/jstmpllitinterp:events
   275  		The number of non-default behaviors executed by
   276  		the html/template package due to a non-default
   277  		GODEBUG=jstmpllitinterp=... setting.
   278  
   279  	/godebug/non-default-behavior/multipartmaxheaders:events
   280  		The number of non-default behaviors executed by
   281  		the mime/multipart package due to a non-default
   282  		GODEBUG=multipartmaxheaders=... setting.
   283  
   284  	/godebug/non-default-behavior/multipartmaxparts:events
   285  		The number of non-default behaviors executed by
   286  		the mime/multipart package due to a non-default
   287  		GODEBUG=multipartmaxparts=... setting.
   288  
   289  	/godebug/non-default-behavior/multipathtcp:events
   290  		The number of non-default behaviors executed by the net package
   291  		due to a non-default GODEBUG=multipathtcp=... setting.
   292  
   293  	/godebug/non-default-behavior/panicnil:events
   294  		The number of non-default behaviors executed by the runtime
   295  		package due to a non-default GODEBUG=panicnil=... setting.
   296  
   297  	/godebug/non-default-behavior/randautoseed:events
   298  		The number of non-default behaviors executed by the math/rand
   299  		package due to a non-default GODEBUG=randautoseed=... setting.
   300  
   301  	/godebug/non-default-behavior/tarinsecurepath:events
   302  		The number of non-default behaviors executed by the archive/tar
   303  		package due to a non-default GODEBUG=tarinsecurepath=...
   304  		setting.
   305  
   306  	/godebug/non-default-behavior/tls10server:events
   307  		The number of non-default behaviors executed by the crypto/tls
   308  		package due to a non-default GODEBUG=tls10server=... setting.
   309  
   310  	/godebug/non-default-behavior/tlsmaxrsasize:events
   311  		The number of non-default behaviors executed by the crypto/tls
   312  		package due to a non-default GODEBUG=tlsmaxrsasize=... setting.
   313  
   314  	/godebug/non-default-behavior/tlsrsakex:events
   315  		The number of non-default behaviors executed by the crypto/tls
   316  		package due to a non-default GODEBUG=tlsrsakex=... setting.
   317  
   318  	/godebug/non-default-behavior/tlsunsafeekm:events
   319  		The number of non-default behaviors executed by the crypto/tls
   320  		package due to a non-default GODEBUG=tlsunsafeekm=... setting.
   321  
   322  	/godebug/non-default-behavior/x509sha1:events
   323  		The number of non-default behaviors executed by the crypto/x509
   324  		package due to a non-default GODEBUG=x509sha1=... setting.
   325  
   326  	/godebug/non-default-behavior/x509usefallbackroots:events
   327  		The number of non-default behaviors executed by the crypto/x509
   328  		package due to a non-default GODEBUG=x509usefallbackroots=...
   329  		setting.
   330  
   331  	/godebug/non-default-behavior/x509usepolicies:events
   332  		The number of non-default behaviors executed by the crypto/x509
   333  		package due to a non-default GODEBUG=x509usepolicies=...
   334  		setting.
   335  
   336  	/godebug/non-default-behavior/zipinsecurepath:events
   337  		The number of non-default behaviors executed by the archive/zip
   338  		package due to a non-default GODEBUG=zipinsecurepath=...
   339  		setting.
   340  
   341  	/memory/classes/heap/free:bytes
   342  		Memory that is completely free and eligible to be returned to
   343  		the underlying system, but has not been. This metric is the
   344  		runtime's estimate of free address space that is backed by
   345  		physical memory.
   346  
   347  	/memory/classes/heap/objects:bytes
   348  		Memory occupied by live objects and dead objects that have not
   349  		yet been marked free by the garbage collector.
   350  
   351  	/memory/classes/heap/released:bytes
   352  		Memory that is completely free and has been returned to the
   353  		underlying system. This metric is the runtime's estimate of free
   354  		address space that is still mapped into the process, but is not
   355  		backed by physical memory.
   356  
   357  	/memory/classes/heap/stacks:bytes
   358  		Memory allocated from the heap that is reserved for stack space,
   359  		whether or not it is currently in-use. Currently, this
   360  		represents all stack memory for goroutines. It also includes all
   361  		OS thread stacks in non-cgo programs. Note that stacks may be
   362  		allocated differently in the future, and this may change.
   363  
   364  	/memory/classes/heap/unused:bytes
   365  		Memory that is reserved for heap objects but is not currently
   366  		used to hold heap objects.
   367  
   368  	/memory/classes/metadata/mcache/free:bytes
   369  		Memory that is reserved for runtime mcache structures, but not
   370  		in-use.
   371  
   372  	/memory/classes/metadata/mcache/inuse:bytes
   373  		Memory that is occupied by runtime mcache structures that are
   374  		currently being used.
   375  
   376  	/memory/classes/metadata/mspan/free:bytes
   377  		Memory that is reserved for runtime mspan structures, but not
   378  		in-use.
   379  
   380  	/memory/classes/metadata/mspan/inuse:bytes
   381  		Memory that is occupied by runtime mspan structures that are
   382  		currently being used.
   383  
   384  	/memory/classes/metadata/other:bytes
   385  		Memory that is reserved for or used to hold runtime metadata.
   386  
   387  	/memory/classes/os-stacks:bytes
   388  		Stack memory allocated by the underlying operating system.
   389  		In non-cgo programs this metric is currently zero. This may
   390  		change in the future.In cgo programs this metric includes
   391  		OS thread stacks allocated directly from the OS. Currently,
   392  		this only accounts for one stack in c-shared and c-archive build
   393  		modes, and other sources of stacks from the OS are not measured.
   394  		This too may change in the future.
   395  
   396  	/memory/classes/other:bytes
   397  		Memory used by execution trace buffers, structures for debugging
   398  		the runtime, finalizer and profiler specials, and more.
   399  
   400  	/memory/classes/profiling/buckets:bytes
   401  		Memory that is used by the stack trace hash map used for
   402  		profiling.
   403  
   404  	/memory/classes/total:bytes
   405  		All memory mapped by the Go runtime into the current process
   406  		as read-write. Note that this does not include memory mapped
   407  		by code called via cgo or via the syscall package. Sum of all
   408  		metrics in /memory/classes.
   409  
   410  	/sched/gomaxprocs:threads
   411  		The current runtime.GOMAXPROCS setting, or the number of
   412  		operating system threads that can execute user-level Go code
   413  		simultaneously.
   414  
   415  	/sched/goroutines:goroutines
   416  		Count of live goroutines.
   417  
   418  	/sched/latencies:seconds
   419  		Distribution of the time goroutines have spent in the scheduler
   420  		in a runnable state before actually running. Bucket counts
   421  		increase monotonically.
   422  
   423  	/sched/pauses/stopping/gc:seconds
   424  		Distribution of individual GC-related stop-the-world stopping
   425  		latencies. This is the time it takes from deciding to stop the
   426  		world until all Ps are stopped. This is a subset of the total
   427  		GC-related stop-the-world time (/sched/pauses/total/gc:seconds).
   428  		During this time, some threads may be executing. Bucket counts
   429  		increase monotonically.
   430  
   431  	/sched/pauses/stopping/other:seconds
   432  		Distribution of individual non-GC-related stop-the-world
   433  		stopping latencies. This is the time it takes from deciding
   434  		to stop the world until all Ps are stopped. This is a
   435  		subset of the total non-GC-related stop-the-world time
   436  		(/sched/pauses/total/other:seconds). During this time, some
   437  		threads may be executing. Bucket counts increase monotonically.
   438  
   439  	/sched/pauses/total/gc:seconds
   440  		Distribution of individual GC-related stop-the-world pause
   441  		latencies. This is the time from deciding to stop the world
   442  		until the world is started again. Some of this time is spent
   443  		getting all threads to stop (this is measured directly in
   444  		/sched/pauses/stopping/gc:seconds), during which some threads
   445  		may still be running. Bucket counts increase monotonically.
   446  
   447  	/sched/pauses/total/other:seconds
   448  		Distribution of individual non-GC-related stop-the-world
   449  		pause latencies. This is the time from deciding to stop the
   450  		world until the world is started again. Some of this time
   451  		is spent getting all threads to stop (measured directly in
   452  		/sched/pauses/stopping/other:seconds). Bucket counts increase
   453  		monotonically.
   454  
   455  	/sync/mutex/wait/total:seconds
   456  		Approximate cumulative time goroutines have spent blocked on a
   457  		sync.Mutex, sync.RWMutex, or runtime-internal lock. This metric
   458  		is useful for identifying global changes in lock contention.
   459  		Collect a mutex or block profile using the runtime/pprof package
   460  		for more detailed contention data.
   461  */
   462  package metrics
   463  

View as plain text