Semantic conventions for Go runtime metrics

Status: Development

This document describes semantic conventions for Go runtime metrics in OpenTelemetry. These metrics are obtained from Go’s runtime/metrics package.

• Go memory
  • Metric: go.memory.used
  • Metric: go.memory.limit
  • Metric: go.memory.allocated
  • Metric: go.memory.allocations
• Go garbage collection
  • Metric: go.memory.gc.goal
  • Metric: go.memory.gc.cycles
  • Metric: go.memory.gc.pause.duration
• Go CPU
  • Metric: go.cpu.time
• Go goroutines
  • Metric: go.goroutine.count
• Go processor
  • Metric: go.processor.limit
• Go scheduler
  • Metric: go.schedule.duration
• Go runtime configuration
  • Metric: go.config.gogc

Go memory

Description: Go runtime metrics captured under the namespace go.memory.*

Metric: go.memory.used

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
go.memory.used	UpDownCounter	By	Memory used by the Go runtime. [1]

[1]: Computed from (/memory/classes/total:bytes - /memory/classes/heap/released:bytes).

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
go.memory.type		Recommended	string	The type of memory.	other; stack
go.memory.detailed_type		Opt-In	string	The detailed type of memory. [1]	heap/objects; heap/free

[1] go.memory.detailed_type: Value SHOULD match the specific memory class reported by the Go runtime under /memory/classes/.... The list of possible values is subject to change with the Go version used.

go.memory.type has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

Value	Description	Stability
other	Memory used by the Go runtime, excluding other categories of memory usage described in this enumeration.
stack	Memory allocated from the heap that is reserved for stack space, whether or not it is currently in-use. [2]

[2]: Computed from /memory/classes/heap/stacks:bytes.

As of Go 1.26, the go.memory.detailed_type attribute has the following relationship to the go.memory.type attribute. Values for go.memory.detailed_type are subject to change with the Go version used:

Metric: go.memory.limit

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
go.memory.limit	UpDownCounter	By	Go runtime memory limit configured by the user, if a limit exists. [1]

[1]: Computed from /gc/gomemlimit:bytes. This metric is excluded if the limit obtained from the Go runtime is math.MaxInt64.

Metric: go.memory.allocated

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
go.memory.allocated	Counter	By	Memory allocated to the heap by the application. [1]

[1]: Computed from /gc/heap/allocs:bytes.

Metric: go.memory.allocations

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
go.memory.allocations	Counter	{allocation}	Count of allocations to the heap by the application. [1]

[1]: Computed from /gc/heap/allocs:objects.

Go garbage collection

Description: Go metrics captured under the namespace go.memory.gc.*

Metric: go.memory.gc.goal

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
go.memory.gc.goal	UpDownCounter	By	Heap size target for the end of the GC cycle. [1]

[1]: Computed from /gc/heap/goal:bytes.

Metric: go.memory.gc.cycles

This metric is opt-in.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
go.memory.gc.cycles	Counter	{gc_cycle}	Number of completed GC cycles. [1]

[1]: Computed from /gc/cycles/total:gc-cycles.

Metric: go.memory.gc.pause.duration

This metric is opt-in.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
go.memory.gc.pause.duration	Histogram	s	Distribution of individual GC-related stop-the-world pause latencies. This is the time from deciding to stop the world until the world is started again. [1]

[1]: Computed from /sched/pauses/total/gc:seconds. Bucket boundaries are provided by the runtime, and are subject to change.

Go CPU

Description: Go runtime metrics captured under the namespace go.cpu.*

Metric: go.cpu.time

This metric is opt-in.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
go.cpu.time	Counter	s	Estimated CPU time spent by the Go runtime. [1]

[1]: Computed from /cpu/classes/... metrics. This metric is an overestimate, and not directly comparable to system CPU time measurements. Compare only with other go.cpu.time metrics.

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
go.cpu.state		Required	string	The state of the CPU.	user; gc
go.cpu.detailed_state		Opt-In	string	The detailed state of the CPU. [1]	gc/pause; gc/mark/assist

[1] go.cpu.detailed_state: Value SHOULD match the specific CPU class reported by the Go runtime under /cpu/classes/.... The list of possible values is subject to change with the Go version used.

go.cpu.state has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

Value	Description	Stability
gc	CPU time spent performing garbage collection tasks.
idle	Available CPU time not spent executing any Go or Go runtime code.
scavenge	CPU time spent returning unused memory to the underlying platform.
user	CPU time spent running user Go code.

As of Go 1.26, the go.cpu.detailed_state attribute has the following relationship to the go.cpu.state attribute. Values for go.cpu.detailed_state are subject to change with the Go version used:

Go goroutines

Description: Go metrics captured under the namespace go.goroutine.*

Metric: go.goroutine.count

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
go.goroutine.count	UpDownCounter	{goroutine}	Count of live goroutines. [1]

[1]: Computed from /sched/goroutines:goroutines.

Go processor

Description: Go metrics captured under the namespace go.processor.*

Metric: go.processor.limit

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
go.processor.limit	UpDownCounter	{thread}	The number of OS threads that can execute user-level Go code simultaneously. [1]

[1]: Computed from /sched/gomaxprocs:threads.

Go scheduler

Description: Go metrics captured under the namespace go.schedule.*

Metric: go.schedule.duration

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
go.schedule.duration	Histogram	s	The time goroutines have spent in the scheduler in a runnable state before actually running. [1]

[1]: Computed from /sched/latencies:seconds. Bucket boundaries are provided by the runtime, and are subject to change.

Go runtime configuration

Description: Go metrics captured under the namespace go.config.*

Metric: go.config.gogc

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
go.config.gogc	UpDownCounter	%	Heap size target percentage configured by the user, otherwise 100. [1]

[1]: The value range is [0.0,100.0]. Computed from /gc/gogc:percent.